139 lines
4.4 KiB
Markdown
139 lines
4.4 KiB
Markdown
# 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 상태
|
|
```bash
|
|
docker ps --filter "name=robeing-gateway"
|
|
# 출력: Up X seconds (healthy)
|
|
```
|
|
|
|
### 2. 엔드포인트 테스트
|
|
```bash
|
|
# 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의 역할 (중앙집중형)
|
|
1. **JWT 검증**: 모든 요청의 인증 게이트웨이
|
|
2. **Username → UUID 변환**: DB 조회 및 캐싱
|
|
3. **라우팅**:
|
|
- `/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` 참고
|
|
|
|
---
|
|
|
|
## 관련 문서
|
|
|
|
- **표준 배포 방식 전환**: `251117_admin_dashboard_standard_deployment_refactoring.md` (최신)
|
|
- **Gateway 아키텍처**: `/home/admin/DOCS/book/300_architecture/gateway_proxy_patterns.md`
|
|
- **전체 시스템 구조**: `/home/admin/DOCS/book/300_architecture/310_전체_시스템_구조_컨테이너와_마이크로서비스.md`
|
|
- **Gateway 구현 히스토리**: `/home/admin/DOCS/journey/troubleshooting/250809_happybell80_robing-gateway구현.md`
|
|
|
|
---
|
|
|
|
## 교훈
|
|
|
|
### 설계 검증의 중요성
|
|
- 새 서비스 추가 시 기존 Gateway 라우팅 검토 필수
|
|
- 각 서비스의 역할 명확히 문서화
|
|
|
|
### TDD 접근
|
|
- 테스트 코드 먼저 작성 (`tests/test_admin_api.py`)
|
|
- 구현 → 테스트 → 검증 순서 준수
|
|
|
|
### 일관성 있는 인증
|
|
- 모든 보호된 엔드포인트는 Gateway 경유
|
|
- JWT 검증 로직 중앙화로 보안 강화
|