README.md

---
title: New API
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# New API 中转 (Hugging Face Spaces 部署)

基于官方镜像 `calciumion/new-api`，部署在 HF Spaces 上作为 LLM API 中转网关。

## 部署步骤

1. 在 https://huggingface.co/new-space 新建 Space
   - **SDK** 选择 `Docker` → `Blank`
   - 建议把可见性设为 **Private**（中转里有你的密钥，别公开）
2. 把本文件夹（`hf-newapi/`）里的 `Dockerfile` 和 `README.md` 推到 Space 仓库根目录：
   ```bash
   git clone https://huggingface.co/spaces/<你的用户名>/<space名> hf-space
   # 复制 Dockerfile 和 README.md 进去
   cd hf-space
   git add . && git commit -m "deploy new-api" && git push
   ```
3. Space 会自动构建并启动，访问 Space URL 进入初始化页面，设置管理员账号密码。

## 持久化（重点）

HF Spaces 默认的容器磁盘是**临时的**，重启/重建会清空。要持久保留数据，二选一：

### 方案 A：开启 HF 持久化存储（最简单）
- 进入 Space → **Settings → Persistent storage**，选一档（最小档即可）。
- 开启后会挂载到 `/data`，本镜像已把 SQLite 设到 `/data/new-api.db`，数据自动持久化。

### 方案 B：使用外部数据库（免费持久化，推荐长期用）
- 准备一个外部 MySQL / PostgreSQL（如 free tier 的云数据库）。
- 在 Space → **Settings → Variables and secrets** 添加 Secret：
  - `SQL_DSN`
    - MySQL: `user:password@tcp(host:3306)/dbname`
    - PostgreSQL: `postgresql://user:password@host:5432/dbname`
- 设置了 `SQL_DSN` 后会自动用外部库，SQLite 不再使用，重建 Space 也不丢数据。

## 建议设置的 Secrets（Settings → Variables and secrets）

| 名称 | 说明 |
|------|------|
| `SESSION_SECRET` | 固定一个随机字符串，避免重启后登录态失效 |
| `SQL_DSN` | 用外部数据库时填（方案 B） |
| `TZ` | 时区，例如 `Asia/Shanghai` |

## 注意
- 中转网关属于会存放密钥的服务，务必把 Space 设为 Private 并设强管理员密码。
- 端口已固定为 7860 以匹配 HF 入口，无需改动。