kneron_model_converter/docs/autoflow/04-architecture/infra.md

Infra 設計

狀態：Phase 1 完工 — Phase 0.8b 只動 env，Nginx / docker-compose 結構不變。

配套：design-doc.md §7、auth.md §4（CONVERTER_API_KEY 管理）。

---

1. Nginx 雙 vhost 分流

維持 Phase 1 設計（Phase 0.8b 不動）：

• public vhost（443 對公網）：只 proxy /api/v1/* + /health
• internal vhost（內部 IP 80）：proxy /jobs/* + /queues/stats + Web UI

  ┌─────────────────────────────────────────────────────────────┐
  │                    Nginx（單一 process）                      │
  │                                                               │
  │  ┌────────────────────────┐   ┌────────────────────────────┐  │
  │  │ server {                │   │ server {                    │  │
  │  │   listen 443 ssl;       │   │   listen 10.0.0.1:80;       │  │
  │  │   server_name           │   │   server_name               │  │
  │  │     converter....com;   │   │     converter-internal...;  │  │
  │  │                         │   │                             │  │
  │  │   location /api/v1/ {}  │   │   location /jobs {}         │  │
  │  │   location = /health {} │   │   location /queues/stats {} │  │
  │  │   location / {          │   │   location / {              │  │
  │  │     return 404;         │   │     proxy_pass web:3000;    │  │
  │  │   }                     │   │   }                         │  │
  │  │ }                       │   │ }                           │  │
  │  │  (public vhost)         │   │  (internal vhost, 內網 IP)   │  │
  │  └───────────┬─────────────┘   └────────────┬────────────────┘  │
  └──────────────┼──────────────────────────────┼───────────────────┘
                 │                              │
                 ▼                              ▼
          ┌──────────────────────────────────────────────────┐
          │               Task Scheduler (:4000)              │
          │   - /api/v1/*    （API key 保護，僅 public vhost 轉入）│
          │   - /jobs/*      （無 auth，僅 internal vhost 轉入） │
          │   - /jobs/*/events（SSE）                           │
          │   - /health, /queues/stats                         │
          └──────────────────────────────────────────────────┘

---

2. Nginx 完整設定（不變）

# /etc/nginx/conf.d/converter.conf

upstream scheduler_upstream {
    server scheduler:4000;
    keepalive 32;
}

# Public vhost
server {
    listen 443 ssl http2;
    server_name converter.innovedus.com;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    location /api/v1/ {
        proxy_pass http://scheduler_upstream;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_request_buffering off;      # 大檔 stream
        proxy_read_timeout 300s;
        client_max_body_size 600M;        # multipart 上限略大於 500MB
    }

    location = /health {
        proxy_pass http://scheduler_upstream;
    }

    location / {
        return 404 '{"error":{"code":"not_found","message":"Not found"}}';
        default_type application/json;
    }
}

# Internal vhost
server {
    listen 10.0.0.1:80;
    server_name converter-internal.innovedus.com;

    location /jobs {
        proxy_pass http://scheduler_upstream;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_buffering off;       # SSE 需要
    }

    location /queues/stats {
        proxy_pass http://scheduler_upstream;
    }

    location / {
        proxy_pass http://web:3000;
    }
}

---

3. docker-compose.yml 環境變數變動

3.1 Phase 0.8b 移除

# 對外 API auth 不再走 OAuth
- MEMBER_CENTER_ISSUER
- MEMBER_CENTER_JWKS_URL
- KNERON_CONVERTER_AUDIENCE
- JWKS_CACHE_MAX_AGE_MS
- JWKS_COOLDOWN_MS
- JWT_CLOCK_TOLERANCE_SEC

3.2 Phase 0.8b 新增

- CONVERTER_API_KEY=${CONVERTER_API_KEY}    # 64 hex chars from `openssl rand -hex 32`

3.3 保留不動（promote 需要）

- MEMBER_CENTER_TOKEN_URL=${MEMBER_CENTER_TOKEN_URL}
- KNERON_CONVERTER_CLIENT_ID=${KNERON_CONVERTER_CLIENT_ID}
- KNERON_CONVERTER_CLIENT_SECRET=${KNERON_CONVERTER_CLIENT_SECRET}
- FILE_ACCESS_AGENT_BASE_URL=${FILE_ACCESS_AGENT_BASE_URL}
- FILE_ACCESS_AGENT_AUDIENCE=${FILE_ACCESS_AGENT_AUDIENCE}
- PROMOTE_TIMEOUT_MS=${PROMOTE_TIMEOUT_MS:-300000}
- OAUTH_TOKEN_REFRESH_SKEW_MS=${OAUTH_TOKEN_REFRESH_SKEW_MS:-60000}
- OAUTH_TOKEN_TIMEOUT_MS=${OAUTH_TOKEN_TIMEOUT_MS:-10000}

3.4 既有（不動）

- PORT=4000
- NODE_ENV=${NODE_ENV:-development}
- REDIS_URL=${REDIS_URL}
- STORAGE_BACKEND=minio
- MINIO_*
- CONVERTER_TENANT_ID=${CONVERTER_TENANT_ID:-}    # Phase 0.8b 仍保留（promote 流程仍可能用）
- API_V1_RATE_LIMIT_WINDOW_MS=${API_V1_RATE_LIMIT_WINDOW_MS:-300000}
- API_V1_RATE_LIMIT_MAX=${API_V1_RATE_LIMIT_MAX:-300}
- MULTIPART_MODEL_MAX_BYTES=${MULTIPART_MODEL_MAX_BYTES:-524288000}
- MULTIPART_REF_IMAGE_MAX_BYTES=${MULTIPART_REF_IMAGE_MAX_BYTES:-10485760}
- MULTIPART_REF_IMAGES_MAX_COUNT=${MULTIPART_REF_IMAGES_MAX_COUNT:-100}
- MAX_CONCURRENT_UPLOADS=${MAX_CONCURRENT_UPLOADS:-5}
- UPLOAD_RETRY_AFTER_SECONDS=${UPLOAD_RETRY_AFTER_SECONDS:-30}

3.5 變動移除原因

Env	為什麼移除	Phase 1 用途
MEMBER_CENTER_ISSUER	API key 不需要驗 issuer	OAuth resource server 驗 iss claim
MEMBER_CENTER_JWKS_URL	API key 不需要 JWKS	OAuth JWT 簽章驗證
KNERON_CONVERTER_AUDIENCE	API key 不需要驗 aud	OAuth 驗 token 是給自己的
JWKS_*	沒有 JWKS cache 了	JWKS 內部 cache 參數
JWT_CLOCK_TOLERANCE_SEC	沒有 JWT 驗證了	JWT exp 時鐘容忍

---

4. .env.example 改動

4.1 移除段（OAuth resource server）

# === OAuth (Member Center) ===           ← 整段移除
MEMBER_CENTER_ISSUER=...
MEMBER_CENTER_JWKS_URL=...

# === Converter identity (Resource Server) ===   ← 整段移除
KNERON_CONVERTER_AUDIENCE=...

# === JWKS cache ===                      ← 整段移除
JWKS_CACHE_MAX_AGE_MS=600000
JWKS_COOLDOWN_MS=30000
JWT_CLOCK_TOLERANCE_SEC=60

4.2 新增段

# === Phase 0.8b: API key for visionA → converter ===
# 用 `openssl rand -hex 32` 產 64 hex chars
# 雙端必須對齊：visionA `.env.stage` 的 VISIONA_CONVERTER_API_KEY 同值
# 絕不進 git / log / Slack
CONVERTER_API_KEY=

4.3 保留段（不變，promote 用）

# === Member Center token endpoint（converter → FAA promote 用）===
MEMBER_CENTER_TOKEN_URL=https://auth.innovedus.com/oauth/token

# === Converter identity (OAuth Client，promote 用) ===
KNERON_CONVERTER_CLIENT_ID=kneron_converter
KNERON_CONVERTER_CLIENT_SECRET=change-me

# === File Access Agent ===
FILE_ACCESS_AGENT_BASE_URL=https://files.nas.internal
FILE_ACCESS_AGENT_AUDIENCE=file_access_api

# === Promote / OAuth Client tunables ===
PROMOTE_TIMEOUT_MS=300000
OAUTH_TOKEN_REFRESH_SKEW_MS=60000
OAUTH_TOKEN_TIMEOUT_MS=10000

# === Rate Limit ===
API_V1_RATE_LIMIT_WINDOW_MS=300000
API_V1_RATE_LIMIT_MAX=300

# === Multipart upload ===
MULTIPART_MODEL_MAX_BYTES=524288000
MULTIPART_REF_IMAGE_MAX_BYTES=10485760
MULTIPART_REF_IMAGES_MAX_COUNT=100
MAX_CONCURRENT_UPLOADS=5
UPLOAD_RETRY_AFTER_SECONDS=30

---

5. 部署順序（Phase 0.8b）

重要：錯誤順序會讓 stage 整段 down。正確順序：

Step 1: converter 端先實作完 + deploy
  - 砍 OAuth middleware、加 API key middleware
  - 加 /result endpoint
  - 設 CONVERTER_API_KEY env
  - 此時 converter 對外只認 API key（OAuth 已移除）
  - 但既有 visionA stage 還在用 OAuth → 會撞 401
  ⚠️ 此 Step 應在 visionA stage 跑得通 OAuth 之前先完成（既然 visionA OAuth 還沒整合通過、本來就 401）

Step 2: 驗證 converter 新 endpoint 可用
  - curl 打 GET /api/v1/jobs/<某 completed job>/result 帶 Bearer <CONVERTER_API_KEY>
  - 確認 200 + NEF binary stream
  - curl 打 POST /api/v1/jobs 用同把 key
  - 確認 201 + job_id

Step 3: visionA backend deploy（已 ready、commit 9e29ebf）
  - VISIONA_CONVERTER_API_KEY env 跟 CONVERTER_API_KEY 對齊
  - visionA 用 API key 打 converter、走新的 GetResult endpoint

Step 4: e2e 驗證
  - User upload → init → poll → promote → download
  - 全綠 = 完成

5.1 注意：5/9 stage 狀態

Phase 1 OAuth 從未在 stage 跑通（MC scope 沒註冊）。所以 Phase 0.8b 切換對「實際 e2e」是 net positive（從未 work → 開始 work）。Stage 不會有「OAuth 過了改 API key 變成 401」的 regression。

---

6. 安全配置

6.1 CONVERTER_API_KEY

詳見 auth.md §4。

重點：

• 每環境獨立（dev / stage / prod）
• 64 hex chars（openssl rand -hex 32）
• 雙端對齊（visionA + converter）
• 絕不進 git
• Rotation 流程：手動同步 .env + redeploy

6.2 Sec C1 暫緩（既有風險、不變）

.env 一度被 commit 進 git history（5/2 健檢發現），已加入 .gitignore 但 history 仍可追溯。

Phase 0.8b 階段：

• 新增 CONVERTER_API_KEY 時注意不要進 git
• Phase 1 ready 後做一次 git history rewrite + 全 secret rotate（包括新加的 CONVERTER_API_KEY、既有的 OAuth client_secret、MinIO 等）

---

7. CI/CD 影響

無需改 CI：

• 既有 GitHub Actions 設定不變
• 新加 CONVERTER_API_KEY 到 stage / prod secrets manager（Vault / k8s secret / docker secret）
• dev 用 .env（gitignored）

---

8. Phase 2 預留

• 多 instance 部署：rate limiter 需從 process-local memory 改 Redis store
• 多 caller：可考慮加回 OAuth resource server（API key + OAuth 並存模式）
• Secrets manager 自動 rotation：整合 HashiCorp Vault / AWS Secrets Manager