전체 구조
중앙 API가 사용자의 화면 요청마다 모든 Hub를 직접 조회하지 않습니다. Collector가 각 제공자에서 데이터를 가져와 PostgreSQL에 저장하고, UI·REST·MCP는 일관된 저장 모델을 조회합니다. 서버 시작·중지·재시작만 대상 JupyterHub로 직접 전달하며 결과를 감사로그에 기록합니다.
Provider와 실제 수집 주기
| Provider | 현재 수집 대상 | 실행 주기 | 필수 여부 |
|---|---|---|---|
| JupyterHub REST | 버전, 사용자·그룹·역할, 서버 상태와 마지막 활동의 허용 목록 snapshot | 30초 base ticker에서 Hub별 설정 주기 확인 | Hub 관리 시 필수 |
| Prometheus | 기본 CPU·메모리 query와 관리자가 추가한 query의 허용 label | 30초 | 선택 |
| Kubernetes API | Pod 최대 500개의 이름·namespace·NodeName·phase만 저장하고 label은 매핑에만 사용 | 30초 | 선택 |
| DCGM → Prometheus | GPU ON 시 Pod별 할당 수·GPU Util·VRAM query | 30초 | GPU ON 시 선택 |
| Gateway/Service Mesh → Prometheus | LLM calls와 설정된 token·latency·bytes query | 1분 | LLM 관측 ON 시 전제 |
Hub 수집은 대상별 goroutine과 25초 context로 실행하고, 안전한 GET 요청은 실패 시 한 번 즉시 재시도합니다. 현재 버전에는 provider rate limit, 지수 backoff 또는 circuit breaker가 없습니다.
Healthy·Degraded와 stale 판정
- 수집 시도
30초 base ticker에서 활성 Hub의 설정 주기가 지났는지 확인합니다. - 성공
사용자·서버 전체 snapshot을 transaction으로 동기화하고 Hub를healthy로 갱신합니다. - 실패
Hub를degraded로 표시하고 오류를 저장하되 마지막 성공 snapshot과last_seen_at은 유지합니다. - stale 판정
세션은 마지막 동기화 시각이 5분 또는 Hub 수집 주기의 두 배보다 오래되면 stale로 취급합니다. - 복구
다음 성공 시 다시 전체 snapshot을 동기화하고healthy로 돌아갑니다.
현재 버전은 disconnected 상태 전이, 누락 구간 Delta Sync 또는 복구 이벤트를 만들지 않습니다. 대시보드·세션·LLM 응답의 기준 시각과 stale 표시, Hub의 last_seen_at을 함께 확인하세요.
PostgreSQL 데이터 계층
| 계층 | 목적 | 현재 보존 처리 |
|---|---|---|
| Latest snapshot | Hub·사용자·서버의 빠른 현재 상태 조회 | 최신 동기화 상태 유지 |
metric_samples | Prometheus 자원 메트릭의 기간별 조회 | system.raw_retention_days 적용 |
llm_usage_samples | 사용자·Pod·모델별 호출 통계 | llm_usage.retention_days 적용 |
| Audit/settings | 변경 추적과 운영 구성 | 현재 자동 보존 삭제 대상 아님 |
현재 주기적 보존 정리는 metric_samples와 llm_usage_samples 두 표에만 적용합니다. 감사로그나 일반 이벤트 전체에 같은 retention 설정이 적용되지는 않습니다.
Hub snapshot 동기화와 metric 저장은 PostgreSQL transaction을 사용합니다. 수집 주기 제어는 현재 프로세스의 mutex와 최근 실행 시각 map을 사용하므로 현재 버전은 단일 애플리케이션 replica 운영을 권장합니다. PostgreSQL advisory lock·작업 lease·날짜 파티셔닝·TimescaleDB 지원은 향후 확장 항목입니다.
오프라인 단일 이미지 런타임
멀티스테이지 Docker 빌드는 React 정적 자산과 Go 실행파일을 최종 Alpine 이미지의 /app에 함께 넣습니다. 실행 시 읽는 환경변수는 정확히 네 개입니다.
POSTGRES_DSN
BOOTSTRAP_ADMIN
BOOTSTRAP_ADMIN_PASSWORD
ENCRYPTION_KEYKeycloak, Hub, Prometheus, Kubernetes, AI, Webhook 설정은 관리자 UI를 통해 PostgreSQL에 저장하며 비밀값은 ENCRYPTION_KEY로 암호화합니다. 외부 CDN, 원격 폰트, 런타임 패키지 다운로드에 의존하지 않습니다.
현재 Adapter와 향후 확장
현재 버전은 JupyterHub·Prometheus·Kubernetes·AI용 구체 HTTP client를 internal/integration에 분리합니다. 공통 HubProvider·metric provider·secret provider 인터페이스와 Kubeflow Notebook, Jupyter Enterprise Gateway, vLLM, Ollama adapter는 향후 확장 항목입니다.
REST/OpenAPI
사람과 자동화가 운영 리소스를 조회·관리하며 RBAC와 감사 계층을 거칩니다.
MCP
현재 버전은 대시보드·Hub·서버·사용량을 조회하는 네 가지 read-only tool만 제공합니다.
상세 계약은 API·MCP 가이드, 위협 통제는 보안 가이드를 참고하세요.