---
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`。