| # 管理员上线清单 |
|
|
| 这份清单用于把中转站公开给大家使用，同时保护管理员权限和上游额度。 |
|
|
| ## 1. Space 设置 |
|
|
| 在 Hugging Face 创建 Space 时： |
|
|
| - SDK 选择 `Docker` |
| - Visibility 选择 `Public` |
| - 不要把任何真实密钥写进仓库文件 |
|
|
| 部署成功后，公开地址通常是： |
|
|
| ```text |
| https://<owner>-<space>.hf.space |
| ``` |
|
|
| 例如 Hugging Face 用户名是 `liuyiyang1439`，Space 名叫 `zhongzhuanzhan`： |
|
|
| ```text |
| https://liuyiyang1439-zhongzhuanzhan.hf.space |
| ``` |
|
|
| 普通用户调用地址是： |
|
|
| ```text |
| 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` 填你自己保存好的强密码。部署成功后用它们登录管理后台。 |
|
|
| 可以用下面命令生成随机密钥： |
|
|
| ```powershell |
| .\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 太远。 |
|
|
