This commit is contained in:
@@ -0,0 +1,374 @@
|
||||
# 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 응답이 오면 세션을 지우고 로그인 만료 이벤트를 발생시킨다.
|
||||
|
||||
## 주요 환경변수
|
||||
|
||||
```text
|
||||
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`에서 관리한다.
|
||||
|
||||
주요 메뉴:
|
||||
|
||||
```text
|
||||
대시보드
|
||||
|
||||
런처
|
||||
- 소스 관리
|
||||
- 빌드 관리
|
||||
- 버전 관리
|
||||
- 구성요소
|
||||
- 공통 설정
|
||||
- 앱 연결
|
||||
|
||||
어플리케이션
|
||||
- 앱 관리
|
||||
- 소스 관리
|
||||
- 빌드 관리
|
||||
- 릴리즈 관리
|
||||
- 실행 설정
|
||||
- 배포 관리
|
||||
- 마이그레이션
|
||||
- 로그/이벤트
|
||||
|
||||
운영
|
||||
- 관리자 관리
|
||||
- 사용자/세션
|
||||
- 라이센스
|
||||
- 공지사항
|
||||
```
|
||||
|
||||
## API 호출 구조
|
||||
|
||||
공통 API 유틸은 `src/lib/api.ts`에 있다.
|
||||
|
||||
```text
|
||||
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 래퍼:
|
||||
|
||||
```text
|
||||
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 관리자, 사용자 세션, 라이센스, 공지사항
|
||||
```
|
||||
|
||||
## 런처 관리 흐름
|
||||
|
||||
### 소스 관리
|
||||
|
||||
런처 클라이언트와 백엔드 소스 저장소를 나눠 관리한다.
|
||||
|
||||
```text
|
||||
클라이언트 저장소 -> Electron 런처 .deb 빌드
|
||||
백엔드 저장소 -> 런처 백엔드 컨테이너 이미지 빌드
|
||||
```
|
||||
|
||||
관련 API:
|
||||
|
||||
```text
|
||||
GET /launcher/source
|
||||
PATCH /launcher/source
|
||||
GET /gitea/repos?owner=platform
|
||||
GET /gitea/repos?owner=studio
|
||||
```
|
||||
|
||||
### 빌드 관리
|
||||
|
||||
런처 빌드는 클라이언트/백엔드로 나뉜다.
|
||||
|
||||
클라이언트 빌드:
|
||||
|
||||
```text
|
||||
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 갱신
|
||||
```
|
||||
|
||||
백엔드 빌드:
|
||||
|
||||
```text
|
||||
1. 저장소 clone
|
||||
2. branch/commit checkout
|
||||
3. package.json version 확인
|
||||
4. docker build
|
||||
5. docker push
|
||||
```
|
||||
|
||||
현재 정책상 런처 클라이언트 버전은 화면 입력값이 아니라 소스의 `package.json` 버전을 최종 기준으로 사용한다.
|
||||
|
||||
### 버전 관리
|
||||
|
||||
런처 앱 업데이트 API가 바라보는 최신 런처 버전 정보를 관리한다.
|
||||
|
||||
관리 값:
|
||||
|
||||
```text
|
||||
version
|
||||
minimumVersion
|
||||
artifact
|
||||
downloadUrl
|
||||
releaseNotes
|
||||
repository
|
||||
branch
|
||||
commitSha
|
||||
isActive
|
||||
```
|
||||
|
||||
### 앱 연결
|
||||
|
||||
Admin 앱/릴리즈를 런처 앱 목록에 연결한다. 런처에서 사용자가 보는 앱 목록, 표시 순서, 실행 경로, 동영상, 아이콘 키, 활성 여부를 관리한다.
|
||||
|
||||
주요 값:
|
||||
|
||||
```text
|
||||
appId
|
||||
releaseId
|
||||
displayOrder
|
||||
isEnabled
|
||||
displayName
|
||||
description
|
||||
subtitle
|
||||
detailUrl
|
||||
videoPath
|
||||
iconKey
|
||||
launchUrl
|
||||
devAppPath
|
||||
execPath
|
||||
artifact
|
||||
```
|
||||
|
||||
## 어플리케이션 관리 흐름
|
||||
|
||||
### 앱 관리
|
||||
|
||||
앱과 구성요소를 등록한다.
|
||||
|
||||
앱 주요 값:
|
||||
|
||||
```text
|
||||
key
|
||||
name
|
||||
description
|
||||
namespace
|
||||
status
|
||||
```
|
||||
|
||||
구성요소 주요 값:
|
||||
|
||||
```text
|
||||
name
|
||||
type
|
||||
repository
|
||||
branch
|
||||
buildTarget
|
||||
imageSource
|
||||
externalImage
|
||||
workloadType
|
||||
replicas
|
||||
serviceType
|
||||
storageEnabled
|
||||
ports
|
||||
```
|
||||
|
||||
구성요소는 빌드 대상과 런타임 배포 대상의 기본 단위다.
|
||||
|
||||
### 소스 관리
|
||||
|
||||
구성요소별 Gitea 저장소와 브랜치를 연결한다.
|
||||
|
||||
```text
|
||||
앱 구성요소 -> repository/branch/buildTarget 연결
|
||||
```
|
||||
|
||||
### 빌드 관리
|
||||
|
||||
구성요소별 빌드 작업을 만든다.
|
||||
|
||||
빌드 타입은 구성요소 설정에 따라 달라진다.
|
||||
|
||||
```text
|
||||
container-image -> docker build/push
|
||||
artifact -> AppImage/deb 등 산출물 빌드 후 R2 업로드
|
||||
migration -> 마이그레이션 이미지/작업에 사용
|
||||
```
|
||||
|
||||
앱 artifact 빌드는 런처와 달리 빌드 후 `package.json` version을 읽어 R2 경로에 반영한다.
|
||||
|
||||
### 릴리즈 관리
|
||||
|
||||
빌드 결과를 묶어 앱 릴리즈를 생성한다.
|
||||
|
||||
```text
|
||||
앱 선택
|
||||
버전 입력
|
||||
브랜치 선택
|
||||
빌드 결과 선택
|
||||
릴리즈 생성
|
||||
```
|
||||
|
||||
최근 수정 기준:
|
||||
|
||||
```text
|
||||
이미 릴리즈에 사용된 빌드 결과는 후보에서 제외
|
||||
최근 빌드 결과 위주로 기본 선택
|
||||
빌드 산출물에서 버전 정보 표시
|
||||
```
|
||||
|
||||
### 실행 설정
|
||||
|
||||
런타임 프로필을 만든다. 실제 배포 환경 차이는 이 프로필에 많이 담긴다.
|
||||
|
||||
프로필 기본 값:
|
||||
|
||||
```text
|
||||
appId
|
||||
name
|
||||
environment: dev 또는 prod
|
||||
namespace
|
||||
```
|
||||
|
||||
프로필에 포함되는 값:
|
||||
|
||||
```text
|
||||
환경변수
|
||||
시크릿
|
||||
Ingress rule
|
||||
componentId
|
||||
host
|
||||
path
|
||||
servicePort
|
||||
stripPrefix
|
||||
tlsEnabled
|
||||
tlsSecretName
|
||||
```
|
||||
|
||||
`적용`을 누르면 Admin BE가 Kubernetes 리소스를 생성/갱신한다.
|
||||
|
||||
### 배포 관리
|
||||
|
||||
생성된 릴리즈를 namespace에 배포한다.
|
||||
|
||||
입력 값:
|
||||
|
||||
```text
|
||||
releaseId
|
||||
environment: dev 또는 prod
|
||||
namespace
|
||||
updateLauncherAppVersion
|
||||
```
|
||||
|
||||
현재 `environment`는 주로 배포 이력의 분류 라벨이다. 실제 리소스 차이는 namespace, 실행 설정, env/secret, ingress, image/artifact로 결정된다.
|
||||
|
||||
같은 namespace와 같은 구성요소에 다른 버전을 배포하면 기존 Pod/리소스는 새 버전으로 교체된다. 다른 namespace에 배포하면 버전별/환경별 병행 운영이 가능하다.
|
||||
|
||||
### 마이그레이션
|
||||
|
||||
릴리즈와 마이그레이션 구성요소를 기준으로 Kubernetes Job을 실행한다.
|
||||
|
||||
주요 입력:
|
||||
|
||||
```text
|
||||
releaseId
|
||||
migrationComponentId
|
||||
imageComponentName
|
||||
namespace
|
||||
command
|
||||
envSecretName
|
||||
```
|
||||
|
||||
## 운영 관리 흐름
|
||||
|
||||
### 관리자 관리
|
||||
|
||||
관리자 계정, 역할, 활성화 상태, 임시 비밀번호, SSH 키를 관리한다.
|
||||
|
||||
### 사용자/세션
|
||||
|
||||
런처/공통 인증 사용자 세션을 조회하고, 사용자 잠금/잠금 해제와 세션 종료를 수행한다.
|
||||
|
||||
### 라이센스
|
||||
|
||||
라이센스 플랜과 사용자 앱 권한을 관리한다. 런처에서 앱 목록이 사용자별로 다르게 보이는 근거가 된다.
|
||||
|
||||
### 공지사항
|
||||
|
||||
런처 로그인 또는 앱별 공지사항을 관리한다.
|
||||
|
||||
공지 주요 값:
|
||||
|
||||
```text
|
||||
appKey
|
||||
title
|
||||
body
|
||||
linkUrl
|
||||
isActive
|
||||
startsAt
|
||||
endsAt
|
||||
priority
|
||||
```
|
||||
|
||||
## 현재 운영상 주의점
|
||||
|
||||
### 빌드 버전
|
||||
|
||||
런처 클라이언트와 앱 artifact는 `package.json` 버전을 기준으로 산출물 버전/R2 경로를 맞추는 방향이 맞다. 배포 대상 변경 시 package version도 같이 올려야 한다.
|
||||
|
||||
### 배포 환경
|
||||
|
||||
`dev/prod` 셀렉트는 현재 분류값이다. 실제 분리는 namespace와 실행 설정 프로필로 한다.
|
||||
|
||||
추천 예:
|
||||
|
||||
```text
|
||||
dev -> stdo-lms-dev
|
||||
prod -> stdo-lms
|
||||
```
|
||||
|
||||
### 같은 태그 이미지
|
||||
|
||||
같은 Docker 태그를 다시 push하면 로컬/레지스트리에는 이전 이미지 레이어가 남을 수 있다. Kubernetes도 같은 태그만으로는 항상 Pod를 재시작하지 않는다. 명확한 재배포가 필요하면 rollout restart 또는 버전 태그 변경이 필요하다.
|
||||
|
||||
### 런처 업데이트
|
||||
|
||||
런처 업데이트 후에는 기존 프로세스를 완전히 종료하고 새 프로세스로 재실행해야 한다. 그렇지 않으면 업데이트 직후 AppImage 실행 환경이 꼬일 수 있다.
|
||||
|
||||
## 관련 파일
|
||||
|
||||
```text
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user