Hugging Face's logo

Spaces:
zlcy
/
study
Paused

App Files Community
study / docs /deployment.md
xiaolongmr
1
6daa87a
preview code
|
Raw History Blame Contribute Delete
7.49 kB
# 部署与升级指南
本文介绍 ChatGPT2API 的常见部署方式，以及后续升级项目时需要保留的数据和执行步骤。
## 部署前准备
服务器需要安装：
- Docker
- Docker Compose v2
- Git
首次部署前建议确认：
```bash
docker version
docker compose version
git --version
```
项目核心持久化文件：
| 路径 | 作用 |
| --- | --- |
| `config.json` | 主配置、后台密钥、代理、图片、备份等配置 |
| `.env` | Docker compose 环境变量 |
| `data/` | 账号、注册配置、日志、图片、任务记录等运行数据 |
升级和迁移时重点保留以上内容。
## 方式一：普通 Docker 部署
适合不需要 WARP / FlareSolverr 清障的场景。
```bash
git clone git@github.com:basketikun/chatgpt2api.git
cd chatgpt2api
```
设置 `config.json` 中的 `auth-key`，或在 `docker-compose.yml` 中配置：
```yaml
environment:
- CHATGPT2API_AUTH_KEY=your_secret_key
```
启动：
```bash
docker compose up -d
```
访问：
```text
http://localhost:3000
```
API 基础地址：
```text
http://localhost:3000/v1
```
查看日志：
```bash
docker logs -f chatgpt2api
```
停止：
```bash
docker compose down
```
## 方式二：WARP / FlareSolverr 部署
适合注册流程经常遇到 Cloudflare 拦截的场景。该方式会启动：
- `warp-proxy`
- `privoxy`
- `flaresolverr`
- `init-config`
- `app`
复制环境变量模板：
```bash
cp .env.example .env
```
至少修改 `.env` 中的：
```text
CHATGPT2API_AUTH_KEY=your_secret_key_here
```
启动：
```bash
docker compose -f docker-compose.warp.yml up -d --build
```
访问：
```text
http://localhost:3000
```
FlareSolverr 相关配置可以在后台设置页的 `FlareSolverr` tab 中查看和测试。更详细的 Cloudflare 清障说明见：
```text
docs/flaresolverr-cloudflare.md
```
查看容器状态：
```bash
docker compose -f docker-compose.warp.yml ps
```
查看日志：
```bash
docker logs -f chatgpt2api-warp
docker logs -f chatgpt2api-flaresolverr
```
停止：
```bash
docker compose -f docker-compose.warp.yml down
```
## 方式三：源码运行
适合本地开发或临时调试。
后端：
```bash
git clone git@github.com:basketikun/chatgpt2api.git
cd chatgpt2api
uv sync
uv run main.py
```
前端开发服务：
```bash
cd web
bun install
bun run dev
```
源码方式运行时，后端默认读取项目根目录的 `config.json` 和 `data/`。
## 并发与容量调优
并发上限由四道闸门依次决定，**改配置前先确认自己在撞哪一道**：
| 闸门 | 容量 | 生效范围 |
|---|---|---|
| ① 账号槽位 | `账号数 × image_account_concurrency`（默认 3） | 只有生图 |
| ② 线程池 | `thread_pool_tokens`（默认 40） | 全站（含对话、图片、Skill、后台任务） |
| ③ CPU | Pillow 解码/编码持 GIL | 全站 |
| ④ 磁盘 | 图片总量 / `image_retention_days` | 全站 |
**② 线程池（`thread_pool_tokens`）**
本项目的阻塞调用统一经 `run_in_threadpool` 分发，容量取自 anyio 的默认线程限流器，anyio 把它硬编码为 40。该值可在设置页「线程池并发上限」调整（范围 4-512），**保存后立即生效，无需重启**。
判断要不要调高：**只有 `账号数 × 单账号图片并发` 大于 40 时才值得调**。例如 3 账号 × 3 = 9 路，占用远不到 40，调高线程池没有任何收益。反过来，账号数上百时它才是真瓶颈。
调高不等于变快：它只允许更多请求同时处于「排队上传」状态，单张图的耗时不变，而且并发压向上游账号更容易触发限流。
**另一条不受线程池约束的生图链路**
网页对话页的生图走 `/api/image-tasks/*`，每个任务独立开一条守护线程（不经线程池），因此**不受 `thread_pool_tokens` 限制**；`/v1/images/*` 等 API 入口才经过它。两条链路都要经过账号槽位。
**④ 磁盘（最容易被忽略的一环）**
单张图约 2MB，保留天数由 `image_retention_days` 控制（默认 30 天）。可用天数为：
```text
每天可生成的图片数 ≈ 可用磁盘空间 ÷ 单图大小 ÷ image_retention_days
```
例如 50GB 空间、30 天保留，约合 **830 张/天**；把保留天数降到 7 天则提升到约 3600 张/天。容器磁盘非持久化时（如部分免费托管平台），重启会清空 `data/`，务必把 `data/` 挂到卷上。
## 存储后端
默认使用本地 JSON 文件：
```text
STORAGE_BACKEND=json
```
可选值：
| 值 | 说明 |
| --- | --- |
| `json` | 本地 JSON 文件，默认方式 |
| `sqlite` | 本地 SQLite，通常存放在 `data/accounts.db` |
| `postgres` | 外部 PostgreSQL |
| `git` | Git 私有仓库存储账号数据 |
PostgreSQL 示例：
```yaml
environment:
- STORAGE_BACKEND=postgres
- DATABASE_URL=postgresql://user:password@host:5432/dbname
```
SQLite 示例：
```yaml
environment:
- STORAGE_BACKEND=sqlite
- DATABASE_URL=sqlite:////app/data/accounts.db
```
## 升级前备份
升级前建议备份：
```bash
mkdir -p backups
tar -czf backups/chatgpt2api-$(date +%Y%m%d-%H%M%S).tgz config.json .env data
```
如果没有 `.env`，可以去掉：
```bash
tar -czf backups/chatgpt2api-$(date +%Y%m%d-%H%M%S).tgz config.json data
```
也可以在后台设置页配置 Cloudflare R2 备份，用于定时备份关键数据。
## 升级：普通 Docker 部署
进入项目目录：
```bash
cd chatgpt2api
```
备份：
```bash
mkdir -p backups
tar -czf backups/chatgpt2api-$(date +%Y%m%d-%H%M%S).tgz config.json .env data
```
拉取最新代码和镜像：
```bash
git pull
docker compose pull
docker compose up -d
```
查看状态：
```bash
docker compose ps
docker logs -f chatgpt2api
```
## 升级：WARP / FlareSolverr 部署
进入项目目录：
```bash
cd chatgpt2api
```
备份：
```bash
mkdir -p backups
tar -czf backups/chatgpt2api-$(date +%Y%m%d-%H%M%S).tgz config.json .env data
```
拉取最新代码并重新构建：
```bash
git pull
docker compose -f docker-compose.warp.yml up -d --build
```
查看状态：
```bash
docker compose -f docker-compose.warp.yml ps
docker logs -f chatgpt2api-warp
```
## 升级：源码运行
```bash
cd chatgpt2api
git pull
uv sync
```
如果需要重新构建前端静态产物：
```bash
cd web
bun install
bun run build
```
然后按你的进程管理方式重启后端服务。
## 回滚
如果升级后需要回滚代码：
```bash
git log --oneline -n 20
git checkout <旧版本commit>
```
普通 Docker 部署：
```bash
docker compose up -d
```
WARP / FlareSolverr 部署：
```bash
docker compose -f docker-compose.warp.yml up -d --build
```
如果需要恢复数据：
```bash
tar -xzf backups/你的备份文件.tgz
```
恢复数据前建议先停止容器，避免运行中写入覆盖：
```bash
docker compose down
```
或：
```bash
docker compose -f docker-compose.warp.yml down
```
## 常用维护命令
查看容器：
```bash
docker compose ps
```
查看主服务日志：
```bash
docker logs -f chatgpt2api
```
查看 WARP 部署主服务日志：
```bash
docker logs -f chatgpt2api-warp
```
重启普通部署：
```bash
docker compose restart
```
重启 WARP 部署：
```bash
docker compose -f docker-compose.warp.yml restart
```
清理未使用镜像：
```bash
docker image prune
```
不要直接删除 `data/`、`config.json`、`.env`，除非已经确认有可用备份。