ADMIN_SETUP.md

# 管理员上线清单

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

## 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 太远。