README.md

---
title: sub2api API Gateway
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# sub2api API Gateway

这是一个中文化、可公开部署的 sub2api 中转站模板，用于 Hugging Face Spaces + Supabase Postgres。应用本体来自 `weishaw/sub2api:latest`，本仓库只保存启动脚本和部署说明；数据库使用 Supabase Postgres 持久化。

公开给大家用时，推荐方式是：

- Hugging Face Space 设置为 `Public`，让大家都能打开网页。
- 管理员密码、Admin API Key、上游渠道 Key 全部只放在后台或 HF Secrets，绝不公开。
- 给普通用户发放 sub2api 的用户 API Key，并按用户/分组设置倍率、额度和可用模型。
- 用户用自己的普通 API Key 调用 `/v1` 接口，不使用管理员 Key。

默认情况下，如果没有配置 Supabase 数据库，Space 会使用容器内临时 PostgreSQL 先启动，方便你马上打开后台测试。临时库会在 Space 重启、迁移或休眠恢复时丢数据；正式给大家长期使用时，请配置 Supabase。

## 文件

- `Dockerfile`: HF Space Docker 入口。
- `start-space.sh`: 从 HF Secrets 准备运行环境，启动 Redis/Postgres，并交给应用自动初始化。
- `.env.example`: 需要配置到 HF Space Secrets 的变量清单。
- `scripts/check-supabase.mjs`: 部署前测试 Supabase Postgres 连接。
- `PUBLIC_USAGE.md`: 发给普通用户看的中文使用说明。
- `ADMIN_SETUP.md`: 管理员上线、发 key、控额度的中文操作清单。

## 必填 Secrets

在 Hugging Face Space 的 `Settings -> Variables and secrets` 中添加：

- `ADMIN_PASSWORD`
- `JWT_SECRET`
- `TOTP_ENCRYPTION_KEY`

如果要持久保存用户、账号、密钥和用量记录，再添加 Supabase Postgres：

- `DATABASE_HOST`
- `DATABASE_USER`
- `DATABASE_PASSWORD`

推荐同时添加：

- `DATABASE_PORT=5432`
- `DATABASE_DBNAME=postgres`
- `DATABASE_SSLMODE=require`
- `ADMIN_EMAIL=2691539771@qq.com`

`JWT_SECRET` 建议至少 32 位随机字符。`TOTP_ENCRYPTION_KEY` 需要使用十六进制随机字符串，推荐用 `scripts/generate-secrets.ps1` 生成。

## 部署到 Hugging Face Space

如果本机还没有 Hugging Face CLI，先安装：

```powershell
python -m pip install -U huggingface_hub
hf auth login
```

登录并确认工具可用：

```powershell
hf auth whoami
git --version
```

创建 Docker Space。想让大家都可以用，创建时 Visibility 选择 `Public`：

```powershell
hf repo create <space-name> --type space --space_sdk docker
git clone https://huggingface.co/spaces/<owner>/<space-name>
Copy-Item Dockerfile,start-space.sh,.gitignore,.gitattributes,.env.example,README.md,PUBLIC_USAGE.md,ADMIN_SETUP.md,package.json <space-repo>\
Copy-Item -Recurse scripts <space-repo>\
Set-Location <space-repo>
git add .
git commit -m "Deploy sub2api on HF Space"
git push
```

如果本机没有 `hf` CLI，也可以用本仓库自带脚本。先在 Hugging Face 创建一个 `Write` 权限 token，然后在 PowerShell 执行：

```powershell
$env:HF_TOKEN = "hf_xxx"
.\scripts\deploy-hf-space.ps1 -Owner liuyiyang1439 -SpaceName sub2api
```

脚本会创建公开 Docker Space，并把当前仓库文件推送到：

```text
https://huggingface.co/spaces/liuyiyang1439/sub2api
```

配置 Secrets 后重启 Space。健康状态应满足：

- 容器监听 `0.0.0.0:7860`
- `/health` 返回成功
- 日志没有缺少 Secrets 或数据库连接错误

本模板会在启动时写入一组适合 Hugging Face 小机器的运行参数：降低连接池和 WebSocket 池规模、减少失败账号切换等待、把 usage 记录队列溢出策略设为同步回写。这样后台用量更不容易漏记，免费 CPU 上的卡顿也会少一些。需要覆盖时，可在 Space Secrets 中设置 `.env.example` 里的可选性能变量。

查看日志：

```powershell
hf spaces logs <owner>/<space> -n 300
```

## 生成随机密钥

在 PowerShell 中执行：

```powershell
.\scripts\generate-secrets.ps1
```

把输出的 `JWT_SECRET` 和 `TOTP_ENCRYPTION_KEY` 添加到 HF Space Secrets。`ADMIN_PASSWORD` 请单独设置为你自己保存好的强密码。

## 测试 Supabase 连接

本地创建 `.env`，填入 `.env.example` 中的数据库变量后执行：

```powershell
npm install pg dotenv
node scripts/check-supabase.mjs
```

脚本只会测试连接并打印数据库名和时间，不会写入数据。

## Admin API 验证

在 sub2api 管理后台生成全局 Admin API Key 后，可用只读接口验证：

```powershell
$headers = @{ "x-api-key" = "<admin-api-key>"; "accept" = "application/json" }
Invoke-RestMethod `
  -Uri "https://<owner>-<space>.hf.space/api/v1/admin/dashboard/stats" `
  -Headers $headers `
  -Method GET
```

全局 Admin API Key 只用于管理接口，不要发给客户当模型调用 key 使用。客户调用模型时使用 sub2api API Key 管理里创建的普通用户 key。

## 给普通用户的调用地址

部署成功后，普通用户的 Base URL 一般是：

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

其中 `<owner>` 是你的 Hugging Face 用户名或组织名，`<space>` 是 Space 名称。你当前页面显示的 Owner 是 `liuyiyang1439`，Space 名叫 `sub2api` 时，公开网页就是：

```text
https://liuyiyang1439-sub2api.hf.space
```

普通用户调用接口时使用：

```text
https://liuyiyang1439-sub2api.hf.space/v1
```

注意：`.hf.space` 是 Hugging Face 固定后缀，不能改成别的。

普通用户需要使用你发放的用户 API Key：

```http
Authorization: Bearer <user-api-key>
```

可以直接把 `PUBLIC_USAGE.md` 发给用户。