gpt-image-linux 项目理解报告

仓库：Z1rconium/gpt-image-linux · 版本 v0.4.0 · commit c045bbf · 生成时间 2026-05-17 13:52

FastAPISvelteKitSQLite自托管图片面板

一句话定位

这是一个自托管 GPT 兼容图片 API Web 面板：前端提供生成/编辑/图库/设置界面，后端把请求转发到外部 GPT-compatible Image API，并把图片与任务元数据落到本地。

当前状态

v0.4.0

最新提交：chore: release v0.4.0|2026-05-17T12:48:43+08:00

Docker 可部署有合同测试中英界面

规模概览

Python：38 文件 / 约 9.3k 行
前端 TS/Svelte/CSS：31 文件 / 约 3.8k 行
合同测试：单文件约 2.2k 行
主要依赖：FastAPI、aiohttp、Pydantic、Pillow、SvelteKit、Tailwind

核心功能

图片生成：/api/generate 创建后台任务，支持模型、尺寸、质量、格式、压缩、数量、webhook。
图片编辑：/api/edits 或从图库选择源图，转发到上游 /v1/images/edits。
多上游预设：保存 API base URL、path、key、模型与 SOCKS5 代理；可用环境变量引用 API Key。
任务系统：SQLite 持久化任务，内存保存活跃 task；SSE 推送单任务和任务列表进度；支持取消。
图库：本地文件 + SQLite 元数据，支持筛选、搜索、收藏、下载、批量操作、ZIP 导入/导出、缩略图。
访问控制：ACCESS_KEY 会话 cookie、IP allowlist、反代 header 信任开关、失败锁定。
安全防护：CSP nonce、SSRF 校验、host allowlist、ZIP bomb 限制、文件路径安全校验、webhook 签名与重试。

架构分层

浏览器
SvelteKit 静态前端
同源调用 /api

FastAPI
路由、鉴权、SSE、静态资源、CSP

任务层
asyncio 队列/并发限制
SQLite job 持久化

上游客户端
Images / Responses / Chat Completions
下载/解析图片结果

存储
images/ 文件
data/app.sqlite3

目录职责

backend/app/api/routers：access、generate、edits、gallery、settings、static。
backend/app/integrations/upstream_client.py：对上游图片 API 的请求构造、SSE/JSON 解析、图片下载与校验。
backend/app/repositories/storage.py：SQLite schema、设置/任务/图库持久化。
frontend/src/lib/stores：settings/gallery/jobs/preview/ui 状态管理。

支持的上游路径

/v1/images/generations：标准图片生成。
/v1/responses：解析 Responses 输出中的 image_generation_call。
/v1/chat/completions：从文本/markdown/data URL/HTTP URL 中抽取图片。

base URL 可含或不含 /v1，后端会规范拼接。

部署方式

cp .env.example .env
# 设置 ACCESS_KEY、DEFAULT_API_URL、DEFAULT_API_KEY 等
docker-compose up -d --build --force-recreate
# 默认只绑定 127.0.0.1:9090

Dockerfile 是多阶段构建：Node 构建 Svelte 静态产物，Python runtime 安装依赖并用 uvicorn 运行。

关键环境变量

DEFAULT_API_URL / DEFAULT_API_KEY / DEFAULT_API_PATH
ACCESS_KEY 或显式 ALLOW_UNAUTHENTICATED=true
IP_ALLOWLIST、TRUST_PROXY_HEADERS
MAX_ACTIVE_GENERATE_JOBS、MAX_QUEUED_GENERATE_JOBS
UPSTREAM_HOST_ALLOWLIST、WEBHOOK_HOST_ALLOWLIST、WEBHOOK_SIGNING_SECRET

公开 API 面

类别	接口	说明
访问	`GET /api/access/status` `POST /api/access`	检查/提交访问 key。
设置	`GET/POST /api/settings` `POST /api/settings/presets` `POST /api/settings/presets/<id>/activate`	管理 API 预设、Key、路径和代理。
生成/编辑	`POST /api/generate` `POST /api/edits`	创建异步任务。
任务	`GET /api/generate/jobs` `GET /api/generate/jobs/events` `GET /api/generate/<job_id>/events` `DELETE /api/generate/<job_id>`	任务列表、SSE、查询、取消。
图库	`GET /api/gallery` `GET /api/image/<filename>` `GET /api/download-all` `POST /api/import`	浏览、下载、导入导出、批量操作。

优点

职责划分清楚，前后端边界和 API 合同明确。
部署简单，默认本地绑定，适合放在 Nginx 后面。
对实际使用体验考虑较多：SSE、历史、重试、图库筛选、批量下载。
安全意识较强：鉴权、CSP、SSRF、ZIP 限制、webhook 签名。
支持多种上游兼容路径，适合接 OpenAI-compatible 代理。

风险与注意

默认必须设置 ACCESS_KEY；公网部署不要开启未鉴权。
API Key 可存入 SQLite 预设；若多人共用机器，应保护 data/app.sqlite3 权限和备份。
上游 URL 默认要求 HTTPS 且拒绝私网解析；如果你的上游是内网代理，需要理解并调整 allowlist/校验策略。
活跃任务 task 只在内存中；进程重启会把运行中任务标记 interrupted。
并发默认较小，适合个人面板；多人/高并发要调队列、反代超时和磁盘容量。
README 存在一处本地开发说明截断：ALLOW_UNAUTHENTICATED=*** 那行未闭合。

适合谁用

想把 GPT Image / 兼容图片生成 API 做成个人 Web 面板的人。
已有本地或远端 OpenAI-compatible 代理，希望保存历史图片、提示词和任务状态的人。
想要轻量部署，不想引入复杂队列/对象存储/账号系统的个人或小团队。

不适合：多租户 SaaS、强权限隔离、超高并发、需要对象存储/CDN/审计计费的生产级商业平台；这些需要额外改造。

如果部署到你的服务器的建议

用 Docker Compose，保持 127.0.0.1:9090 绑定，只通过 Nginx HTTPS 暴露。
必须设置强 ACCESS_KEY，不要公网 ALLOW_UNAUTHENTICATED=true。
若接本机 CLIProxyAPI，需要确认上游 URL 校验是否允许该地址；当前代码偏向要求 HTTPS 公网上游。
把 images/ 和 data/ 加入备份；SQLite 中可能含 API Key，不要公开。
配置磁盘清理或图库导出策略，防止图片长期堆积。

验证来源：本地浅克隆仓库、README、Dockerfile、Compose、后端路由/设置/任务/上游客户端/存储代码、前端 API/stores 代码。未执行真实图片生成，因为需要外部图片 API Key。