ivada-infra/DOCS

Fork 0

happybell80 1610103c46 docs: Add admin dashboard standard deployment refactoring (2025-11-17)

2025-11-17 18:12:58 +09:00

3.6 KiB

Raw Blame History

Admin Dashboard 표준 배포 방식 전환 및 구조 리팩토링

날짜: 2025-11-17 작성자: admin 관련 파일:

admin-dashboard/docker-compose.yml
admin-dashboard/backend/main.py
admin-dashboard/frontend/
robeing-gateway/app/main.py
nginx-infra/server-nginx-default

문제 상황

1. 비표준 배포 방식

FastAPI 백엔드가 정적 HTML 파일을 FileResponse로 서빙
표준 방식(nginx 직접 서빙)과 불일치
frontend-customer는 이미 표준 방식으로 전환 완료

2. 폴더 구조 혼란

frontend-base 폴더명이 역할을 명확히 표현하지 않음
admin-ui 폴더명이 frontend보다 덜 직관적

3. Gateway JWT 검증 문제

/admin 라우팅에서 JWT 검증을 필수로 하면, JWT가 없는 사용자는 401로 HTML을 받지 못해 로그인 페이지를 볼 수 없음

4. 토큰 불일치

frontend-base가 adminToken을 사용하나, Gateway는 표준 JWT(auth_token)를 기대

해결 방안

1. 구조 변경

폴더 리네임:

frontend-base → admin-dashboard
admin-ui → frontend

최종 구조:

admin-dashboard/
├── backend/          # FastAPI 서버 (API만 처리)
├── frontend/         # React + Tailwind + shadcn + Vite
└── docker-compose.yml

2. 표준 배포 방식 채택

nginx 설정 (nginx-infra/server-nginx-default):

location /admin {
    root /home/admin/admin-dashboard/frontend/dist;
    try_files $uri $uri/ /index.html;
}

권한 설정:

sudo chmod o+x /home
sudo chmod o+x /home/admin

빌드 및 배포:

Vite로 npm run build 실행 → dist/ 폴더 생성
nginx가 /home/admin/admin-dashboard/frontend/dist/ 직접 서빙
FastAPI는 API만 처리 (/admin/api/*)

3. Gateway JWT 검증 수정

robeing-gateway/app/main.py - JWT 검증을 선택적으로 처리:

@app.api_route("/admin/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def admin_proxy(
    path: str,
    request: Request,
    user_uuid: Optional[str] = Depends(get_verified_user_optional)  # 선택적
):
    # JWT가 없어도 HTML 반환, frontend JavaScript가 로그인 페이지 표시

4. 토큰 통일

frontend/index.html - adminToken → auth_token으로 변경:

// Before: localStorage.setItem('adminToken', token)
// After:
localStorage.setItem('auth_token', token)

구현 완료

커밋: 진행 중 일시: 2025-11-17 브랜치: main

변경 사항:

admin-dashboard/docker-compose.yml: 컨테이너명, 볼륨 경로 수정
admin-dashboard/backend/main.py: frontend 경로 수정
admin-dashboard/README.md: 구조 설명 업데이트
Git 원격 저장소: admin-dashboard.git로 변경

교훈

표준 방식의 중요성

nginx가 정적 파일을 직접 서빙하는 것이 성능과 보안 측면에서 최적
FastAPI는 API 처리에 집중, 정적 파일 서빙은 웹서버가 담당
참고: 250717_happybell80_auth서버구축및정적빌드배포전환.md

폴더 구조 명확성

프로젝트명은 역할을 명확히 표현해야 함 (admin-dashboard)
frontend가 admin-ui보다 직관적이고 표준적

JWT 검증 전략

HTML은 공개되어도 되고, 실제 데이터 API는 별도로 JWT 검증
Gateway는 HTML 요청은 통과시키고, API 요청만 검증하는 선택적 검증 필요

토큰 통일

프로젝트 전체에서 표준 JWT 키(auth_token) 사용으로 일관성 확보
Gateway와 frontend 간 토큰 키 불일치 방지

3.6 KiB Raw Blame History