Upload ADMIN_SETUP.md with huggingface_hub

ADMIN_SETUP.md

@@ -0,0 +1,101 @@
+# 管理员上线清单
+
+这份清单用于把中转站公开给大家使用，同时保护管理员权限和上游额度。
+
+## 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 太远。