| --- |
| 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` 发给用户。 |
|
|
