FLUX Studio

基于 FLUX.2-dev 的图像生成平台,支持纯文生图与多图融合(图生图)。提供上传图片、设置提示词/步数/引导强度/输出尺寸、提交任务、实时查看进度、取消与删除任务等完整 workflow。

项目采用前后端分离 + 异步任务队列的架构,GPU 推理与 Web 服务解耦——模型常驻在单独的 GPU 服务器上,Web 平台本身不需要 GPU。

┌────────────┐   /api/*   ┌──────────┐  enqueue   ┌───────┐  pop task   ┌────────┐  HTTP multipart  ┌───────────┐
│  Frontend  │ ─────────> │ Backend  │ ─────────> │ Redis │ ─────────> │ Worker │ ───────────────> │ Model API │
│ (React+Vite)│            │ (FastAPI)│            │       │            │        │                  │  (GPU)    │
└────────────┘ <────────── └──────────┘ <────────── └───────┘ <────────── └────────┘ <─────────────── └───────────┘
                 poll tasks     ↑ 写状态 pub/sub      ↑ 写结果               ↑ 推理/进度/取消
                                 │                     │                       │ Flux2Pipeline (常驻显存)
                          ┌──────┴──────┐       ┌───────┴────┐
                          │ PostgreSQL  │       │  持久化文件 │
                          └─────────────┘       └────────────┘

1. 前端上传图片 → backend POST /api/upload → 落盘 + DB
2. 前端提交生成 → backend POST /api/generate → DB 建任务(置 queued)→ Redis 入队
3. Worker 弹任务 → 置 running → 把图片上传给 model-api → 调 mix-generation-pro
4. model-api 用 Flux2Pipeline 推理,步进回调写进度,返回 PNG
5. Worker 保存 PNG → 发 completed 事件 → backend 写回 DB 与 output 文件名
6. 前端轮询 /api/tasks 展示进度与结果;可 cancel / delete

针对任务所处的不同阶段,采用组合策略保证取消可见且不产生孤儿状态:

• 队列中未弹出:Redis 预置 cancel flag,worker pop 后预检即直接置 cancelled。
• 已在 model-api 推理:backend 经 HTTP 调 model-api/v1/cancel/{task_id},model-api 的步进回调检测到 cancel event 即在下个 step 抛异常中止推理。
• 已终态(completed/failed/cancelled):幂等返回当前状态,不再重复发事件。

• Docker + Docker Compose
• 一台 GPU 服务器,已部署 model-api/app.py(需 CUDA、diffusers、FLUX.2-dev 4-bit 模型)

Web 平台本身的四组件(frontend/backend/worker/redis/db)无需 GPU,部署在普通服务器即可。

cp .env.example .env
# 编辑 .env,重点修改:
#   MODEL_API_URL   —— 指向你单独部署的 GPU 模型服务,如 http://192.168.1.50:8000
#   DB_PASSWORD     —— 生产环境请改强密码
#   FRONTEND_PORT / BACKEND_PORT / DATA_DIR —— 按服务器实际调整

在 GPU 服务器上运行 model-api/app.py。它会加载 FLUX.2-dev 4-bit 模型并监听 0.0.0.0:8000:

cd model-api
pip install -r requirements.txt
# 需预先准备:diffusers 的 Flux2Pipeline + FLUX.2-dev 4-bit 模型权重
python app.py
# 服务 Ready 后,确保 MODEL_API_URL 指向该机器的可达地址

在仓库根目录:

./scripts/deploy.sh
# 或手动:
docker compose up -d --build

启动后:

• 前端:http://<服务器IP>:<FRONTEND_PORT>(默认 8080)
• API 文档:http://<服务器IP>:<BACKEND_PORT>/docs(默认仅绑 127.0.0.1:8081,从外网访问需 SSH 隧道或反向代理)

前端

cd frontend
pnpm install      # 或 npm install
pnpm dev          # 默认 5173,自动代理 /api 到本机 8081

后端 / worker:需本地可达 PostgreSQL 与 Redis(可用 compose 仅起这两个服务:docker compose up -d redis db)。

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8081   # 需设置 DATABASE_URL / REDIS_URL / MODEL_API_URL 等环境变量

cd ../worker
python main.py     # 同样需 REDIS_URL / MODEL_API_URL / OUTPUT_DIR / UPLOAD_DIR

Model API(由 GPU 服务器提供):POST /v1/mix-generation-pro、GET /v1/progress/{task_id}、POST /v1/cancel/{task_id}。

完整项见 .env.example。

.
├── frontend/        # React + Vite 前端
├── backend/         # FastAPI 后端(app/api, app/services, app/models, app/queue)
├── worker/          # 任务执行 HTTP 客户端(无 GPU)
├── model-api/       # GPU 推理服务(Flux2Pipeline,独立部署)
├── redis/           # Redis 数据卷挂载点
├── data/            # uploads / outputs / pg 数据(gitignored)
├── scripts/deploy.sh
├── docker-compose.yml
└── .env.example

• model-api 不在 docker-compose.yml 中——GPU 与依赖环境各异,需在 GPU 服务器上按实际情况单独部署,compose 中的 backend/worker 通过 MODEL_API_URL 调用它。
• Docker 镜像构建时使用 TUNA(清华)PyPI/Debian 镜像源以加速国内构建,如需更换可在各 Dockerfile 中调整。
• .env 不会进入 git(已 gitignore);.env.example 是配置模板。
• data/、redis/、node_modules、构建产物等均已 gitignore。