| --- |
| title: anuma2api |
| emoji: 🚀 |
| colorFrom: blue |
| colorTo: purple |
| sdk: docker |
| pinned: false |
| --- |
| |
| # Deploy anuma2api to Hugging Face (Persistent Storage) |
|
|
| 把网关跑在 HF Space 上，账号凭据 / config / 日志存在 **Space 持久存储**（重启不丢）。 |
|
|
| ## 一键部署 |
|
|
| 1. 打开 https://huggingface.co/new-space |
| - **Owner**: 选你自己 |
| - **Space name**: 任意，如 `anuma2api` |
| - **License**: 随意 |
| - **SDK**: **Docker**（重要） |
| - 点 **Create Space** |
|
|
| 2. 本地把这个目录内容推到 Space（目录已自包含 App 代码，直接全量推）： |
| ```bash |
| cd hf_space |
| # 在 Space 页面 Settings → Repo → 复制 git 地址（形如 https://huggingface.co/spaces/<你>/anuma2api） |
| git init |
| git add . |
| git commit -m "anuma2api HF space" |
| git remote add origin https://huggingface.co/spaces/<你>/anuma2api |
| git push -u origin main |
| ``` |
| （Space 上 Docker SDK 会自己构建并运行 `Dockerfile`；覆盖旧项目用 `git push -f`。） |
| ⚠️ 若在前一版部署过（hf_space 缺构建源），Docker 构建上下文错误可导致 `COPY pyproject.toml not found` —— 本目录已含 `app/ registrar/ scripts/ pyproject.toml` 全部构建源。 |
| |
| 3. **启用持久存储**（关键）：Space 页面 **Settings → Persistent Storage → New Volume** |
| - 挂载点填 **`/data`**，存储选默认（免费档 50GB）。 |
| - 重启 Space 生效。 |
| |
| 4. **配置账号**： |
| - **推荐：本地跑注册机**生成 `account/*.json`，然后通过**管理面板上传**（见下），不把凭据 push 进 git。 |
| - 或 SSH 进 Space 手动放 `/data/account/`（不持久在 git，仅容器内）。 |
| |
| 5. Space 构建完成后，App 页面即 `http://localhost:7860`（HF 自动分配 https 域名）。 |
| 健康检查：`https://<你>-anuma2api.hf.space/healthz` |
| |
| 6. 在 Cherry Studio 配 OpenAI 兼容服务： |
| - 地址 `https://<你>-anuma2api.hf.space/v1` |
| - 模型 / API key 照旧。 |
| |
| ## 管理面板上传账号（推荐） |
| |
| Space 跑起来后，直接用浏览器管理面板传账号，**不用 git、不用 SSH、凭据不进仓库**： |
| |
| 1. 打开 `https://<你>-anuma2api.hf.space/admin`，输入 `config.toml` 里 `[admin].auth_key`。 |
| 2. 「账号管理」页点 **📤 上传账号文件**。 |
| - 选本地注册机生成的 `account/*.json`（可多选），或把多个打包成 `.zip` 一次传（zip 里只提取 `.json`）。 |
| - 同名账号覆盖更新；上传后自动热加载，**无需重启**。 |
| 3. 上传完立刻出现在列表里，可直接「💰 查余额」验证。 |
|
|
| > 注册机只在本地跑：本地注册 → 面板上传 → HF 上的网关直接用。HF 上不放注册机。 |
|
|
| ## API Key 管理（面板） |
|
|
| Cherry 等客户端连 `/v1/*` 用的鉴权 key，面板里直接管： |
|
|
| 1. 打开 `/admin`，切到 **API Key** tab。 |
| 2. **＋ 生成 Key**：输入名称（可选）点生成，key 自动复制到剪贴板；同一网关可持多个 key（不同客户端各用各的）。 |
| 3. 删除：点行内「删」，确认后 key 立即失效。 |
| 4. 兼容：config 里 `[gateway] api_key` 填的 key 依然有效（老客户端不用改）；全部 key 删空 + config 留空 = 无认证。 |
|
|
| Key 存 `/data/logs/api_keys.json`（持久化，重启不丢；已在 http_log 脱敏保护内）。 |
| |
| ## 端口与持久化说明 |
| |
| - HF 强制监听 `$PORT`（通常 7860），`init_and_run.sh` 自动用 `$PORT` 覆盖 config 里的 `port = 8088`。 |
| - 所有可变数据都在 `/data`： |
| | 数据 | 路径 | |
| |---|---| |
| | 网关配置 | `/data/config.toml` | |
| | 账号凭据 | `/data/account/*.json` | |
| | 日志 | `/data/logs/gateway.log` | |
| | 用量统计 | `/data/logs/usage.db` | |
| | 生图最近 URL | `/data/logs/.last_image_urls.json` | |
| - 镜像内 `config.toml` / `account/` 只是种子，首启拷进 `/data` 后一切改动以 `/data` 为准。 |
| |
| ## 注意 |
| |
| - **不要**把真实账号凭据 push 进 git 仓库（public Space 会泄露）。用 private Space；本地 `account/` 已被 `.gitignore` 排除，账号一律走面板上传（见上）。 |
| - 免费 Space 的 CPU 有额度，`uvicorn` 是单进程；够个人用。 |
| - 若你在墙内访问 HF Space，Cherry 需要能连上 `*.hf.space`。 |
| |
