https://github.com/redredchen01/banner-studio

1200×248 Banner Studio image processing service with Celery async, WebSocket real-time feedback, and Gallery curation workflow. Python 3.11 + Flask + OpenCV AI face detection.
https://github.com/redredchen01/banner-studio

Last synced: 14 days ago
JSON representation

1200×248 Banner Studio image processing service with Celery async, WebSocket real-time feedback, and Gallery curation workflow. Python 3.11 + Flask + OpenCV AI face detection.

• Host: GitHub
• URL: https://github.com/redredchen01/banner-studio
• Owner: redredchen01
• Created: 2026-05-13T09:44:51.000Z (about 1 month ago)
• Default Branch: feat/ai-composition-integration
• Last Pushed: 2026-05-13T09:45:31.000Z (about 1 month ago)
• Last Synced: 2026-05-13T11:36:02.802Z (about 1 month ago)
• Language: Python
• Size: 1.15 MB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# 📸 Banner Studio 图片处理系统

> **版本 v0.4.0** · Python 3.11 · 611+ 测试通过 · Celery + WebSocket 实时反馈

PC 桌面主版位（1200×248）优先的智能图片处理服务。一张原图自动产出多规格（PC banner、移动卡片、母版等）；多张原图可进入 Gallery 做策展和批量预览。

## 🎯 核心特性

- **AI 人脸检测**：OpenCV Haar cascade + head-and-shoulders 完整包围盒对焦

- **多规格自动派生**：从 1200×248 主版位直接派生移动卡片、HD 宽屏等，避免二次失真

- **Gallery 策展工作流**：批量预览、标记/拒绝/置顶、CSV 导出、键盘快捷键

- **异步后台处理**：Celery 队列（独立 GPU 队列支持）+ Redis 缓存

- **实时进度反馈**：WebSocket 长连接、前端实时显示处理进度

- **生产级部署**：Canary 策略、性能基线监控、故障自动告警

## 📂 项目结构

```

resizer_0429/

├── README.md                          # 本文件

├── image-resizer/                     # 核心图片处理模块（Git submodule）

│   ├── master_system/

│   │   ├── config.py                  # 规格配置（frozen dataclass）

│   │   ├── core/

│   │   │   ├── face_detector.py       # 人脸检测 + 显著区识别

│   │   │   ├── face_compositor.py     # head-and-shoulders 裁切核心

│   │   │   ├── outpaint_engine.py     # 横向不足智能填充

│   │   │   ├── export_manager.py      # 主流水线编排

│   │   │   └── validator.py           # 输入验证 + 素材评分

│   │   ├── tests/                     # 611+ 单元 / 集成 / E2E 测试

│   │   └── main.py                    # CLI 入口

│   ├── start_web.py                   # Web 工作室入口

│   └── README.md                      # image-resizer 子模块详细文档

│

├── app.py                             # Flask 主应用 + WebSocket

├── celery_config.py                   # Celery 配置（GPU 队列）

├── celery_tasks.py                    # Celery 后台任务定义

├── requirements.txt                   # Python 依赖

│

├── docs/

│   ├── plans/                         # 技术规划与设计文档

│   ├── solutions/                     # 问题修复与最佳实践库

│   └── deployments/                   # 部署与监控方案

│

├── DEPLOYMENT_PLAN_2026-05-05.md      # 生产部署 Canary 策略

├── PRODUCTION_READINESS_2026-05-13.md # 生产就绪评估

└── COMPLETE_DEPLOYMENT_REPORT.md      # 完整部署报告

```

## 🚀 快速开始

### 本地开发（Web 工作室）

**macOS:**

```bash

# 方式1：便捷脚本

./启动Web服务.command

# 方式2：直接 Python

python3 start_web.py

```

**Windows:**

```bash

# 双击运行

启动Web服务.bat

```

**访问：** http://localhost:8080

### CLI 命令行

```bash

# 单图处理（推荐：包模式）

python3 -m master_system.main photo.jpg -o ./output

# 多图处理（自动取最高分主图）

python3 -m master_system.main photo1.jpg photo2.jpg photo3.jpg -o ./output

# JSON 输出（脚本集成）

python3 -m master_system.main photo.jpg -o ./output --json

```

### 生产部署（Gunicorn + Celery）

```bash

# 启动 Gunicorn（Flask Web）

gunicorn -c gunicorn.conf.py app:app

# 启动 Celery Worker（后台任务）

celery -A celery_tasks worker -l info -Q default,gpu

# 启动 Celery Beat（定时任务，如果需要）

celery -A celery_tasks beat -l info

```

**监控 Celery 任务：**

```bash

# 实时任务面板

celery -A celery_tasks events

```

## 📊 输出规格

| 规格 | 尺寸 | 用途 |

|------|------|------|

| `primary_banner` | 1200×248 | **PC 桌面主版位**（设计起点） |

| `master` | 1300×640 | 编辑端上传母版 |

| `card_medium` | 420×260 | 移动端卡片 |

| `landscape_hd` | 1920×400 | HD 宽屏横版 |

| `portrait_story` | 750×1334 | 手机竖版 Story（9:16） |

| `square_thumbnail` | 600×600 | 正方形缩略图 |

## 🔧 核心算法

1. **人脸检测**：OpenCV Haar cascade + FIFO 缓存（256 条）

2. **完整包围盒**：脸顶 +0.5×fh、脸底 +1.0×fh（≈2.5×fh 总高）

3. **自检 Retry**：距视口边 <8px 则自动降低 face_height_ratio（0.40→0.35→0.30）

4. **多脸策略**：单脸居中、双脸左右对称、三脸+ 取外接矩形

5. **横向填充**：原图宽度不足时自动 outpaint（同图镜像 + 高斯模糊）

6. **无脸兜底**：saliency 主体检测；失败时显式返回 None，调用方决定降级

7. **EXIF 修正**：手机竖拍照片自动方向修正；损坏时静默退化为原图

## 🎯 Gallery 策展工作流（v0.4.0）

上传 ≥2 张图后选择「批量预览 Gallery」：

- **可视化**：lightbox + safeZone overlay、逐张评估

- **快速标记**：`s`=select / `r`=reject / `p`=pin / `d`=delete / `?`=帮助

- **编辑操作**：filter bar、批量操作 toolbar、拖拽重排序

- **数据导出**：CSV 一键导出选中项及打分

- **状态持久化**：sessionStorage（`gallery_session` / `gallery_selection_v1` / `gallery_order_v1`）

## 💾 异步处理架构

### Celery 队列设计

```

队列 (Queue)          用途                   Worker 配置

─────────────────────────────────────────────────────────

default              图片处理主流程          标准 Worker

gpu                  GPU 密集任务            GPU Worker（专用）

                     （future-ready）

```

### 实时进度反馈（WebSocket）

- **连接**：客户端上传后建立长连接 `/ws/progress`

- **消息**：每秒推送当前处理进度（单位 %）

- **状态流**：`pending` → `processing` → `completed` / `failed`

- **前端显示**：实时进度条 + 预期完成时间估算

### 任务生命周期

```

POST /upload

  ↓

1. 前端验证（MIME type、尺寸）

2. 服务端入队（Celery）→ Redis 缓存任务 ID

3. Worker 处理（parallel pipeline）

4. WebSocket 推送实时进度

5. 完成 → 静态资源存储 → 返回下载链接

```

## 📈 性能基线

- **单图处理**：~220ms（含检测、裁切、导出）

- **Gallery 批处理**：N×220ms（可配置并行度）

- **单元测试覆盖**：99%

- **E2E 覆盖**：32 Chromium + 26 Firefox + 26 WebKit

## ✅ 测试与质量

```bash

# 运行单元 + 集成测试

python3 -m pytest -q

# 611+ passed, 1 skipped

# 代码覆盖率报告

python3 -m coverage run -m pytest && python3 -m coverage report

# 静态类型检查

python3 -m mypy master_system/

# 代码风格检查

ruff check master_system/ app.py celery_tasks.py

```

### E2E 测试（真实浏览器）

```bash

# 快速验证（Chromium）

make e2e-install && make e2e

# 完整验证（Chromium + Firefox + WebKit）

make e2e-install-cross && make e2e-cross

```

## 🛠️ 技术栈

| 层 | 技术 | 版本 |

|---|---|---|

| **语言** | Python | 3.11+ |

| **图像处理** | Pillow, NumPy, OpenCV | 最新 |

| **Web 框架** | Flask | 2.x |

| **异步队列** | Celery + Redis | 5.x |

| **实时通信** | WebSocket (python-socketio) | 5.x |

| **部署** | Gunicorn / Waitress | 最新 |

| **监控** | Prometheus + Grafana（optional） | 最新 |

## 📚 文档导航

| 文档 | 适用场景 |

|---|---|

| [image-resizer/README.md](./image-resizer/README.md) | 核心算法、API 详细说明 |

| [DEPLOYMENT_PLAN_2026-05-05.md](./DEPLOYMENT_PLAN_2026-05-05.md) | 生产 Canary 部署策略 |

| [PRODUCTION_READINESS_2026-05-13.md](./PRODUCTION_READINESS_2026-05-13.md) | 生产就绪评估清单 |

| [COMPLETE_DEPLOYMENT_REPORT.md](./COMPLETE_DEPLOYMENT_REPORT.md) | 部署验证详细报告 |

| [docs/solutions/](./docs/solutions/) | 问题修复库 & 最佳实践 |

## 🔐 配置与安全

### 环境变量

```bash

# Redis

REDIS_HOST=localhost

REDIS_PORT=6379

REDIS_DB=0

# Celery

CELERY_BROKER_URL=redis://localhost:6379/0

CELERY_RESULT_BACKEND=redis://localhost:6379/1

# Flask

FLASK_ENV=development|production

SECRET_KEY=

# 可选：Sentry 错误追踪

SENTRY_DSN=https://...

```

### 关键契约

- **Frozen Config**：`MASTER_CONFIG`、`OutputProfile` 是 frozen dataclass，运行时不可变

- **类型安全**：`PipelineResult` TypedDict 定义，静态自描述

- **统一异常**：`OutpaintRequired` 显式抛出，调用方逻辑清晰

- **PIL Bomb 防护**：`Image.MAX_IMAGE_PIXELS = 200M`（在加载时初始化）

- **极端纵横比拦截**：max/min ratio > 20.0 直接拒绝

## 📋 常见问题

**Q: 支持哪些图片格式？**

A: JPEG、PNG、WebP、GIF（单帧）。推荐 JPEG（压缩率最优）。

**Q: 如何自定义输出规格？**

A: 编辑 `image-resizer/master_system/config.py` 的 `OUTPUT_PROFILES`，然后重启服务。

**Q: 可以在 Docker 中部署吗？**

A: 可以。示例 Dockerfile 见 `DEPLOYMENT_PLAN_2026-05-05.md`。

**Q: 支持 GPU 加速吗？**

A: 是的。启用 GPU Worker：`celery -A celery_tasks worker -Q gpu -l info`。

**Q: 如何监控任务队列？**

A: 使用 Celery Flower（Web UI）：`pip install flower && celery -A celery_tasks flower`

## 🚢 发布历史

- **v0.4.0** (2026-05-07) — Gallery 策展、Celery 集成、WebSocket 实时反馈

- **v0.3.x** — head-and-shoulders 算法优化、多脸策略完善

- **v0.2.x** — 初版，多规格导出、CLI 支持

- **v0.1.x** — MVP，单图处理核心

详见 [image-resizer/CHANGELOG.md](./image-resizer/CHANGELOG.md)

## 👥 贡献

问题反馈或改进建议？请在 GitHub Issues 提交。

开发环境搭建：

```bash

git clone --recursive 

cd resizer_0429

pip install -r image-resizer/requirements.txt

python3 start_web.py

```

## 📄 许可

MIT License

---

**最后更新**：2026-05-13  

**维护者**：Banner Studio Team