Spaces:

zlcy
/

li

Running

App Files Files Community

li / docs /deployment.md

xiaolongmr

init

85270f9 about 2 hours ago

preview code

Raw History Blame Contribute Delete

7.49 kB

部署与升级指南

本文介绍 ChatGPT2API 的常见部署方式，以及后续升级项目时需要保留的数据和执行步骤。

部署前准备

服务器需要安装：

Docker
Docker Compose v2
Git

首次部署前建议确认：

docker version
docker compose version
git --version

项目核心持久化文件：

路径	作用
`config.json`	主配置、后台密钥、代理、图片、备份等配置
`.env`	Docker compose 环境变量
`data/`	账号、注册配置、日志、图片、任务记录等运行数据

升级和迁移时重点保留以上内容。

方式一：普通 Docker 部署

适合不需要 WARP / FlareSolverr 清障的场景。

git clone git@github.com:basketikun/chatgpt2api.git
cd chatgpt2api

设置 config.json 中的 auth-key，或在 docker-compose.yml 中配置：

environment:
  - CHATGPT2API_AUTH_KEY=your_secret_key

启动：

docker compose up -d

访问：

http://localhost:3000

API 基础地址：

http://localhost:3000/v1

查看日志：

docker logs -f chatgpt2api

停止：

docker compose down

方式二：WARP / FlareSolverr 部署

适合注册流程经常遇到 Cloudflare 拦截的场景。该方式会启动：

warp-proxy
privoxy
flaresolverr
init-config
app

复制环境变量模板：

cp .env.example .env

至少修改 .env 中的：

CHATGPT2API_AUTH_KEY=your_secret_key_here

启动：

docker compose -f docker-compose.warp.yml up -d --build

访问：

http://localhost:3000

FlareSolverr 相关配置可以在后台设置页的 FlareSolverr tab 中查看和测试。更详细的 Cloudflare 清障说明见：

docs/flaresolverr-cloudflare.md

查看容器状态：

docker compose -f docker-compose.warp.yml ps

查看日志：

docker logs -f chatgpt2api-warp
docker logs -f chatgpt2api-flaresolverr

停止：

docker compose -f docker-compose.warp.yml down

方式三：源码运行

适合本地开发或临时调试。

后端：

git clone git@github.com:basketikun/chatgpt2api.git
cd chatgpt2api
uv sync
uv run main.py

前端开发服务：

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 天）。可用天数为：

每天可生成的图片数 ≈ 可用磁盘空间 ÷ 单图大小 ÷ image_retention_days

例如 50GB 空间、30 天保留，约合 830 张/天；把保留天数降到 7 天则提升到约 3600 张/天。容器磁盘非持久化时（如部分免费托管平台），重启会清空 data/，务必把 data/ 挂到卷上。

存储后端

默认使用本地 JSON 文件：

STORAGE_BACKEND=json

可选值：

值	说明
`json`	本地 JSON 文件，默认方式
`sqlite`	本地 SQLite，通常存放在 `data/accounts.db`
`postgres`	外部 PostgreSQL
`git`	Git 私有仓库存储账号数据

PostgreSQL 示例：

environment:
  - STORAGE_BACKEND=postgres
  - DATABASE_URL=postgresql://user:password@host:5432/dbname

SQLite 示例：

environment:
  - STORAGE_BACKEND=sqlite
  - DATABASE_URL=sqlite:////app/data/accounts.db

升级前备份

升级前建议备份：

mkdir -p backups
tar -czf backups/chatgpt2api-$(date +%Y%m%d-%H%M%S).tgz config.json .env data

如果没有 .env，可以去掉：

tar -czf backups/chatgpt2api-$(date +%Y%m%d-%H%M%S).tgz config.json data

也可以在后台设置页配置 Cloudflare R2 备份，用于定时备份关键数据。

升级：普通 Docker 部署

进入项目目录：

cd chatgpt2api

备份：

mkdir -p backups
tar -czf backups/chatgpt2api-$(date +%Y%m%d-%H%M%S).tgz config.json .env data

拉取最新代码和镜像：

git pull
docker compose pull
docker compose up -d

查看状态：

docker compose ps
docker logs -f chatgpt2api

升级：WARP / FlareSolverr 部署

进入项目目录：

cd chatgpt2api

备份：

mkdir -p backups
tar -czf backups/chatgpt2api-$(date +%Y%m%d-%H%M%S).tgz config.json .env data

拉取最新代码并重新构建：

git pull
docker compose -f docker-compose.warp.yml up -d --build

查看状态：

docker compose -f docker-compose.warp.yml ps
docker logs -f chatgpt2api-warp

升级：源码运行

cd chatgpt2api
git pull
uv sync

如果需要重新构建前端静态产物：

cd web
bun install
bun run build

然后按你的进程管理方式重启后端服务。

回滚

如果升级后需要回滚代码：

git log --oneline -n 20
git checkout <旧版本commit>

普通 Docker 部署：

docker compose up -d

WARP / FlareSolverr 部署：

docker compose -f docker-compose.warp.yml up -d --build

如果需要恢复数据：

tar -xzf backups/你的备份文件.tgz

恢复数据前建议先停止容器，避免运行中写入覆盖：

docker compose down

或：

docker compose -f docker-compose.warp.yml down

常用维护命令

查看容器：

docker compose ps

查看主服务日志：

docker logs -f chatgpt2api

查看 WARP 部署主服务日志：

docker logs -f chatgpt2api-warp

重启普通部署：

docker compose restart

重启 WARP 部署：

docker compose -f docker-compose.warp.yml restart

清理未使用镜像：

docker image prune