ivada-infra/DOCS

Fork 0

happybell80 50e9ad884c docs: Update admin dashboard routing doc - link to standard deployment refactoring

2025-11-17 18:15:24 +09:00

4.4 KiB

Raw Permalink Blame History

Admin Dashboard 라우팅 구현 (Gateway 프록시 패턴)

날짜: 2025-11-17
작업자: Claude (51123 서버 관리자)
관련 서버: 51123
관련 서비스: robeing-gateway, frontend-base, nginx

배경

사용자가 https://ro-being.com/admin으로 관리자 대시보드 접근 시 빈 페이지가 표시되는 문제 발생.

초기 상태

nginx: /admin → localhost:8100 (robeing-gateway)
robeing-gateway: /admin 라우팅 없음 → 404 반환
frontend-base: localhost:8000에서 실행 중, /admin UI 제공

문제 원인

robeing-gateway는 로빙 API 라우팅 전용으로 설계되어 /admin 경로를 처리하지 않음.

해결 방안 검토

참고: 이 문서는 초기 구현 방식을 기록한 것이며, 이후 표준 배포 방식으로 전환되었습니다. 최신 구현 방식은 다음 문서를 참고하세요:

표준 배포 방식 전환: 251117_admin_dashboard_standard_deployment_refactoring.md

초기 구현 (폐기됨)

Gateway가 frontend-base(localhost:8000)로 프록시하는 방식
FastAPI가 정적 HTML을 FileResponse로 서빙

최종 채택 방식

nginx가 정적 파일(/home/admin/admin-dashboard/frontend/dist/)을 직접 서빙
FastAPI는 API만 처리
Gateway는 JWT 검증을 선택적으로 처리하여 HTML은 통과, API만 검증

구현 내역 (초기 구현 - 폐기됨)

이 문서는 초기 구현 방식을 기록한 것이며, 이후 표준 배포 방식으로 전환되었습니다.

초기 구현 내용:

Gateway에 /admin 라우팅 추가하여 frontend-base로 프록시
FastAPI가 정적 HTML을 FileResponse로 서빙

최신 구현: 251117_admin_dashboard_standard_deployment_refactoring.md 참고

아키텍처 플로우

Before (404 에러)

사용자 → nginx → robeing-gateway → 404 (라우팅 없음)

After (초기 구현 - 폐기됨)

사용자 → nginx (:80/443) → robeing-gateway (:8100)
         ↓ JWT 검증
         ↓ user_uuid 추출
         → frontend-base (:8000) → Admin UI 반환

최신 아키텍처: 251117_admin_dashboard_standard_deployment_refactoring.md 참고

검증

1. Gateway 상태

docker ps --filter "name=robeing-gateway"
# 출력: Up X seconds (healthy)

2. 엔드포인트 테스트

# JWT 없이 (401 예상)
curl http://localhost:8100/admin
# {"detail":"Missing or invalid authorization header"}

# JWT 포함 (200 OK, HTML 반환)
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8100/admin
# <!DOCTYPE html>...

3. 브라우저 테스트

URL: https://ro-being.com/admin
예상: Admin Dashboard UI 표시
JWT 자동 포함 (localStorage에서)

설계 원칙 (Gateway Proxy Pattern)

Gateway의 역할 (중앙집중형)

JWT 검증: 모든 요청의 인증 게이트웨이
Username → UUID 변환: DB 조회 및 캐싱
라우팅:
- /api/chat → 로빙 서비스 (rb8001, rb10508 등)
- /api/stats → robeing-monitor (51124:9024)
- /api/items → robeing-monitor
- /admin → frontend-base (51123:8000)

역할 분리 (초기 설계 - 이후 변경됨)

robeing-gateway: 인증 + 라우팅 (코드 없는 프록시)
frontend-base: 관리자 UI + 시스템 메트릭 대시보드 (→ admin-dashboard로 변경)
robeing-monitor: 로빙 통계, 아이템 관리 (51124)

최신 구조: 251117_admin_dashboard_standard_deployment_refactoring.md 참고

교훈

설계 검증의 중요성

새 서비스 추가 시 기존 Gateway 라우팅 검토 필수
각 서비스의 역할 명확히 문서화

TDD 접근

테스트 코드 먼저 작성 (tests/test_admin_api.py)
구현 → 테스트 → 검증 순서 준수

일관성 있는 인증

모든 보호된 엔드포인트는 Gateway 경유
JWT 검증 로직 중앙화로 보안 강화

4.4 KiB Raw Permalink Blame History