Upload README.md with huggingface_hub

README.md

@@ -1,6 +1,5 @@
 ---
-title: Sub2API Gateway
-emoji: 🔑
+title: sub2api API Gateway
 colorFrom: blue
 colorTo: green
 sdk: docker
@@ -8,4 +7,168 @@ app_port: 7860
 pinned: false
 ---
 
-Sub2API Gateway - AI API中转服务
+# 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` 发给用户。