ADMIN_SETUP.md

管理员上线清单

这份清单用于把中转站公开给大家使用，同时保护管理员权限和上游额度。

1. Space 设置

在 Hugging Face 创建 Space 时：

• SDK 选择 Docker
• Visibility 选择 Public
• 不要把任何真实密钥写进仓库文件

部署成功后，公开地址通常是：

https://<owner>-<space>.hf.space

例如 Hugging Face 用户名是 liuyiyang1439，Space 名叫 zhongzhuanzhan：

https://liuyiyang1439-zhongzhuanzhan.hf.space

普通用户调用地址是：

https://<owner>-<space>.hf.space/v1

.hf.space 是 Hugging Face 固定后缀，不能改；你能自定义的是 <owner> 和 <space>。

2. 必填 Secrets

在 Space 的 Settings -> Variables and secrets 添加：

• ADMIN_EMAIL
• ADMIN_PASSWORD
• JWT_SECRET
• TOTP_ENCRYPTION_KEY

如果暂时不配置 Supabase，Space 会使用临时 PostgreSQL 启动，适合先测试后台。正式给大家长期使用时，再添加：

• DATABASE_HOST
• DATABASE_USER
• DATABASE_PASSWORD

你自己当管理员时，ADMIN_EMAIL 填你的管理员邮箱，ADMIN_PASSWORD 填你自己保存好的强密码。部署成功后用它们登录管理后台。

可以用下面命令生成随机密钥：

.\scripts\generate-secrets.ps1

3. 创建用户和普通 API Key

进入 sub2api 管理后台后：

• 添加上游账号或渠道
• 创建用户分组
• 设置分组倍率、额度、可用模型
• 给用户创建普通 API Key
• 把 PUBLIC_USAGE.md 中的 Base URL 和用户 API Key 发给用户

不要把下面这些内容发给普通用户：

• 管理员登录密码
• 全局 Admin API Key
• Supabase 密码
• 上游渠道 Key
• HF Token

4. 公开使用建议

• 每个用户单独发一个 API Key，方便限额和封禁。
• 新用户先给小额度测试。
• 给不同用户组设置不同模型和倍率。
• 出现异常消耗时，先禁用对应用户 API Key，而不是删除数据库数据。
• 定期检查使用日志、失败率和上游账号状态。

5. 用量统计和卡顿排查

后台的用量统计依赖数据库里的 usage_logs。正式使用时请务必配置 Supabase Postgres；如果只用临时 PostgreSQL，Space 休眠、重启或迁移后用量数据会丢失，看起来就像“没有统计”。

流式 Chat Completions 请求会由网关向上游强制启用 stream_options.include_usage=true，请求结束后写入用量记录。它不是逐字实时刷新，而是一次请求结束后很快出现在后台用量页；如果上游本身不返回 usage，token 数可能只能显示为 0 或依赖估算逻辑。

这个 HF 部署包默认写入了适合小机器的网关配置：

• 降低账号失败切换次数，避免模型名或上游异常时长时间等待。
• 降低上游连接池和 OpenAI WebSocket 池规模，减少免费 CPU/内存压力。
• 将 usage 记录队列溢出策略设为 sync，尽量避免高负载时丢用量记录。
• 缩短流式 keepalive 间隔，让客户端更快收到连接仍然活跃的信号。

如果仍然卡，优先检查：

• Space 是否刚从休眠唤醒。
• 是否使用了不存在的模型名。
• 上游账号是否 429、限流、余额不足或响应慢。
• 国内到 Hugging Face 的网络是否不稳定。
• Supabase 所在区域是否离 Hugging Face 太远。