kyush/kyush-llm-router
1
0
Fork 0
Code Releases Packages 1 Activity Actions

refactor(oci): to one image

Browse source
This commit is contained in:
Kyush 2026-03-26 04:10:01 +09:00
commit ee27e4c676
18 changed files with 342 additions and 633 deletions
Download patch file Download diff file Expand all files Collapse all files

108
docs/admin-auth.md
View file

@ -1,20 +1,25 @@
# Admin Authentication
관리자 영역은 `/admin/**` API와 관리자 프론트엔드 전체를 포함한다.
`/v1/**` 와 `/health` 는 기존 사용자 API 키 인증 또는 공개 엔드포인트 계약을 유지한다.
관리자 표면은 아래 두 부분으로 구성된다.
- 관리자 API: `/admin/**`
- 관리자 UI: `/dashboard`, `/dashboard/**`
OpenAI 호환 라우터 표면은 그대로 유지된다.
- `/v1/**`
- `/health`
## Authentication Modes
`ADMIN_AUTH_MODE` 로 관리자 로그인 방식을 제어한다.
`ADMIN_AUTH_MODE` 가 사용 가능한 관리자 로그인 방식을 제어한다.
| Mode | Description |
|------|-------------|
| `env` | ENV 기반 관리자 아이디/비밀번호 로그인만 허용 |
| `env` | 아이디/비밀번호 로그인만 허용 |
| `oidc` | OpenID Connect 로그인만 허용 |
| `both` | ENV 로그인과 OIDC 로그인을 모두 허용 |
기본 추천값은 `both`.
## Protected Surface
아래 경로는 관리자 인증이 필요하다.
@ -26,7 +31,7 @@
- `/admin/analytics/*`
- `/admin/health`
예외 공개 경로:
관리자 인증 내부의 공개 예외 경로:
- `POST /admin/auth/login`
- `GET /admin/auth/session`
@ -35,98 +40,55 @@
## Session Model
브라우저 로그인은 서버사이드 세션 + `HttpOnly` 쿠키를 사용한다.
- 브라우저 인증은 서버사이드 세션 + `HttpOnly` 쿠키를 사용한다
- 쿠키 이름: `kyush_admin_session`
- `SameSite=Lax`
- `Secure`: production 환경에서 활성화
- 세션 TTL: `ADMIN_SESSION_TTL_HOURS`
세션 데이터는 `core.db` 의 `admin_sessions` 테이블에 저장된다.
- 세션 레코드는 `core.db` 의 `admin_sessions` 테이블에 저장된다
## CSRF
세션 기반 관리자 요청은 CSRF 보호를 적용한다.
- `GET /admin/auth/session` 응답에 `csrfToken` 이 포함된다.
- 프론트엔드는 `POST`, `PUT`, `DELETE` 요청마다 `X-CSRF-Token` 헤더를 보낸다.
- Bearer 관리자 API 토큰 요청에는 CSRF를 적용하지 않는다.
- `GET /admin/auth/session` 응답에 `csrfToken` 이 포함된다
- 세션 기반 `POST`, `PUT`, `DELETE` 요청은 `X-CSRF-Token` 을 보내야 한다
- Bearer 관리자 API 토큰 요청에는 CSRF를 적용하지 않는다
## Admin API Tokens
자동화나 서비스 연동은 관리자 API 토큰을 사용할 수 있다.
- 발급: `POST /admin/auth/tokens`
- 조회: `GET /admin/auth/tokens`
- 폐기: `DELETE /admin/auth/tokens/:id`
- 발급 API: `POST /admin/auth/tokens`
- 조회 API: `GET /admin/auth/tokens`
- 폐기 API: `DELETE /admin/auth/tokens/:id`
토큰은 최초 발급 시 1회만 원문이 반환된다.
DB에는 hash 와 prefix 만 저장된다.
대상 테이블:
- `admin_api_tokens`
원본 토큰은 생성 시 1회만 반환된다. DB에는 hash와 prefix만 저장된다.
## ENV Login
ENV 로그인은 아래 설정이 필요하다.
| Variable | Description |
|----------|-------------|
| `ADMIN_USERNAME` | 관리자 로그인 아이디 |
| `ADMIN_PASSWORD_HASH` | 비밀번호 hash |
| `ADMIN_SESSION_SECRET` | 세션/토큰 hash salt 및 비밀값 |
| `ADMIN_SESSION_SECRET` | 세션/토큰용 비밀값 |
현재 구현은 아래 hash 형식을 지원한다.
지원하는 hash 형식:
- `sha256$<hex>`
- `scrypt$<salt_hex>$<derived_hex>`
`ADMIN_PASSWORD_HASH` 는 평문 비밀번호 대신 hash 값으로만 저장하는 것을 전제로 한다.
### Password Hash Generation Examples
## Admin Session API
빠른 로컬 테스트용 `sha256` 예시:
### `GET /admin/auth/session`
현재 관리자 세션 정보를 반환한다.
```json
{
"authenticated": true,
"authMode": "both",
"csrfToken": "base64url-token",
"principal": {
"provider": "env",
"subject": "env:admin",
"username": "admin",
"displayName": "admin"
}
}
```bash
node -e "const crypto=require('crypto'); const password=process.argv[1]; console.log('sha256$'+crypto.createHash('sha256').update(password).digest('hex'))" "change-me"
```
### `POST /admin/auth/login`
운영 권장 `scrypt` 예시:
요청 본문:
```json
{
"username": "admin",
"password": "your-password"
}
```bash
node -e "const crypto=require('crypto'); const password=process.argv[1]; const salt=crypto.randomBytes(16).toString('hex'); const derived=crypto.scryptSync(password, Buffer.from(salt,'hex'), 64).toString('hex'); console.log(`scrypt$${salt}$${derived}`)" "change-me"
```
성공 시 세션 쿠키를 발급하고 `AdminSessionResponse` 를 반환한다.
## UI Flow
### `POST /admin/auth/logout`
현재 세션을 무효화하고 세션 쿠키를 제거한다.
## Deployment Notes
운영 배포는 관리자 영역과 공개 라우팅을 분리하는 구성이 권장된다.
- public gateway: `/v1/**`, `/health`
- admin gateway: 관리자 SPA + `/admin/**`
관리자 프론트는 내부 전용 origin 에서 `/admin/**` 상대 경로만 호출한다.
이 구조로 브라우저 CORS 복잡도를 줄이고 관리자 라우팅을 외부 공개하지 않을 수 있다.
- 브라우저 진입 경로는 `/dashboard`
- 관리자 SPA는 `/admin/**` 로 관리자 API를 호출한다
- 로그인 성공 후 기본 이동 경로는 `/dashboard`
- OIDC `next` 값은 `/dashboard` 경로들로 제한된다

93
docs/client.md
View file

@ -1,6 +1,6 @@
# Client (Solid.js + Vite)
Admin 대시보드 진입점: `client/src/index.tsx`
관리자 대시보드 진입점: `client/src/index.tsx`
## Directory Structure
@ -14,77 +14,50 @@ client/src/
types/
index.ts # TypeScript 타입 정의
routes/
Dashboard.tsx # 메인 운영 요약 스트립 + 최근 요청 테이블 + 관리자 토큰 관리
Users.tsx # 사용자 관리, CRUD, API 키 재발급, 개별 상세 로그 토글
Backends.tsx # 백엔드 관리, CRUD (name, base_url, api_key, detail_logging, is_active)
Permissions.tsx # 권한 관리, user-backend 매핑, 추가/해제
Analytics.tsx # 분석 탭, 최근 요청, 사용량 통계, 백엔드 메트릭 차트/표
DetailLogs.tsx # 상세 로그 검색 뷰, 텍스트 검색, 사용자/백엔드 필터 + 페이지 + 페이로드 인스펙터
Scripts.tsx # 스크립트 관리, 목록, 요약, 편집기, 테스트, 활성/비활성화
Dashboard.tsx # 운영 요약, 최근 요청, 관리자 토큰 관리
Users.tsx # 사용자 CRUD
Backends.tsx # 백엔드 CRUD
Permissions.tsx # 권한 매핑 관리
Analytics.tsx # 분석 화면
DetailLogs.tsx # 상세 요청 로그 탐색
Scripts.tsx # 스크립트 관리 및 테스트
components/
Layout.tsx # AppShell 래퍼
EditModal.tsx # 레거시 범용 편집 모달
ScriptEditor.tsx # Monaco 에디터 래퍼 (TypeScript 하이라이트)
LoginGate.tsx # 로그인 화면, ENV 로그인 폼, OIDC 시작 버튼
LoginGate.tsx # 로그인 화면, ENV 로그인 폼, OIDC 버튼
ui/
index.ts # primitives/patterns 재수출
primitives/ # Button, Dialog, Select, Tabs, TextField 등
patterns/ # AppShell, DataGrid, PageHeader, SummaryStrip 등
styles/ # token/base/layout/pattern CSS 레이어
stories/ # Storybook workbench 스토리
patterns/ # AppShell 등 페이지 패턴
primitives/ # 공통 입력/표시 컴포넌트
styles/ # CSS 레이어
```
## Routes
관리자 UI의 브라우저 진입 경로는 `/dashboard` 이다.
| URL | Component | Description |
|-----|-----------|-------------|
| `/` | Dashboard | 시스템 개요 |
| `/users` | Users | 사용자 관리 |
| `/backends` | Backends | 백엔드 관리 |
| `/permissions` | Permissions | 권한 관리 |
| `/analytics` | Analytics | 집계 기반 분석 대시보드 |
| `/detail-logs` | DetailLogs | 상세 요청 로그 검색/인스펙션 |
| `/scripts` | Scripts | 스크립트 관리 |
| `/dashboard` | Dashboard | 시스템 개요 |
| `/dashboard/users` | Users | 사용자 관리 |
| `/dashboard/backends` | Backends | 백엔드 관리 |
| `/dashboard/permissions` | Permissions | 권한 관리 |
| `/dashboard/analytics` | Analytics | 분석 대시보드 |
| `/dashboard/detail-logs` | DetailLogs | 상세 요청 로그 탐색 |
| `/dashboard/scripts` | Scripts | 스크립트 관리 |
모든 관리자 라우트는 로그인 게이트 아래에서만 렌더링된다.
모든 관리자 라우트는 로그인 게이트 아래에서 렌더링된다.
## Styling
## Dev And Production
공통 UI 레이어는 `client/src/ui/styles.css` 에서 시작하고, 내부적으로 `tokens.css`, `base.css`, `layout.css`, `patterns.css`, `pages.css` 를 불러온다.
- 개발 서버 포트: `3002`
- 개발 API 프록시: `/admin` -> `http://localhost:3000`
- 운영에서는 Express 서버가 빌드된 `client/dist`를 직접 서빙한다
- 운영 브라우저 진입 경로: `http://<host>:3000/dashboard`
- `@kobalte/core` 기반 primitive wrapper와 공통 pattern을 사용한다.
- 페이지는 `AppShell`, `PageHeader`, `Panel`, `DataGrid`, `SummaryStrip`, `FormDialog`, `ConfirmDialog` 조합으로 구성된다.
- Storybook(`client/.storybook`)에서 같은 스타일 레이어를 사용하는 workbench를 운영한다.
- 라이트 테마와 dense 콘솔형 레이아웃을 기본 전제로 둔다.
## Dependencies
| Package | Purpose |
|---------|---------|
| solid-js | UI 프레임워크 |
| @solidjs/router | 클라이언트 사이드 라우터 |
| @kobalte/core | headless UI primitive |
| lucide-solid | 아이콘 세트 |
| solid-monaco | Monaco 에디터 통합 |
| vite | 빌드 도구 + 개발 서버 |
## Dev Server
포트: 3002 (`vite.config.ts`), 개발 중 API 프록시 `/admin` → `http://localhost:3000`
운영 배포에서는 관리자 프론트가 admin gateway 뒤에서 same-origin `/admin/**`를 호출한다. 브라우저가 내부 서버 주소를 직접 알 필요는 없다.
SPA는 `/dashboard`를 라우터 base로 사용하고, 관리자 API는 계속 `/admin/**`로 호출한다.
## Admin Auth Notes
- 앱 시작 시 `GET /admin/auth/session`으로 현재 로그인 상태와 CSRF 토큰을 불러온다.
- 인증되지 않은 상태에서는 관리자 화면 대신 `LoginGate`가 렌더링된다.
- ENV 로그인 폼과 OIDC 로그인 버튼을 함께 제공한다.
- 세션 기반 변경 요청은 `X-CSRF-Token` 헤더를 자동으로 포함한다.
- 401 응답은 재로그인 흐름으로, 403 응답은 권한 오류 표시로 처리한다.
- 관리자 API 토큰 생성/폐기는 Dashboard에서 수행한다.
## Analytics Notes
- `Analytics` 화면은 최근 요청/사용량 메트릭의 집계 뷰를 보여준다.
- 상세 요청 로그 검색은 별도 `DetailLogs` 화면에서 처리한다.
- analytics API 클라이언트는 `month`, `date`, `q`, `limit`, `offset`, `userId`, `backendId`, `endpoint`, `detailLogged` 필터를 지원한다.
- 앱 시작 시 `GET /admin/auth/session`으로 세션을 복구한다
- 인증되지 않은 상태에서는 `LoginGate`가 렌더링된다
- ENV 로그인과 OIDC 로그인을 함께 사용할 수 있다
- 세션 기반 쓰기 요청에는 `X-CSRF-Token`이 자동 포함된다
- 401 응답이 오면 UI는 로그인 상태로 되돌아간다

296
docs/k8s-traefik.md
View file

@ -1,118 +1,57 @@
# Kubernetes Deployment with Traefik
`kyush-llm-router`를 Kubernetes에 배포하면서, 외부에는 라우터 API만 공개하고 관리자 프론트와 `/admin/**`는 내부망에서만 접근하도록 구성하는 예시다.
이 예시는 아래를 함께 담은 단일 OCI 이미지를 가정한다.
이 문서는 ingress controller로 Traefik을 사용하고, 관리자 경로에는 `IngressRoute`와 `Middleware.ipAllowList`를 적용하는 상황을 가정한다.
- Express API 서버
- 빌드된 관리자 대시보드 자산
## Goals
Traefik은 path 기반으로 공개/내부 경로를 분리한다.
- 공개 진입점
- `/v1/**`
- `/health`
- 내부 전용 진입점
- 관리자 프론트
- `/admin/**`
- 브라우저 기준 관리자 프론트와 관리자 API는 same-origin으로 동작
- Traefik에서 admin host에 IP allowlist를 적용
- 공개: `/v1/**`, `/health`
- 내부 전용: `/admin/**`, `/dashboard`, `/dashboard/**`
## Assumptions
- Traefik CRD가 이미 설치되어 있다.
- 예시는 `apiVersion: traefik.io/v1alpha1` 기준이다.
- public host는 `router.example.com`, admin host는 `router-admin.internal.example.com` 을 사용한다.
- admin host는 사내망, VPN, 프라이빗 DNS 같은 내부 경로에서만 해석되거나 접근된다.
- 앱 이미지는 역할별로 분리되어 있다고 가정한다.
- `server` 이미지: Express 서버
- `admin-client` 이미지: 관리자 프론트 정적 파일을 nginx로 서빙하는 이미지
## Recommended Topology
## Topology
```text
Internet
-> Traefik
-> public IngressRoute
-> router-server Service:3000
-> router-app Service:3000
Internal network / VPN
-> Traefik
-> admin frontend IngressRoute + ipAllowList middleware
-> admin-client Service:80
Admin frontend
-> same-origin /admin/**
-> admin api IngressRoute + ipAllowList middleware
-> router-server Service:3000
-> admin IngressRoute + ipAllowList middleware
-> router-app Service:3000
```
핵심은 public/admin을 서로 다른 host로 분리하고, admin 쪽만 Traefik middleware로 한 번 더 제한하는 것이다.
## Environment And Secrets
아래 예시는 서버에 필요한 주요 ENV만 담는다.
```yaml
apiVersion: v1
kind: Secret
metadata:
name: router-server-secret
namespace: llm-router
type: Opaque
stringData:
ADMIN_PASSWORD_HASH: "scrypt$..."
ADMIN_SESSION_SECRET: "replace-with-long-random-secret"
OIDC_CLIENT_SECRET: ""
---
apiVersion: v1
kind: ConfigMap
metadata:
name: router-server-config
namespace: llm-router
data:
NODE_ENV: "production"
SERVER_PORT: "3000"
DB_DIR: "/data"
TZ: "Asia/Seoul"
CORS_ORIGINS: "https://router-admin.internal.example.com"
ADMIN_AUTH_MODE: "both"
ADMIN_USERNAME: "admin"
ADMIN_SESSION_TTL_HOURS: "12"
ADMIN_API_TOKEN_TTL_DAYS: "30"
ADMIN_TRUSTED_PROXY_IPS: "10.0.0.0/8,192.168.0.0/16"
OIDC_ISSUER_URL: ""
OIDC_CLIENT_ID: ""
OIDC_REDIRECT_URI: "https://router-admin.internal.example.com/admin/auth/oidc/callback"
OIDC_ALLOWED_EMAILS: "admin1@example.com,admin2@example.com"
OIDC_SCOPES: "openid profile email"
```
## Server Deployment
## App Deployment
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: router-server
name: router-app
namespace: llm-router
spec:
replicas: 1
selector:
matchLabels:
app: router-server
app: router-app
template:
metadata:
labels:
app: router-server
app: router-app
spec:
containers:
- name: server
image: ghcr.io/example/kyush-llm-router-server:latest
- name: app
image: ghcr.io/example/kyush-llm-router:latest
ports:
- containerPort: 3000
envFrom:
- configMapRef:
name: router-server-config
name: router-app-config
- secretRef:
name: router-server-secret
name: router-app-secret
volumeMounts:
- name: router-data
mountPath: /data
@ -120,14 +59,10 @@ spec:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 5
periodSeconds: 10
livenessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 15
periodSeconds: 20
volumes:
- name: router-data
persistentVolumeClaim:
@ -136,82 +71,18 @@ spec:
apiVersion: v1
kind: Service
metadata:
name: router-server
name: router-app
namespace: llm-router
spec:
selector:
app: router-server
app: router-app
ports:
- name: http
port: 3000
targetPort: 3000
```
```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: router-data
namespace: llm-router
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
```
## Admin Frontend Deployment
정적 파일 서빙이라면 nginx를 사용해도 충분하다. 여기서는 빌드된 관리자 프론트를 nginx가 서빙하는 전용 이미지를 사용한다고 가정한다.
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: admin-client
namespace: llm-router
spec:
replicas: 1
selector:
matchLabels:
app: admin-client
template:
metadata:
labels:
app: admin-client
spec:
containers:
- name: admin-client
image: ghcr.io/example/kyush-llm-router-admin:latest
ports:
- containerPort: 80
readinessProbe:
httpGet:
path: /
port: 80
initialDelaySeconds: 5
periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
name: admin-client
namespace: llm-router
spec:
selector:
app: admin-client
ports:
- name: http
port: 80
targetPort: 80
```
중요한 점은 nginx를 ingress 대신 내부 정적 파일 서버로만 쓰고, 외부 라우팅과 접근 제어는 Traefik이 담당하게 두는 것이다.
## Traefik Middleware
관리자용 host에만 내부망 IP allowlist를 적용한다.
## Admin IP Allowlist Middleware
```yaml
apiVersion: traefik.io/v1alpha1
@ -225,17 +96,10 @@ spec:
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16
- 100.64.0.0/10
ipStrategy:
depth: 1
```
`ipStrategy.depth` 는 Traefik 앞단에 L4/L7 프록시가 하나 더 있는 환경에서만 맞춰야 한다. 직접 노출된 Traefik이라면 생략하는 편이 안전하다.
## Public IngressRoute
외부 공개는 `/v1` 과 `/health` 만 노출한다.
```yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
@ -249,139 +113,33 @@ spec:
- match: Host(`router.example.com`) && (PathPrefix(`/v1`) || Path(`/health`))
kind: Rule
services:
- name: router-server
- name: router-app
port: 3000
tls:
secretName: router-example-com-tls
```
이 라우트에는 `/admin` 이나 관리자 프론트 경로를 넣지 않는다.
## Admin Frontend IngressRoute
관리자 프론트는 내부 전용 host로 따로 분리한다.
## Admin IngressRoute
```yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: router-admin-frontend
name: router-admin
namespace: llm-router
spec:
entryPoints:
- websecure
routes:
- match: Host(`router-admin.internal.example.com`) && Path(`/`)
- match: Host(`router-admin.internal.example.com`) && (PathPrefix(`/admin`) || PathPrefix(`/dashboard`))
kind: Rule
middlewares:
- name: admin-ip-allowlist
services:
- name: admin-client
port: 80
- match: Host(`router-admin.internal.example.com`) && PathPrefix(`/assets`)
kind: Rule
middlewares:
- name: admin-ip-allowlist
services:
- name: admin-client
port: 80
tls:
secretName: router-admin-internal-tls
```
단일 페이지 앱 경로 재작성은 admin-client 이미지 내부 nginx 설정에서 처리하는 편이 단순하다.
## Admin API IngressRoute
관리자 프론트가 same-origin `/admin/**` 를 직접 호출할 수 있도록 같은 host 아래에서 관리자 API를 서버로 보낸다.
```yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: router-admin-api
namespace: llm-router
spec:
entryPoints:
- websecure
routes:
- match: Host(`router-admin.internal.example.com`) && PathPrefix(`/admin`)
kind: Rule
middlewares:
- name: admin-ip-allowlist
services:
- name: router-server
- name: router-app
port: 3000
tls:
secretName: router-admin-internal-tls
```
이 방식이면 prefix 제거용 middleware가 필요 없고, 브라우저 요청:
```text
GET https://router-admin.internal.example.com/admin/auth/session
```
은 서버에 그대로 아래처럼 전달된다.
```text
GET /admin/auth/session
```
## Optional Hardening
- `router-server` Service를 `ClusterIP`로만 두고 외부 노출은 Traefik만 담당하게 한다.
- `NetworkPolicy`로 Traefik namespace에서만 `router-server` 와 `admin-client` 에 접근 가능하게 제한한다.
- 서버의 `ADMIN_TRUSTED_PROXY_IPS` 에 Traefik Pod CIDR 또는 Service CIDR 범위를 넣어 추가 방어선을 둔다.
- admin host는 공인 DNS에 올리지 않고 split-horizon DNS 또는 내부 DNS로만 배포한다.
- `/health` 와 `/admin/health` 의 공개 범위를 운영 정책에 맞게 다시 점검한다.
## Minimal NetworkPolicy Example
```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: router-server-ingress
namespace: llm-router
spec:
podSelector:
matchLabels:
app: router-server
policyTypes:
- Ingress
ingress:
- from:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: traefik
ports:
- protocol: TCP
port: 3000
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: admin-client-ingress
namespace: llm-router
spec:
podSelector:
matchLabels:
app: admin-client
policyTypes:
- Ingress
ingress:
- from:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: traefik
ports:
- protocol: TCP
port: 80
```
## Notes
- 이 문서는 예시이며, 실제 이미지 이름, TLS secret 이름, CIDR 범위, namespace 이름은 환경에 맞게 바꿔야 한다.
- Traefik CRD 버전에 따라 구버전 클러스터는 `traefik.containo.us/v1alpha1` 를 사용할 수 있다. 현재 예시는 `traefik.io/v1alpha1` 기준이다.
- IP allowlist는 강한 방어선이지만, 관리자 인증 자체를 대체하지 않는다. 현재 서버의 관리자 세션/OIDC/토큰 인증은 그대로 유지해야 한다.
이 구조는 관리자 API와 관리자 UI를 같은 origin에 두면서도, Traefik이 내부망 전용 접근 제어를 담당하게 만든다.

38
docs/oidc.md
View file

@ -1,22 +1,21 @@
# OpenID Connect Setup
관리자 인증은 generic OpenID Connect discovery 기반으로 동작한다.
특정 공급자 전용 분기 없이 issuer metadata 와 authorization code flow 를 사용한다.
관리자 OIDC 인증은 generic OpenID Connect discovery와 authorization code flow를 사용한다.
## Required Environment Variables
| Variable | Description |
|----------|-------------|
| `ADMIN_AUTH_MODE` | `oidc` 또는 `both` |
| `ADMIN_SESSION_SECRET` | state, nonce, session 보호용 비밀값 |
| `ADMIN_SESSION_SECRET` | state/session 보호용 비밀값 |
| `OIDC_ISSUER_URL` | issuer URL |
| `OIDC_CLIENT_ID` | client id |
| `OIDC_CLIENT_SECRET` | client secret |
| `OIDC_REDIRECT_URI` | callback URL |
| `OIDC_ALLOWED_EMAILS` | 관리자 허용 이메일 목록 |
| `OIDC_ALLOWED_EMAILS` | 관리자 allowlist |
| `OIDC_SCOPES` | 기본값 `openid profile email` |
## Minimal Example
## Local Example
```env
ADMIN_AUTH_MODE=both
@ -24,7 +23,7 @@ ADMIN_SESSION_SECRET=replace-with-long-random-secret
OIDC_ISSUER_URL=https://your-issuer.example.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_REDIRECT_URI=http://localhost:3002/admin/auth/oidc/callback
OIDC_REDIRECT_URI=http://localhost:3000/admin/auth/oidc/callback
OIDC_ALLOWED_EMAILS=admin1@example.com,admin2@example.com
OIDC_SCOPES=openid profile email
```
@ -37,29 +36,16 @@ ADMIN_SESSION_SECRET=replace-with-long-random-secret
OIDC_ISSUER_URL=https://auth.example.com/realms/main
OIDC_CLIENT_ID=kyush-router-admin
OIDC_CLIENT_SECRET=replace-with-client-secret
OIDC_REDIRECT_URI=https://admin.internal.example.com/admin/auth/oidc/callback
OIDC_REDIRECT_URI=https://router-admin.internal.example.com/admin/auth/oidc/callback
OIDC_ALLOWED_EMAILS=admin1@example.com,admin2@example.com
OIDC_SCOPES=openid profile email
```
## Flow
1. 브라우저가 `GET /admin/auth/oidc/start` 로 이동한다.
2. 서버는 discovery metadata 를 읽고 authorization endpoint 로 redirect 한다.
3. IdP 로그인 후 `OIDC_REDIRECT_URI` 로 callback 된다.
4. 서버는 code exchange 를 수행하고 ID token / userinfo 에서 principal 을 구성한다.
5. 이메일이 `OIDC_ALLOWED_EMAILS` 에 포함되면 관리자 세션을 생성한다.
6. 이후 브라우저는 세션 쿠키로 `/admin/**` 를 호출한다.
## Allowlist Policy
- 관리자 승인은 이메일 allowlist 로 제한한다.
- allowlist 에 없는 계정은 인증에 성공해도 관리자 권한을 얻지 못한다.
- 이메일 비교는 운영 중 표기 흔들림을 막기 위해 소문자 정규화를 전제로 하는 편이 좋다.
## Notes
- `OIDC_REDIRECT_URI` 는 실제 브라우저가 접근하는 관리자 origin 기준이어야 한다.
- 관리자 프론트가 same-origin `/admin/**` 를 사용하므로 callback 도 같은 origin 아래 두는 구성이 가장 단순하다.
- `OIDC_ALLOWED_EMAILS` 가 비어 있으면 운영 환경에서는 사실상 관리자 승인이 열려버릴 수 있으므로 명시적으로 설정하는 편이 안전하다.
- OIDC 는 관리자 인증 수단일 뿐이며, 내부망 접근 제어와 세션/토큰 정책을 대체하지 않는다.
1. 브라우저가 `GET /admin/auth/oidc/start` 로 이동한다
2. 서버가 공급자 authorization endpoint 로 redirect 한다
3. 공급자가 `OIDC_REDIRECT_URI` 로 다시 redirect 한다
4. 서버가 code exchange 를 수행하고 사용자를 검증한다
5. 이메일이 allowlist 에 있으면 관리자 세션을 생성한다
6. 브라우저는 `/dashboard` 로 진입한다

126
docs/server.md
View file

@ -6,99 +6,59 @@
```
server/src/
index.ts # Express 엔트리포인트(CORS, 라우터 마운트, health 핸들러, 관리자 인증 적용)
index.ts # Express 엔트리포인트, API/admin 라우트 마운트, dashboard 정적 파일 서빙
config/
db-paths.ts # DB_DIR 기준 파일 경로 계산
database.ts # Core SQLite 연결 및 스키마 초기화
analytics-db.ts # Analytics SQLite 연결 및 스키마 초기화
request-logs-db.ts # 월별 request_logs SQLite 연결 및 스키마 초기화
admin-auth.ts # 관리자 인증 ENV 파싱, auth mode / OIDC / TTL 설정
models/
User.ts # 사용자 CRUD (create, findById, findByApiKey, update, delete, regenerateApiKey)
Backend.ts # 백엔드 CRUD (create, findById, findAll, update, delete)
Permission.ts # 권한 관리 (user-backend 매핑)
Script.ts # 스크립트 CRUD (타입별 필터링, 활성화/비활성화)
AdminSession.ts # 관리자 세션 저장/조회/만료 처리
AdminApiToken.ts # 관리자 API 토큰 발급/조회/폐기
admin-auth.ts # 관리자 인증 ENV 파싱
database.ts # core DB 초기화
analytics-db.ts # analytics DB 초기화
request-logs-db.ts # 월별 request log DB 초기화
routes/
auth.ts # Bearer 토큰 인증 미들웨어 (사용자 API 키 검증, 권한 로드)
api.ts # OpenAI 호환 프록시 핸들러 (/v1/chat/completions, /v1/models)
admin-auth.ts # 관리자 로그인, 세션, OIDC, 관리자 토큰 API
admin.ts # Admin CRUD 핸들러 (users, backends, permissions, /admin/health, /admin/scripts 마운트)
scripts.ts # Script 관리/테스트 핸들러
analytics.ts # Analytics 조회 핸들러
api.ts # /v1 핸들러
admin-auth.ts # /admin/auth 핸들러
admin.ts # /admin CRUD 핸들러
analytics.ts # /admin/analytics 핸들러
services/
RouterService.ts # 활성 백엔드 선택, HTTP 요청 포워딩, header/body 정규화
AnalyticsService.ts # 일별 사용량 메트릭 집계 + request_logs 조회
RequestLogService.ts # 월별 request_logs 기록/조회
ScriptEngine.ts # 스크립트 체인 오케스트레이션 (onRequest/onResponse 적용)
ScriptExecutor.ts # isolated-vm 기반 스크립트 컴파일/실행 (5s timeout, 50MB memory)
RouterService.ts # 백엔드 선택 및 포워딩
AnalyticsService.ts # 사용량 집계 및 요청 로그 조회
ScriptEngine.ts # 스크립트 오케스트레이션
utils/
apiKey.ts # API 키 생성 (sk-{timestamp}-{random}, crypto.randomBytes)
adminAuth.ts # 관리자 principal 추출, 세션/토큰 인증 미들웨어, CSRF 검증
adminSecurity.ts # 비밀번호 hash 검증, 토큰 생성/hash, OIDC state/nonce 처리
logger.ts # 컬러 콘솔 로거
time.ts # TZ 기준 날짜/월 계산, UTC timestamp 생성
adminAuth.ts # 관리자 세션/토큰 인증 + CSRF 검사
adminSecurity.ts # 비밀번호/토큰 보안 유틸
logger.ts # 콘솔 로깅
```
## Request Flow
## Runtime Behavior
```text
Client -> auth.ts (사용자 API 키 검증, 권한 로드)
-> RouterService.selectBackend (허용된 활성 백엔드 중 1개 선택)
-> ScriptEngine.applyOnRequestScripts (요청 변조)
-> RouterService.forwardRequest (백엔드로 프록시)
-> ScriptEngine.applyOnResponseScripts (응답 컨텍스트 후처리 결과)
-> AnalyticsService.logRequest (집계 + 월별 request_logs 기록)
-> Response
```
- `/v1/**` 는 공개 라우터 API를 유지한다
- `/health` 는 공개 상태 확인 엔드포인트를 유지한다
- `/admin/**` 는 관리자 API 표면을 유지한다
- `/dashboard` 와 `/dashboard/**` 는 빌드된 관리자 SPA를 서빙한다
- 빌드된 `client/dist` 가 있으면 관리자 UI를 함께 제공하고, 없으면 API 전용 모드처럼 동작한다
참고:
- 라우터 마운트는 `server/src/index.ts` 에서 직접 수행한다.
- `/admin/**` 는 별도 관리자 인증 레이어를 거친 뒤 각 CRUD/analytics 라우트로 들어간다.
- `/admin/auth/*` 만 관리자 영역 내 공개 예외 엔드포인트다.
- `onResponse` 훅은 실행되지만 현재 구현에서는 반환값을 최종 HTTP 응답에 다시 반영하지 않는다.
라우트 우선순위는 다음과 같다.
## Time & Storage
1. `/admin/auth`
2. `/admin/analytics`
3. `/admin`
4. `/v1`
5. `/health`
6. `/dashboard` 정적 파일 + SPA fallback
7. `404`
- DB 루트는 `DB_DIR`로 설정한다. 파일은 `core.db`, `analytics.db`, `request_logs/request_logs_YYYY-MM.db` 구조로 생성된다.
- `core.db`에는 관리자 세션과 관리자 API 토큰을 위한 `admin_sessions`, `admin_api_tokens` 테이블도 생성된다.
- 일/월 경계 계산은 `TZ` 기준으로 수행된다.
- 저장되는 timestamp 문자열은 UTC ISO 형식으로 통일된다.
## Storage
## Admin Auth Notes
- `DB_DIR` 에 `core.db`, `analytics.db`, `request_logs/request_logs_YYYY-MM.db` 가 저장된다
- `core.db` 에는 `admin_sessions`, `admin_api_tokens` 도 함께 저장된다
- 시간 경계 계산은 `TZ` 기준이다
- 관리자 브라우저 인증은 서버사이드 세션 + `HttpOnly` 쿠키를 사용한다.
- 자동화용 관리자 인증은 Bearer 관리자 API 토큰을 사용한다.
- 세션 기반 `POST/PUT/DELETE` 요청에는 CSRF 검사가 적용된다.
- OIDC는 generic discovery 방식으로 동작하며, 허용 이메일은 `OIDC_ALLOWED_EMAILS`로 제한한다.
- 권장 배포는 public/admin 게이트웨이 분리 구조다. public 쪽은 `/v1/**`, `/health`만 노출하고 admin 쪽은 관리자 프론트와 `/admin/**`를 same-origin으로 제공한다.
## Deployment Notes
## Dependencies
| Package | Purpose |
|---------|---------|
| express@5 | 웹 프레임워크 |
| better-sqlite3 | SQLite 드라이버 |
| isolated-vm | 스크립트 샌드박스 실행 |
| zod | 입력 검증 |
| cors | CORS 미들웨어 |
| dotenv | 환경변수 로딩 |
## Tests
통합 테스트: `server/tests/integration/`
- `api.test.ts` - 인증, 에러, 프록시 핸들러
- `admin-auth.test.ts` - 관리자 로그인, 세션, CSRF, 관리자 토큰
- `admin.test.ts` - Admin CRUD
- `routing.test.ts` - 백엔드 선택, 요청 포워딩
- `scripts.test.ts` - 스크립트 생성, 실행, 검증
테스트 유틸: `server/tests/utils/` (`testApp.ts`, `mockBackend.ts`, `adminClient.ts`)
벤치마크: `server/benchmarks/` (`index.ts`, `runner.ts`, `scenarios.ts`, `report.ts`, `stats.ts`)
사용 문서:
- [docs/benchmarks.md](./benchmarks.md) - benchmark CLI usage, modes, output, caveats
- [docs/admin-auth.md](./admin-auth.md) - 관리자 인증, 세션, CSRF, 관리자 토큰
- [docs/oidc.md](./oidc.md) - OpenID Connect 설정과 allowlist 정책
- 권장 런타임은 단일 OCI 이미지다
- 이 이미지는 아래를 함께 포함한다
- 서버 런타임
- 빌드된 관리자 대시보드 자산
- database 스키마 파일
- `docker-compose` 에서는 API와 관리자 UI를 단일 포트로 노출할 수 있다
- Kubernetes에서는 Traefik이 아래처럼 path 기준으로 나눈다
- 공개: `/v1/**`, `/health`
- 내부 전용: `/admin/**`, `/dashboard`, `/dashboard/**`