ChatGPT2API

ChatGPT2API 是一个面向自托管场景的 ChatGPT 官网能力封装服务，提供 OpenAI 兼容图片 API、在线创作台、账号池调度、图片库、日志治理、RBAC 权限管理和 Docker 部署能力。

• 快速入口
• 项目能力
• 快速部署
• 升级与在线更新
• 配置说明
• 本地开发
• 发布流程
• API 接入
• 截图
• 技术研究文档
• 社区与鸣谢

• Go 单体服务，容器内启动 /app/chatgpt2api。
• 前端构建产物嵌入 Go 二进制，由 Go 服务直接托管。
• 支持 Docker / Docker Compose 部署。
• 支持 SQLite、JSON 文件和 PostgreSQL 存储后端。
• 支持全局 HTTP / HTTPS / SOCKS5 / SOCKS5H 代理。
• 支持 DockerHub 默认版本检查，以及非 Docker Release 构建的在线更新和回滚。

• React 19 + Vite 管理端。
• 登录页、创作台、号池管理、图片库、用户管理、角色权限、日志管理和设置页。
• 本地账号密码登录，不再把部署密钥当作后台登录密钥。
• 首次启动自动初始化管理员；未配置密码时会生成一次性管理员密码并输出到启动日志。
• 内置 RBAC，统一管理菜单权限和 API 权限。
• 支持 Linuxdo OAuth 登录与本地账号共存。
• 支持个人 API 令牌管理。

• OpenAI 兼容图片生成接口：POST /v1/images/generations。
• OpenAI 兼容图片编辑接口：POST /v1/images/edits。
• 面向图片场景的 Chat Completions：POST /v1/chat/completions。
• 面向图片工具调用场景的 Responses：POST /v1/responses。
• Anthropic Messages 风格入口：POST /v1/messages。
• 异步创作任务资源：/api/creation-tasks。
• 支持 gpt-image-2、codex-gpt-image-2、auto 和多个 gpt-5* 文本/图片场景模型选项。

• 支持账号可用性、邮箱、类型、额度、恢复时间刷新。
• 支持轮询可用账号执行图片生成和图片编辑。
• 支持 Token 失效后自动剔除无效账号。
• 支持账号搜索、筛选、批量刷新、导出、编辑和清理。
• 支持本地 CPA JSON 文件导入、远程 CPA 服务器导入、Sub2API 服务器导入和 access token 直接导入。

git clone https://github.com/ZyphrZero/chatgpt2api.git
cd chatgpt2api
cp .env.example .env

编辑 .env。建议至少设置管理员密码：

CHATGPT2API_ADMIN_USERNAME=admin
CHATGPT2API_ADMIN_PASSWORD=change_me_please

如果不设置 CHATGPT2API_ADMIN_PASSWORD，服务首次启动会生成一次性管理员密码并输出到容器日志。

docker compose -f deploy/docker-compose.yml up -d

默认 Compose 配置：

• 镜像：zyphrzero/chatgpt2api:latest
• 端口：宿主机 3000 -> 容器 80
• 数据目录：./data:/app/data
• 环境文件：./.env:/app/.env
• 重启策略：restart: unless-stopped

访问：

http://localhost:3000

查看日志（需要在仓库根目录执行）：

docker compose -f deploy/docker-compose.yml logs -f app

查看自动生成的管理员密码（需要在仓库根目录执行）：

docker compose -f deploy/docker-compose.yml logs app | grep "bootstrap admin password generated"

日志行格式：

bootstrap admin password generated: username=admin password=生成的密码

docker compose -f deploy/docker-compose.yml logs app | Select-String "bootstrap admin password generated"

docker logs chatgpt2api 2>&1 | grep "bootstrap admin password generated"

grep -n "^CHATGPT2API_ADMIN_PASSWORD=" .env
docker inspect chatgpt2api --format '{{range .Config.Env}}{{println .}}{{end}}' | grep "^CHATGPT2API_ADMIN_PASSWORD="

cd /opt/chatgpt2api
# 编辑 .env，设置一个新的已知管理员密码：
# CHATGPT2API_ADMIN_PASSWORD=your_new_password

docker compose -f deploy/docker-compose.yml down
cp -a data "data.bak.$(date +%Y%m%d-%H%M%S)"
python3 - <<'PY'
import sqlite3
from pathlib import Path

db = Path("data/chatgpt2api.db")
if not db.exists():
    raise SystemExit(f"{db} not found")

con = sqlite3.connect(db)
cur = con.execute("DELETE FROM json_documents WHERE name = ?", ("auth_users.json",))
con.commit()
print(f"removed auth_users.json rows: {cur.rowcount}")
con.close()
PY
docker compose -f deploy/docker-compose.yml up -d

发布镜像由 GitHub Actions 构建。如果你需要在自己的服务器上从当前源码构建镜像，使用受限 BuildKit 脚本：

sh deploy/docker-build-limited.sh up

该脚本会创建独立的 docker-container Buildx builder，并对构建容器设置 CPU / 内存上限。直接运行时会按服务器资源自动选择默认值：最多使用 2 核；内存充足时默认放开到 3-4 GB；低内存机器才会降低 Go 编译并行度，避免 compile: signal: killed 这类 OOM：

sh deploy/docker-build-limited.sh up

如果你想显式放开配额：

BUILD_CPUS=2 BUILD_MEMORY=4g BUILD_MEMORY_SWAP=4g BUILD_GOMAXPROCS=2 BUILD_GOMEMLIMIT=2GiB sh deploy/docker-build-limited.sh up

如果只想构建本地镜像、不重启容器：

sh deploy/docker-build-limited.sh build

脚本使用 deploy/Dockerfile 从源码构建本地镜像，默认镜像名为 chatgpt2api:local；up 模式会继续用 deploy/docker-compose.yml 启动该本地镜像。

Docker 部署的推荐升级方式：

docker compose -f deploy/docker-compose.yml pull
docker compose -f deploy/docker-compose.yml up -d

默认 Compose 使用 DockerHub 公共镜像，普通用户不需要配置 GitHub Release 源、GitHub Token，也不需要登录 GitHub。也可以按需将 deploy/docker-compose.yml 的 image 改为 GHCR：

image: ghcr.io/zyphrzero/chatgpt2api:latest

可用镜像：

zyphrzero/chatgpt2api:latest
ghcr.io/zyphrzero/chatgpt2api:latest

设置页的“版本更新”卡片会按部署方式选择更新来源：

• Docker 镜像：默认匿名检查 DockerHub 公共镜像标签，升级方式是 docker compose -f deploy/docker-compose.yml pull && docker compose -f deploy/docker-compose.yml up -d。
• Release 二进制：检查项目 GitHub Release，只有这种非 Docker 部署会显示“立即更新”并替换当前 chatgpt2api 二进制。

Release 二进制在线更新流程：

1. 后端请求项目 latest release。
2. 比较当前版本和最新版本。
3. 下载当前平台匹配的 Release 压缩包。
4. 校验 checksums.txt。
5. 替换当前 chatgpt2api 二进制。
6. 保留 .backup 以支持回滚。
7. 前端提示重启服务。

重要说明：

• Docker 部署默认从 DockerHub 拉取镜像，不需要填写 GitHub Release 源或 GitHub Token。
• Docker 容器内不会执行二进制替换；请用 docker compose -f deploy/docker-compose.yml pull && docker compose -f deploy/docker-compose.yml up -d 更新镜像。
• 在线二进制替换只在非 Docker 的 BuildType=release 构建中开放。
• 前端资源已嵌入 Release 二进制，在线更新只替换 chatgpt2api 这一个运行文件。
• 检查更新访问 DockerHub / Release API 可通过 CHATGPT2API_UPDATE_PROXY_URL 配置代理；未设置时复用 CHATGPT2API_PROXY。
• 正式 Release archive 只发布 Linux amd64 / arm64 构建；Windows 和 macOS 不提供在线更新压缩包。

源码部署请使用 Git 和本地构建流程：

git pull
bun install --cwd web --frozen-lockfile
bun --cwd web run build
go test ./...
go build -tags=embed -ldflags "-X chatgpt2api/internal/version.Version=1.0.0" -o chatgpt2api ./internal

运行时配置统一写入 .env。容器部署时，平台环境变量也可以覆盖 .env 中的同名变量。

SQLite 示例：

STORAGE_BACKEND=sqlite
DATABASE_URL=sqlite:////app/data/chatgpt2api.db

PostgreSQL 示例：

STORAGE_BACKEND=postgres
DATABASE_URL=postgresql://user:password@host:5432/chatgpt2api

MySQL 示例：

STORAGE_BACKEND=mysql
DATABASE_URL=mysql://user:password@host:3306/chatgpt2api

新部署默认使用 SQLite，并自动创建 data/chatgpt2api.db。本地 JSON 文件存储后端已移除，STORAGE_BACKEND=json 不再支持。

Linuxdo OAuth 是可选能力。启用前需要在 Linuxdo Connect 后台创建应用，并配置后端 OAuth 回调地址。

CHATGPT2API_LINUXDO_ENABLED=true
CHATGPT2API_LINUXDO_CLIENT_ID=your-client-id
CHATGPT2API_LINUXDO_CLIENT_SECRET=your-client-secret
CHATGPT2API_LINUXDO_REDIRECT_URL=https://your-domain.com/auth/linuxdo/oauth/callback
CHATGPT2API_LINUXDO_FRONTEND_REDIRECT_URL=/auth/linuxdo/callback

注意：

• Linuxdo Connect 应用后台应填写后端回调地址：/auth/linuxdo/oauth/callback。
• CHATGPT2API_LINUXDO_FRONTEND_REDIRECT_URL 是前端接收本地会话的路由，不要填到 Linuxdo Connect 应用后台。
• 如果未显式设置 CHATGPT2API_LINUXDO_REDIRECT_URL，且已配置 CHATGPT2API_BASE_URL，后端会自动推导回调地址。

bun install --cwd web --frozen-lockfile
bun --cwd web run build
go test ./...
go build -tags=embed -ldflags "-X chatgpt2api/internal/version.Version=0.0.0-dev" -o chatgpt2api ./internal
CHATGPT2API_ADMIN_PASSWORD=change_me_please ./chatgpt2api

后端默认监听：

http://127.0.0.1:8000

也可以通过 PORT 指定端口：

PORT=8000 ./chatgpt2api

cd web
bun install
bun run dev

前端开发服务器默认会通过 VITE_API_URL 访问后端。未设置时，开发模式默认使用：

http://127.0.0.1:8000

前端验证命令：

cd web
bun run lint
bun run build

项目使用 GitHub Actions + GoReleaser 发布。

.github/workflows/ci.yml 在 main push 和 pull request 上执行：

• go test ./...
• bun install --frozen-lockfile
• bun run build
• docker compose -f deploy/docker-compose.yml config

推送 v* 标签会触发 .github/workflows/release.yml：

1. 构建前端。
2. 上传 internal/web/dist artifact。
3. 将前端 artifact 下载到 internal/web/dist。
4. GoReleaser 使用 -tags=embed 构建 Linux amd64 / arm64 二进制。
5. 生成 GitHub Release archive 和 checksums.txt。
6. 使用 deploy/Dockerfile.release 构建多架构 Docker 镜像。
7. 推送 DockerHub 镜像。
8. 推送 GHCR 镜像。

发布命令示例：

git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

Release 构建会注入：

• chatgpt2api/internal/version.Version
• chatgpt2api/internal/version.Commit
• chatgpt2api/internal/version.Date
• chatgpt2api/internal/version.BuildType=release

默认发布到 DockerHub：

zyphrzero/chatgpt2api:<version>
zyphrzero/chatgpt2api:latest
zyphrzero/chatgpt2api:<major>.<minor>

同时发布到 GHCR：

ghcr.io/zyphrzero/chatgpt2api:<version>
ghcr.io/zyphrzero/chatgpt2api:latest
ghcr.io/zyphrzero/chatgpt2api:<major>.<minor>

所有受保护的 AI 接口都需要请求头：

Authorization: Bearer <session-or-api-token>

后台登录后可以在个人资料或用户管理中创建 API 令牌。

图片生成、图片编辑、异步创作任务、轮询、取消、输出格式、文本型结果和错误码的完整说明见 生图接口文档

权限系统中，异步创作任务对应的 API 权限为 GET /api/creation-tasks 和 POST /api/creation-tasks，并按子路径生效。

curl http://localhost:3000/v1/models \
  -H "Authorization: Bearer <session-or-api-token>"

curl http://localhost:3000/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session-or-api-token>" \
  -d '{
    "model": "auto",
    "prompt": "一只漂浮在太空里的猫",
    "n": 1,
    "response_format": "b64_json"
  }'

字段说明：

gpt-image-2 和 auto 走 ChatGPT 官网图片工作台的纯协议链路：当前按官网 HAR 实抓对齐到底层 gpt-5-5 模型，请求 /backend-api/f/conversation 建立 SSE，并从 role=tool 且 async_task_type=image_gen 的上游消息里提取图片结果。部分会话/续图场景里官网还会补发 /backend-api/f/conversation/prepare 获取 conduit_token，但不是每次首发生成前都显式出现。codex-gpt-image-2 仍保留为独立的 Codex 图片协议模型，继续走 /backend-api/codex/responses 路线，用于和官网图片额度区分。Free 账号不会被本地预先拦截；如果账号没有对应图片工具权限，上游可能直接返回失败。

size 可以传 auto、比例值（如 1:1、16:9、9:16）、分辨率档位（1080p、2k、4k）或显式 WIDTHxHEIGHT。在纯协议工作台链路下，这些信息会作为上游提示词约束参与构图，不再转换为 Codex Responses 专用的工具尺寸字段。

curl http://localhost:3000/v1/images/edits \
  -H "Authorization: Bearer <session-or-api-token>" \
  -F "model=auto" \
  -F "prompt=把这张图改成赛博朋克夜景风格" \
  -F "n=1" \
  -F "image=@./input.png"

字段说明：

图片编辑同样按模型分流：gpt-image-2、auto 走官网图片工作台纯协议链路，codex-gpt-image-2 走独立的 Codex 图片协议链路。

该接口面向图片场景，不是完整通用聊天代理。

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session-or-api-token>" \
  -d '{
    "model": "auto",
    "messages": [
      {
        "role": "user",
        "content": "生成一张雨夜东京街头的赛博朋克猫"
      }
    ],
    "modalities": ["image"],
    "n": 1
  }'

该接口面向图片生成工具调用场景，不是完整通用 Responses API 代理。

curl http://localhost:3000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session-or-api-token>" \
  -d '{
    "model": "gpt-5.5",
    "input": "生成一张未来感城市天际线图片",
    "tools": [
      {
        "type": "image_generation",
        "model": "gpt-image-2"
      }
    ],
    "tool_choice": {
      "type": "image_generation"
    }
  }'

以下截图均来自仓库的 assets/ 目录。

创作台	任务队列
图片库	提示词管理
号池管理	角色与权限
日志管理	注册管理

项目包含对 ChatGPT 官网生图链路的完整逆向分析，详见 jshook/ 目录：

Telegram 群组：ChatGPT2API

学 AI，上 L 站：LinuxDO

• banana-prompt-quicker，作者：阿良
• awesome-gpt-image-2-prompts
• ChatGpt-Image-Studio，作者：小怪兽
• sub2api

感谢所有为本项目做出贡献的开发者：