Sakurasan
5d6e5bdb04
渠道上游 key 用 OT_MASTER_KEY 经 AES-GCM 加密落库，主密钥一旦变化，全部渠道在运行时
报 "failed to decrypt channel key"。最常见的成因是历史实例先用了空主密钥（退化为
sha256("")），后来才补上 OT_MASTER_KEY——旧密文从此解不开，看起来像渠道全挂了。
- 新增 `check-channels`：打印主密钥派生路径与指纹（SHA-256 前 4 字节，不泄露密钥）
+ 逐渠道解密结果，区分「全部失败=主密钥不对」与「个别失败=该渠道密文异常」；
存在失败时退出码为 1，便于脚本告警
- 新增 `rotate-master-key`：旧密钥解密、新密钥重新加密，全部渠道单事务更新，
任一渠道解不开就整体回滚（--force 可跳过），避免库里新旧密钥混杂；
写入前对新密文做回读校验；--dry-run 只验证不改库。空主密钥作为默认 --old，
正是「先空后补」的历史路径；配套迁移无需重新录入任何渠道 key
- crypto 新增 KeyFingerprint / KeyMode：指纹用于比对两个实例是否同一把密钥，
KeyMode 显式暴露「16/24/32 字节用原始字节、其他长度走 SHA-256 派生」这条
容易踩的长度陷阱（改长度等于换密钥）
- 启动警告：开发环境不拦空/占位主密钥，但明确提示它等于公开密钥，并给出
rotate-master-key 指引；生产环境仍由 config.validate 直接拒绝启动
- README 补主密钥与渠道密钥运维小节
- 测试：换密钥必解密失败、长度切换 32↔33 字节必失败、指纹一致性
验证：go vet、go test ./... 全绿；端到端复现「空主密钥建渠道 → 配新主密钥全部解密失败
→ rotate-master-key 迁移 → check-channels 全部正常」，明文长度与前后缀保持一致。
134 lines
11 KiB
Markdown
134 lines
11 KiB
Markdown
# openteam · 大模型中转站
|
||
|
||
自托管的 LLM API 中转网关，功能对标 OpenRouter / one-api：统一 OpenAI 与 Anthropic 协议入口，背后对接多个上游渠道，内置用户体系、API Key 管理与用量计费。
|
||
|
||
> 规划文档见 [PLANNING.md](./PLANNING.md)。当前进度：**M0-M2 + M4-M5 + M3 收尾已完成**（基建 + 用户/密钥/核心代理 + 前端 MVP + 管理后台基础 + 三协议互转 + 渠道体系 + 限流/配额 + 前端骨架屏）。
|
||
|
||
## 功能（当前）
|
||
|
||
- **代理端点**（Bearer API Key）
|
||
- `POST /v1/chat/completions` — OpenAI Chat（非流式 + 流式 SSE）
|
||
- `POST /v1/responses` — OpenAI Responses API（非流式 + 流式事件）
|
||
- `POST /v1/messages` — Anthropic Messages API（非流式 + 流式事件）
|
||
- `GET /v1/models` — 可用模型列表：只列调用方真能用的模型（叠加用户与密钥白名单），带上下文长度与能力位；Anthropic 客户端（带 `x-api-key`/`anthropic-version`）返回 Anthropic 形状
|
||
- **三协议互转**：客户端协议 × 渠道协议不匹配时自动转换（如 Chat 调用 Claude、Messages 调用 OpenAI、Responses 调用 Claude），流式逐事件转换；协议匹配时直通
|
||
- 错误按客户端协议返回（OpenAI 格式 / Anthropic 格式）
|
||
- **热路径开销**：鉴权缓存（`OT_PROXY_AUTH_CACHE_TTL`，默认 2s，缓存密钥+用户行，状态与过期仍按当前时间判定，写操作即时失效）——开启后命中请求**零 SQL**，16 并发实测 p50 535µs→131µs、RPS 21k→56–81k；模型/渠道目录进程内缓存（每请求 SQL 从 10 条降到 2 条，管理端写操作与健康状态变化即时失效）、流式正文按字节快路径提取、请求体定点改写（模型映射不再整包 unmarshal/marshal）、tiktoken 编码器复用、会话亲和表 16 片无锁竞争（键为 64 位摘要、零分配）、访问日志走 64 KiB 缓冲（不再每请求一次 stderr 系统调用）；记账落库按驱动自适应（SQLite 单 worker + batch 64，并启用 `_txlock=immediate` 与 `synchronous=NORMAL`，实测 13k → 30k rows/s 且抖动从 ±50% 收敛到 <1%；PostgreSQL 4 个分片 worker）
|
||
- **渠道体系**：按模型绑定选渠道 + 加权负载均衡；模型已有绑定时只用绑定渠道（都不可用则 503，不会把请求发给不认识它的渠道）；每渠道并发信号量（满载排队 `OT_PROXY_CHANNEL_ACQUIRE_WAIT`，默认 150ms，仍满则 503 + Retry-After 而不是 502）；后台健康检查（探测 `/models`，连续失败进 cooldown、恢复放回）+ 运行期健康（按失败原因分类冷却：网络错误/5xx 连续 3 次进冷却且指数退避，余额/配额类第一次即冷却 30 分钟，成功清零退避计数）；可安全重试的失败自动故障转移（网络错误/429/5xx/超时/流式首个内容事件之前的任何失败）；**会话亲和**（`OT_PROXY_AFFINITY_TTL`，默认 5m）：同一会话粘住上次应答的渠道，命中上游提示词缓存而不是全价重算，冷却/下线自动回退加权随机
|
||
- **上游超时**：渠道 `timeout_ms` 生效——非流式为整段请求上限，流式仅约束首包（正文不限时长）；上游请求绑定客户端 context，断连即取消
|
||
- **故障转移与流式细节**（借鉴 magpie 的 holdWriter）：流式请求在**首个内容事件**到达前由网关缓冲——上游的错误事件、空流、断连、协议形态不符（要流给了整包，didNotStream）都在放行前换渠道消化，客户端无感知；`OT_PROXY_FIRST_TOKEN_WAIT` 限定放行前等内容的最长时间（0=不限）；429 不一定是限流——错误体带余额/配额特征时按配额类长冷却；上游 `Retry-After` 会延长该渠道冷却（夹在 10 分钟内）；重试受 `OT_PROXY_FAILOVER_BUDGET` 时间预算约束（首个渠道不受限，避免坏渠道把客户端拖到 N×timeout）；流式空闲超过 `OT_PROXY_STREAM_HEARTBEAT` 补一行 SSE 注释心跳（扣住期间也照发），防止 nginx/Cloudflare 的空闲超时掐掉长思考；响应头已被心跳先行写出时，全部候选失败以 SSE 错误事件收尾
|
||
- **数据保留**：`OT_USAGE_RETENTION_DAYS`（默认 0=永久保留）开启后每天分批清理过期用量明细；余额流水不清理
|
||
- **渠道观测**：`GET /api/v1/admin/channels/stats?window=5m|1h|6h|24h|7d` 按渠道聚合请求量、成功率、错误码分布与 P50/P95 延迟；渠道页直接展示近况与运行期冷却剩余时间，可一键恢复
|
||
- **限流/配额**（内存计数）：密钥级每日请求数 / Token 数配额、用户级每秒速率（`OT_RATELIMIT_USER_RPS`）；超限返回 429
|
||
- **用量计费**：请求级 `usage_logs` 异步批量落库，按模型价格扣减余额，日粒度预聚合（`usage_daily`）；模型可单独配置缓存写价（留空按输入价 ×1.25）；记录思考 token（`reasoning_tokens`，展示口径不重复计费）、Anthropic 1h 缓存写（计价 2× 输入）与上游实际应答的模型名（`served_model`，映射/聚合商场景对账用）
|
||
- **认证面防护**：登录按「单 IP」+「单 IP×账号」双桶滑动窗口限速、注册按 IP 限速（429 + `Retry-After`）；`/v1` 请求体上限 `OT_PROXY_MAX_BODY_MB`（超限按客户端协议返回 413）；CORS 改为显式 origin 白名单（默认不发跨域头）；`env=production` 启动时断言 JWT secret / 主密钥 / 管理员密码不能是仓库默认值，否则拒绝启动
|
||
- **前端**：Dashboard / 管理总览骨架屏加载态
|
||
- **用户体系**：注册（开放/邀请码可切换，管理后台可改）、登录（JWT access + HttpOnly refresh cookie）、argon2id 密码
|
||
- **API Key**：`sk-ot-` 48 位 base62，仅存 SHA-256 哈希，明文一次性展示；支持限额/过期/白名单字段
|
||
- **用量计费**：请求级 `usage_logs` 异步批量落库，按模型价格扣减余额，日粒度预聚合（`usage_daily`）
|
||
- **管理 API**：渠道 CRUD + 连通测试 + 立即恢复（清运行期冷却）+ 模型导入、模型管理 + 定价 + 渠道绑定、用户管理、全局用量/统计、系统配置
|
||
- **前端**（Vue3 + Tailwind，taste-skill 设计，深色优先）
|
||
- Landing / 登录 / 注册
|
||
- 控制台：Dashboard（余额/用量/趋势图）、API Keys、用量明细
|
||
- 管理后台：运营总览、渠道管理、模型与定价、用户管理、系统配置
|
||
- **后端**：Go + Gin + GORM，SQLite（开发）/ PostgreSQL（生产）
|
||
|
||
> 剩余：M6 充值（待定）与 M3 收尾（限流、骨架屏）。
|
||
|
||
## 快速开始（开发）
|
||
|
||
前置：Go 1.23+。
|
||
|
||
```bash
|
||
# 1. 配置（复制并修改，至少设置上游 key）
|
||
cp .env.example .env
|
||
|
||
# 2. 启动后端（SQLite 起步，无需数据库）
|
||
cd server && go run ./cmd/server
|
||
# 默认管理员 admin / admin123（生产务必修改）
|
||
|
||
# 3. 用 mock 上游联调（无需真实 key，另开终端）
|
||
make mock-upstream # :9000 起一个模拟 OpenAI 服务
|
||
```
|
||
|
||
`.env` 中 `OT_PROXY_UPSTREAM_KEY` / `OT_PROXY_UPSTREAM_BASE_URL` 指向 mock 上游时，服务首次启动会自动创建默认渠道与示例模型。
|
||
|
||
### 冒烟测试（curl）
|
||
|
||
```bash
|
||
# 注册 → 登录 → 建 key
|
||
curl -s -X POST localhost:8080/api/v1/auth/register -H 'Content-Type: application/json' \
|
||
-d '{"username":"alice","email":"a@b.com","password":"password123"}'
|
||
TOKEN=$(curl -s -X POST localhost:8080/api/v1/auth/login -H 'Content-Type: application/json' \
|
||
-d '{"username":"alice","password":"password123"}' | jq -r .data.access_token)
|
||
KEY=$(curl -s -X POST localhost:8080/api/v1/keys -H "Authorization: Bearer $TOKEN" \
|
||
-H 'Content-Type: application/json' -d '{"name":"dev"}' | jq -r .data.key)
|
||
|
||
# 对话（非流式 + 流式）
|
||
curl -s localhost:8080/v1/chat/completions -H "Authorization: Bearer $KEY" \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}],"stream":false}'
|
||
curl -N localhost:8080/v1/chat/completions -H "Authorization: Bearer $KEY" \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}],"stream":true}'
|
||
|
||
# 用量
|
||
curl -s localhost:8080/api/v1/usage/summary -H "Authorization: Bearer $TOKEN"
|
||
curl -s "localhost:8080/api/v1/usage/logs?page_size=5" -H "Authorization: Bearer $TOKEN"
|
||
```
|
||
|
||
### 前端（开发）
|
||
|
||
```bash
|
||
cd web && pnpm i && pnpm dev # http://localhost:5173（/api、/v1 代理到 8080）
|
||
```
|
||
|
||
### 测试
|
||
|
||
```bash
|
||
cd server && go test ./...
|
||
cd web && pnpm build # vue-tsc 类型检查 + 构建
|
||
```
|
||
|
||
### 主密钥与渠道密钥运维
|
||
|
||
渠道上游 key 用 `OT_MASTER_KEY` 经 AES-GCM 加密后落库。两个运维命令：
|
||
|
||
```bash
|
||
cd server
|
||
go run ./cmd/server check-channels # 诊断：当前主密钥能否解开全部渠道
|
||
go run ./cmd/server rotate-master-key # 迁移：旧密钥解密、新密钥重新加密
|
||
```
|
||
|
||
- **`failed to decrypt channel key`**：先跑 `check-channels`。它会打印主密钥派生路径与
|
||
密钥指纹（同指纹=同一把密钥）+ 逐渠道结果；全部失败基本就是主密钥变了。
|
||
- **从「没配主密钥」升级到「配置了主密钥」**：旧密文是用 `sha256("")` 加密的，
|
||
直接配新密钥会全部解不开。用 `rotate-master-key`（`--old` 留空即空密钥）迁移，
|
||
不需要重新录入任何渠道 key；全部渠道在一个事务里更新，解不开就整体回滚。
|
||
- **主密钥长度陷阱**：16/24/32 字节直接用原始字节，其他长度走 SHA-256 派生。
|
||
改长度等于换了一把密钥——轮换请用 `rotate-master-key`，不要直接改 `OT_MASTER_KEY`。
|
||
- 生产环境（`OT_ENV=production`）缺失主密钥、少于 16 字节或仍是示例占位值会拒绝启动；
|
||
开发环境允许为空，但启动时会打警告（空主密钥等于公开密钥）。
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
server/ # Go 后端
|
||
cmd/server/ # 入口
|
||
internal/
|
||
config/ # viper + env（OT_ 前缀）
|
||
store/ # GORM models + 连接
|
||
pkg/ # apikey / crypto / jwt / resp
|
||
api/ # 管理 API（认证、用户、密钥、用量、渠道/模型/管理后台）
|
||
proxy/ # 代理网关（鉴权、直通、流式、记账）
|
||
channel/ # 渠道选择与密钥解密
|
||
usage/ # 异步记账
|
||
web/ # Vue3 前端（Tailwind，taste-skill 设计 tokens）
|
||
src/
|
||
views/ # Landing / 登录注册 / console / admin
|
||
components/ # ui（Button/Input/Modal/Badge/Toast/TrendChart）+ layout
|
||
stores/ · api/ · router/ · lib/
|
||
scripts/mockupstream/ # mock 上游（联调）
|
||
deploy/ # Docker 部署（后续里程碑）
|
||
```
|