首次初始化与最小可用配置

服务启动只是基础设施就绪。还需要完成管理员、安全、账号、分组和测试 Key 配置，才能真正发送模型请求。

两种初始化方式

Docker Auto Setup

Compose 设置 AUTO_SETUP=true，应用会自动：

1. 读取数据库和 Redis 环境变量。
2. 连接依赖。
3. 执行数据库迁移。
4. 创建管理员。
5. 生成或持久化配置。
6. 启动正式服务。

管理员密码为空时在日志中生成。

ADMIN_EMAIL/ADMIN_PASSWORD 只在数据库完全没有用户时创建管理员。初始化完成后修改这两个环境变量不会重置已有账号；登录校验以 PostgreSQL 的 users.password_hash 为准。完整启动判断见启动、配置与事实来源。

设置向导

二进制首次启动会进入 Web 设置服务，浏览器填写数据库、Redis 和管理员。源码环境也可以运行：

cd backend
go run ./cmd/server --setup

第一次登录

登录后不要立即开放注册，先完成：

1. 修改或确认管理员强密码。
2. 配置固定 TOTP key 后启用管理员 TOTP。
3. 设置站点名称、外部 URL 和时区。
4. 检查注册、支付、邮件和 OAuth 是否默认关闭。
5. 接受管理员合规确认。

添加第一个账号

选择你实际拥有授权的上游类型：

不知道选择 API Key、OAuth、Setup Token 或第三方兼容上游时，先阅读上游账号池运维。原则上不直接保存上游网站账号密码；第三方兼容服务通常也按“对应平台 + API Key + 自定义 Base URL”创建，而不是选择通用 upstream 类型。

API Key

• 选择平台和 apikey 类型。
• 填写 API Key 与 Base URL（官方地址可用默认）。
• 如需代理先创建 Proxy。
• 设置较保守并发，例如 1–3。
• 保存后运行账号测试。

OAuth

• 先配置相应 OAuth client secret。
• 从管理员账号页面发起授权。
• 确认 access/refresh token 已保存。
• 检查 plan、quota、expires_at 和 privacy 状态。

首次测试只使用一个账号，减少调度变量。

创建测试分组

建议：

name: anthropic-test / openai-test
platform: 与账号一致
status: active（仅测试阶段）
rate multiplier: 1.0
exclusive: true
rpm limit: 低值

把第一个账号加入分组，先不配置复杂模型路由、fallback、高峰倍率和图片视频功能。

创建测试用户和 Key

1. 创建普通用户，初始余额给一个小额测试值。
2. 显式授权测试分组。
3. 以用户身份登录。
4. 创建 API Key，绑定测试分组。
5. 保存完整 Key。

不要直接用管理员账号承担正式流量。

模型发现

python3 - <<'PY'
import json, urllib.request

req = urllib.request.Request(
    'https://api.example.com/v1/models',
    headers={'Authorization': 'Bearer sk-your-sub2api-key'},
)
with urllib.request.urlopen(req) as response:
    print(json.dumps(json.load(response), indent=2))
PY

确认目标模型出现，并理解展示模型是否需要额外映射。

最小文本测试

Anthropic 格式：

curl https://api.example.com/v1/messages \
  -H 'content-type: application/json' \
  -H 'x-api-key: sk-your-sub2api-key' \
  -d '{
    "model": "your-model",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "reply only: ok"}]
  }'

OpenAI Responses 格式：

curl https://api.example.com/v1/responses \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer sk-your-sub2api-key' \
  -d '{
    "model": "your-model",
    "input": "reply only: ok"
  }'

流式测试

使用 curl -N 确认事件逐步返回：

curl -N https://api.example.com/v1/messages \
  -H 'content-type: application/json' \
  -H 'x-api-key: sk-your-sub2api-key' \
  -d '{
    "model": "your-model",
    "stream": true,
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "count 1 to 5"}]
  }'

请求后的四项核对

用户使用记录

确认模型、端点、Token、费用、账号和状态正确。

用户余额/订阅

确认只扣了一次，窗口用量变化符合预期。

账号状态

确认 last used、并发和今日统计更新，没有异常冷却。

运维错误

确认没有 pricing not found、usage worker error 或协议转换 warning。

再逐步开启功能

推荐顺序：

1. 第二个同平台账号和 failover。
2. 账号并发与用户并发。
3. 模型映射。
4. 粘性会话。
5. 工具调用与 thinking。
6. 用户订阅和额度。
7. 渠道展示。
8. 图片、视频或 WebSocket。
9. 注册、邮件、OAuth。
10. 支付。

每增加一层功能都保留一组可重复的 smoke test。