studio-admin-fe/docs/admin-fe-architecture-and-flow-v0.1.0.md

Studio Admin FE 구성과 운영 흐름

문서 버전: 0.1.0
기준 앱 버전: 0.1.0
기준일: 2026-07-03

개요

Studio Admin FE는 스튜디오 플랫폼 운영 콘솔이다. 런처, 어플리케이션, 실행 설정, 배포, 마이그레이션, 사용자/라이센스/공지 관리를 한 화면에서 처리한다.

프론트엔드는 Vite + React 기반이며, API 호출은 VITE_API_BASE_URL 기준의 Admin BE로 전달된다. 인증 토큰은 localStorage의 studio-admin-token을 사용하고, 401 응답이 오면 세션을 지우고 로그인 만료 이벤트를 발생시킨다.

주요 환경변수

VITE_API_BASE_URL              Admin BE API 주소
VITE_GITEA_BASE_URL            Gitea 웹 주소
VITE_GITEA_SSH_BASE_URL        Gitea SSH clone 주소
VITE_GITEA_APP_ORG             앱 저장소 기본 조직
VITE_R2_PUBLIC_BASE_URL        R2 공개 다운로드 base URL
VITE_R2_ARTIFACT_PREFIX        R2 artifact prefix, 기본 studio-artifacts

라우팅과 메뉴

메뉴 정의는 src/layout/navigation.ts에 있다. 실제 화면 매핑은 src/App.tsx의 pathByView와 viewByPath에서 관리한다.

주요 메뉴:

대시보드

런처
- 소스 관리
- 빌드 관리
- 버전 관리
- 구성요소
- 공통 설정
- 앱 연결

어플리케이션
- 앱 관리
- 소스 관리
- 빌드 관리
- 릴리즈 관리
- 실행 설정
- 배포 관리
- 마이그레이션
- 로그/이벤트

운영
- 관리자 관리
- 사용자/세션
- 라이센스
- 공지사항

API 호출 구조

공통 API 유틸은 src/lib/api.ts에 있다.

apiBaseUrl = VITE_API_BASE_URL || http://localhost:4500/api
apiRequest(path) -> `${apiBaseUrl}${path}`
Authorization -> localStorage studio-admin-token
401 -> clearAdminSession + studio-admin-auth-expired event

도메인별 API 래퍼:

src/pages/launcher/launcher-api.ts          런처 소스/빌드/버전/앱 연결/공통 설정
src/pages/applications/application-api.ts   앱/구성요소/소스/빌드/릴리즈/배포/마이그레이션
src/pages/runtime/runtime-api.ts            실행 설정, namespace 리소스, 로그, scale/restart
src/pages/operations/operations-api.ts      관리자, 사용자 세션, 라이센스, 공지사항

런처 관리 흐름

소스 관리

런처 클라이언트와 백엔드 소스 저장소를 나눠 관리한다.

클라이언트 저장소 -> Electron 런처 .deb 빌드
백엔드 저장소     -> 런처 백엔드 컨테이너 이미지 빌드

관련 API:

GET   /launcher/source
PATCH /launcher/source
GET   /gitea/repos?owner=platform
GET   /gitea/repos?owner=studio

빌드 관리

런처 빌드는 클라이언트/백엔드로 나뉜다.

클라이언트 빌드:

1. 저장소 clone
2. branch/commit checkout
3. npm ci && npm run build:linux
4. 생성된 .deb 탐색
5. package.json version과 실제 .deb 파일명 기준으로 R2 key/download URL 확정
6. R2 업로드
7. latest deb/install.sh 갱신

백엔드 빌드:

1. 저장소 clone
2. branch/commit checkout
3. package.json version 확인
4. docker build
5. docker push

현재 정책상 런처 클라이언트 버전은 화면 입력값이 아니라 소스의 package.json 버전을 최종 기준으로 사용한다.

버전 관리

런처 앱 업데이트 API가 바라보는 최신 런처 버전 정보를 관리한다.

관리 값:

version
minimumVersion
artifact
downloadUrl
releaseNotes
repository
branch
commitSha
isActive

앱 연결

Admin 앱/릴리즈를 런처 앱 목록에 연결한다. 런처에서 사용자가 보는 앱 목록, 표시 순서, 실행 경로, 동영상, 아이콘 키, 활성 여부를 관리한다.

주요 값:

appId
releaseId
displayOrder
isEnabled
displayName
description
subtitle
detailUrl
videoPath
iconKey
launchUrl
devAppPath
execPath
artifact

어플리케이션 관리 흐름

앱 관리

앱과 구성요소를 등록한다.

앱 주요 값:

key
name
description
namespace
status

구성요소 주요 값:

name
type
repository
branch
buildTarget
imageSource
externalImage
workloadType
replicas
serviceType
storageEnabled
ports

구성요소는 빌드 대상과 런타임 배포 대상의 기본 단위다.

소스 관리

구성요소별 Gitea 저장소와 브랜치를 연결한다.

앱 구성요소 -> repository/branch/buildTarget 연결

빌드 관리

구성요소별 빌드 작업을 만든다.

빌드 타입은 구성요소 설정에 따라 달라진다.

container-image -> docker build/push
artifact        -> AppImage/deb 등 산출물 빌드 후 R2 업로드
migration       -> 마이그레이션 이미지/작업에 사용

앱 artifact 빌드는 런처와 달리 빌드 후 package.json version을 읽어 R2 경로에 반영한다.

릴리즈 관리

빌드 결과를 묶어 앱 릴리즈를 생성한다.

앱 선택
버전 입력
브랜치 선택
빌드 결과 선택
릴리즈 생성

최근 수정 기준:

이미 릴리즈에 사용된 빌드 결과는 후보에서 제외
최근 빌드 결과 위주로 기본 선택
빌드 산출물에서 버전 정보 표시

실행 설정

런타임 프로필을 만든다. 실제 배포 환경 차이는 이 프로필에 많이 담긴다.

프로필 기본 값:

appId
name
environment: dev 또는 prod
namespace

프로필에 포함되는 값:

환경변수
시크릿
Ingress rule
componentId
host
path
servicePort
stripPrefix
tlsEnabled
tlsSecretName

적용을 누르면 Admin BE가 Kubernetes 리소스를 생성/갱신한다.

배포 관리

생성된 릴리즈를 namespace에 배포한다.

입력 값:

releaseId
environment: dev 또는 prod
namespace
updateLauncherAppVersion

현재 environment는 주로 배포 이력의 분류 라벨이다. 실제 리소스 차이는 namespace, 실행 설정, env/secret, ingress, image/artifact로 결정된다.

같은 namespace와 같은 구성요소에 다른 버전을 배포하면 기존 Pod/리소스는 새 버전으로 교체된다. 다른 namespace에 배포하면 버전별/환경별 병행 운영이 가능하다.

마이그레이션

릴리즈와 마이그레이션 구성요소를 기준으로 Kubernetes Job을 실행한다.

주요 입력:

releaseId
migrationComponentId
imageComponentName
namespace
command
envSecretName

운영 관리 흐름

관리자 관리

관리자 계정, 역할, 활성화 상태, 임시 비밀번호, SSH 키를 관리한다.

사용자/세션

런처/공통 인증 사용자 세션을 조회하고, 사용자 잠금/잠금 해제와 세션 종료를 수행한다.

라이센스

라이센스 플랜과 사용자 앱 권한을 관리한다. 런처에서 앱 목록이 사용자별로 다르게 보이는 근거가 된다.

공지사항

런처 로그인 또는 앱별 공지사항을 관리한다.

공지 주요 값:

appKey
title
body
linkUrl
isActive
startsAt
endsAt
priority

현재 운영상 주의점

빌드 버전

런처 클라이언트와 앱 artifact는 package.json 버전을 기준으로 산출물 버전/R2 경로를 맞추는 방향이 맞다. 배포 대상 변경 시 package version도 같이 올려야 한다.

배포 환경

dev/prod 셀렉트는 현재 분류값이다. 실제 분리는 namespace와 실행 설정 프로필로 한다.

추천 예:

dev  -> stdo-lms-dev
prod -> stdo-lms

같은 태그 이미지

같은 Docker 태그를 다시 push하면 로컬/레지스트리에는 이전 이미지 레이어가 남을 수 있다. Kubernetes도 같은 태그만으로는 항상 Pod를 재시작하지 않는다. 명확한 재배포가 필요하면 rollout restart 또는 버전 태그 변경이 필요하다.

런처 업데이트

런처 업데이트 후에는 기존 프로세스를 완전히 종료하고 새 프로세스로 재실행해야 한다. 그렇지 않으면 업데이트 직후 AppImage 실행 환경이 꼬일 수 있다.

관련 파일

src/App.tsx
src/layout/navigation.ts
src/lib/api.ts
src/pages/launcher/launcher-api.ts
src/pages/applications/application-api.ts
src/pages/runtime/runtime-api.ts
src/pages/operations/operations-api.ts
src/types/application.ts
src/types/runtime.ts