# Sub2API Bridge — 协同调度说明 > **版本**: v0.1 | **日期**: 2026-05-08 --- ## 系统总览 ``` ┌──────────────┐ ┌─────────────────────────────────────┐ │ │ HTTPS │ nginx (TLS) │ │ Client │────────>│ │ │ (前端 SPA) │ │ /api/v1/oidc-bridge ──> Bridge │ │ │<────────│ /api/v1/* ──> Sub2API │ └──────────────┘ JWT │ /v1/* ──> Sub2API │ │ │ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │ 林社 │ │Postgres│ │ Redis │ │ │ │ (OIDC) │ │ │ │ │ │ │ └────────┘ └────────┘ └────────┘ │ └─────────────────────────────────────┘ ``` **核心思路**: 用户在前端通过林社完成 OIDC 认证拿到林社 JWT，然后由 Bridge 服务验签并换发 Sub2API 的 Session JWT，之后所有业务请求使用 Session JWT 访问 Sub2API。 --- ## 调度时序 ``` Client (SPA) nginx Bridge 林社 (OIDC) Postgres │ │ │ │ │ │ 1. 用户点击登录 │ │ │ │ │ ── redirect ─────────>│── proxy ──────────────────────────────>│ │ │ │ │ │ Passkey/密码认证 │ │ <── 林社 JWT ──────── │<── callback ──────────────────────────│ │ │ │ │ │ │ │ 2. 交换令牌 │ │ │ │ │ POST /api/v1/oidc-bridge │ │ │ │ Bearer <林社 JWT> │ │ │ │ │ ─────────────────────>│ proxy_pass ──────>│ │ │ │ │ │ │ │ │ │ │ 3. JWKS 验签 │ │ │ │ │ GET jwks.json ──>│ │ │ │ │ <── { keys } ────│ │ │ │ │ 验证 sig/iss/aud │ │ │ │ │ │ │ │ │ │ 4. 获取用户邮箱 │ │ │ │ │ GET userinfo ───>│ │ │ │ │ <── { email } ───│ │ │ │ │ │ │ │ │ │ 5. 查 sub2api 用户│ │ │ │ │ SELECT ... ──────────────────────> │ │ │ │ <── (id, email, role) ──────────── │ │ │ │ │ │ │ │ │ 6. 签发 HS256 JWT │ │ │ │ │ │ │ │ <── 200 { access_token, user_email, user_id } │ │ │ │ │ │ │ │ 7. 后续业务请求 │ │ │ │ │ Bearer │ │ │ │ │ ─────────────────────>│── /api/v1/* ──> Sub2API │ │ │ ─────────────────────>│── /v1/* ──> Sub2API (streaming) │ │ │ │ │ │ │ ``` --- ## 调度入口 — Bridge nginx 将 `/api/v1/oidc-bridge` 精确转发至 Bridge 的 `/exchange-session`。 | 方法 | 路径 | 说明 | |:---:|:---|:---| | POST | `/api/v1/oidc-bridge` | 林社 JWT → Session JWT 交换 | | GET | `/healthz` | Bridge 健康检查 | **请求**: ```http POST /api/v1/oidc-bridge Authorization: Bearer <林社 JWT> ``` **成功响应** (200): ```json { "access_token": "eyJhbGciOi...", "token_type": "Bearer", "expires_in": 86400, "user_email": "user@example.com", "user_id": 42 } ``` **错误码**: | HTTP | Code | 阶段 | 原因 | |:---:|:---|:---:|:---| | 405 | `METHOD_NOT_ALLOWED` | 入口 | 非 POST | | 401 | `MISSING_BEARER` | 入口 | 缺 Authorization 头 | | 401 | `INVALID_PID_TOKEN` | JWKS 验签 | 签名/iss/aud 校验失败 | | 401 | `USERINFO_FAILED` | Userinfo | 林社调用失败 | | 404 | `USER_NOT_FOUND` | DB 查询 | 邮箱不在 sub2api 用户表 | | 500 | `SIGN_FAILED` | JWT 签发 | HS256 签名异常 | --- ## 交换后可调用的 API 获得 Session JWT 后，以 `Authorization: Bearer ` 调用以下端点。 ### 认证管理 | 方法 | 路径 | 说明 | |:---:|:---|:---| | GET | `/api/v1/auth/me` | 获取当前用户信息 | | POST | `/api/v1/auth/refresh` | 刷新 JWT | | POST | `/api/v1/auth/logout` | 登出 | | POST | `/api/v1/auth/revoke-all-sessions` | 撤销所有会话 | | POST | `/api/v1/auth/oauth/bind-token` | 准备 OAuth 绑定 Cookie | ### 用户资料 | 方法 | 路径 | 说明 | |:---:|:---|:---| | GET | `/api/v1/user/profile` | 获取个人资料 | | PUT | `/api/v1/user` | 更新个人资料 | ### API Keys | 方法 | 路径 | 说明 | |:---:|:---|:---| | GET | `/api/v1/keys` | 列出 API Key | | GET | `/api/v1/keys/:id` | 获取单个 Key | | POST | `/api/v1/keys` | 创建 Key | | PUT | `/api/v1/keys/:id` | 更新 Key | | DELETE | `/api/v1/keys/:id` | 删除 Key | ### 分组与模型 | 方法 | 路径 | 说明 | |:---:|:---|:---| | GET | `/api/v1/groups/available` | 可用分组列表 | | GET | `/api/v1/groups/rates` | 用户分组费率 | | GET | `/api/v1/groups/:id/models` | 分组下的模型 | | GET | `/api/v1/channels/available` | 可用渠道列表 | ### 用量统计 | 方法 | 路径 | 说明 | |:---:|:---|:---| | GET | `/api/v1/usage` | 用量列表 | | GET | `/api/v1/usage/:id` | 单条用量详情 | | GET | `/api/v1/usage/stats` | 用量统计 | | GET | `/api/v1/usage/dashboard/stats` | 仪表盘统计 | | GET | `/api/v1/usage/dashboard/trend` | 趋势图 | | GET | `/api/v1/usage/dashboard/models` | 模型分布 | | POST | `/api/v1/usage/dashboard/api-keys-usage` | Key 用量 | ### 公告 | 方法 | 路径 | 说明 | |:---:|:---|:---| | GET | `/api/v1/announcements` | 公告列表 | | POST | `/api/v1/announcements/:id/read` | 标记已读 | ### 兑换 | 方法 | 路径 | 说明 | |:---:|:---|:---| | POST | `/api/v1/redeem` | 使用兑换码 | | GET | `/api/v1/redeem/history` | 兑换历史 | ### 订阅 | 方法 | 路径 | 说明 | |:---:|:---|:---| | GET | `/api/v1/subscriptions` | 订阅列表 | | GET | `/api/v1/subscriptions/active` | 当前有效订阅 | | GET | `/api/v1/subscriptions/progress` | 订阅进度 | | GET | `/api/v1/subscriptions/summary` | 订阅摘要 | ### 渠道监控 | 方法 | 路径 | 说明 | |:---:|:---|:---| | GET | `/api/v1/channel-monitors` | 监控列表 | | GET | `/api/v1/channel-monitors/:id/status` | 监控状态 | ### AI 网关 (API Key 认证) Session JWT 创建的 API Key 用于以下网关端点 (nginx streaming 模式, 无缓冲): | 方法 | 路径 | 说明 | |:---:|:---|:---| | POST | `/v1/chat/completions` | OpenAI Chat Completions | | POST | `/v1/messages` | Claude Messages API | | POST | `/v1/messages/count_tokens` | Claude Token 计数 | | POST | `/v1/responses` | OpenAI Responses API | | GET | `/v1/models` | 模型列表 | | GET | `/v1/usage` | 用量查询 | | POST | `/v1/images/generations` | 图片生成 | | POST | `/v1/images/edits` | 图片编辑 | | GET | `/v1beta/models` | Gemini 模型列表 | | POST | `/v1beta/models/*modelAction` | Gemini generateContent 等 | ---