# 管理员上线清单 这份清单用于把中转站公开给大家使用，同时保护管理员权限和上游额度。 ## 1. Space 设置 在 Hugging Face 创建 Space 时： - SDK 选择 `Docker` - Visibility 选择 `Public` - 不要把任何真实密钥写进仓库文件 部署成功后，公开地址通常是： ```text https://-.hf.space ``` 例如 Hugging Face 用户名是 `liuyiyang1439`，Space 名叫 `zhongzhuanzhan`： ```text https://liuyiyang1439-zhongzhuanzhan.hf.space ``` 普通用户调用地址是： ```text https://-.hf.space/v1 ``` `.hf.space` 是 Hugging Face 固定后缀，不能改；你能自定义的是 `` 和 ``。 ## 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 太远。