README.md

metadata

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，先安装：

python -m pip install -U huggingface_hub
hf auth login

登录并确认工具可用：

hf auth whoami
git --version

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

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 执行：

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

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

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

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

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

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

查看日志：

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

生成随机密钥

在 PowerShell 中执行：

.\scripts\generate-secrets.ps1

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

测试 Supabase 连接

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

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

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

Admin API 验证

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

$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 一般是：

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

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

https://liuyiyang1439-sub2api.hf.space

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

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

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

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

Authorization: Bearer <user-api-key>

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