# gen2d **Repository Path**: hezhaohui123/gen2d ## Basic Information - **Project Name**: gen2d - **Description**: 🎨 AI 驱动的 2D 游戏素材生成工具。通过文本提示词或可视化参数，快速生成风格一致、管线友好的 Sprite、背景、UI 与动画帧。支持 Unity/Godot 一键集成，兼顾生成效率、画质与低成本工作流。 - **Primary Language**: Go - **License**: MIT - **Default Branch**: master - **Homepage**: http://47.121.181.112:9000/ - **GVP Project**: No ## Statistics - **Stars**: 5 - **Forks**: 0 - **Created**: 2026-05-23 - **Last Updated**: 2026-07-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: AI, Gamemaker, qiniu, 2d, UI ## README # gen2d > ⚠️ 注意：当前为 v2 版本文档，对应代码在 [v2](https://gitee.com/hezhaohui123/gen2d/tree/v2/) 分支。 > > 线上服务器已部署 v2 版本，v1 版本（master分支）即将弃用 > > 若要查看 v1 版本文档，查看这里 [README_old](README_old.md)

AI 驱动的 2D 游戏素材生成工具
文本描述 + 风格参数 → 风格一致、管线友好的 Sprite、背景、UI 与动画帧
无缝融入 Unity / Godot 等主流 2D 游戏引擎工作流

在线体验 | 文档 | 快速开始 | API

> 🎈 **哔哩哔哩视频**：【七牛云 XEngineer 暑期实训营 | 2D 游戏素材 | 团体作品演示】 https://www.bilibili.com/video/BV1jAGo6DEbC > 🔥 **在线体验**：http://47.121.181.112:9000/ --- ## 目录 - [特性](#特性) - [架构总览](#架构总览) - [快速开始](#快速开始) - [配置](#配置) - [API](#api) - [技术栈](#技术栈) - [项目结构](#项目结构) - [部署](#部署) - [文档](#文档) - [路线图](#路线图) - [参与贡献](#参与贡献) - [License](#license) ## 特性 - **多智能体协作管线** — PromptOptimizer → AssetGenerator → QualitySupervisor → FormatAdapter，基于 Eino `compose.Graph` 编排，支持质检重试与降级输出 - **有界并发协程池** — `NumCPU*4` Worker 并行处理，per-user 限流、背压保护、优雅关闭 - **可插拔任务队列** — Memory / RabbitMQ 双实现，Consumer-Producer 桥接解耦提交与执行 - **SSE 实时推送** — 内存 EventBus 发布/订阅，浏览器 EventSource 接收管线各阶段进度 - **提示词优化** — 40+ 标签映射 + Eino Chain 驱动，支持任意 OpenAI 兼容 API，无 key 时自动回退模板 - **风格系统** — 预设美术风格、色调、线条、场景、光照、情绪等维度，支持工程级与任务级风格覆盖 - **精灵图处理** — 背景移除 → 投影切割 → 后处理 → GIF 预览，游戏引擎友好格式 - **三级降级** — Queue → Pool → Legacy 降级链，宁可降级不可阻塞 - **可观测性** — 35 Prometheus 指标 + Grafana 仪表盘 + 告警规则 - **一键部署** — Docker Compose + Prometheus + Grafana，`deploy.sh` 脚本 ## 架构 > 详细架构说明见 [docs/00-索引.md](docs/00-索引.md)。 ### 系统总览经典分层架构：Gin HTTP Server → Handler → Service → 基础设施 → 外部依赖。轻量级 Set\*/Init\* 函数注入，Viper 三层配置级联（环境变量 > YAML > 默认值），零配置可启动。 ![系统总览](docs/png/01-system-overview.png) ### 协程池有界并发协程池，`NumCPU*4` Worker 并行处理任务。per-user 限流防止单用户占满池，`select + default` 非阻塞背压拒绝，30 秒超时优雅关闭。 ![协程池](docs/png/02-worker-pool.png) ### 任务队列可插拔 `TaskQueue` 接口，Memory（Go channel）/ RabbitMQ（AMQP 持久化）双实现，工厂模式一行切换。Consumer 桥接队列与协程池，三级降级链：Queue → Pool → Legacy。 ![任务队列](docs/png/03-task-queue.png) ### 精灵图处理自动管线：背景移除 → 两阶段投影检测（全局行投影 + 逐行列投影）→ MinFillRatio 过滤 → trimAlpha 裁剪 → padToLargest 底部居中对齐 → GIF 预览。将一张 AI 生成的 Sprite Sheet 无缝转化为可用的逐帧动画资源。 ![精灵图处理](docs/png/06-sprite-processing.png) ### SSE 实时推送内存 EventBus 发布/订阅，Pipeline 通过 `ProgressReporter` 回调发布进度事件，SSE Handler 订阅推送给浏览器 EventSource。支持任务级（`tasks/:id/stream`）和工程级（`projects/:id/stream`）两种订阅模式，慢消费者非阻塞丢弃。 ![SSE 实时推送](docs/png/08-sse-push.png) ### 限流 Redis Lua 原子令牌桶，双层限流（全局 + 用户）保护核心接口。Redis 不可用时自动 Fail-Open 降级，优先保证服务可用性。 ![限流](docs/png/09-rate-limiting.png) ### 标签驱动提示词工程 40+ 预定义标签（7 大类别：内容类型、美术风格、色调、线条、场景、光照、情绪）精确映射到图像生成指令。命中网格标签时自动注入间隙布局指令，保障下游投影切割算法可靠性。LLM 不可用时自动回退模板生成。 ![标签驱动提示词](docs/png/13-prompt-engineering.png) ## 快速开始 ### 环境要求 - Go 1.26+ - Node.js 20+ - Docker & Docker Compose（部署用） ### 后端 ```bash cd backend cp .env.example .env # 编辑 .env 填入 API key go mod tidy go run cmd/main.go ``` 服务默认运行在 `http://localhost:8080`。 ### 前端 ```bash cd frontend npm install npm run dev ``` 开发服务器运行在 `http://localhost:5173`，通过 Vite proxy 转发 `/api` 和 `/auth` 请求到后端。 ## 配置配置通过 Viper 三层级联，优先级从高到低：**环境变量 > YAML 文件 > 代码默认值**。 | 配置块 | 环境变量前缀 | 关键字段 | |--------|-------------|----------| | `server` | `GEN2D_*` | port, mode | | `database` | `GEN2D_DSN` | dsn | | `jwt` | `GEN2D_JWT_*` | secret, expire | | `llm` | `GEN2D_LLM_*` | base_url, api_key, model | | `image_gen` | `GEN2D_IMAGE_*` | base_url, api_key, model | | `redis` | `GEN2D_REDIS_*` | addr, password | | `workerpool` | `GEN2D_WORKERPOOL_*` | workers, queue_size, max_per_user | | `taskqueue` | `GEN2D_TASKQUEUE_*` | driver, memory.buffer_size, rabbitmq.* | > 详细配置说明见 [docs/15-配置级联机制.md](docs/15-配置级联机制.md)。 ## API 接口统一前缀 `/api/v1/`，统一响应格式： ```json { "code": 0, "message": "ok", "data": {} } ``` 除健康检查和注册登录外，所有接口需通过 `Authorization: Bearer ` 认证。 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/v1/health` | 健康检查 | | POST | `/auth/register` | 用户注册 | | POST | `/auth/login` | 用户登录（返回 JWT Token） | | POST | `/api/v1/prompt/optimize` | 提示词优化 | | GET/POST | `/api/v1/projects` | 工程列表 / 创建工程 | | GET/PUT/DELETE | `/api/v1/projects/:id` | 工程详情 / 更新 / 删除 | | GET/PUT | `/api/v1/projects/:id/style` | 工程风格读写 | | POST | `/api/v1/generate` | 提交生成任务 | | GET | `/api/v1/tasks/:id` | 任务状态与进度 | | GET | `/api/v1/tasks/:id/assets` | 生成结果素材列表 | | GET | `/api/v1/tasks/:id/stream` | SSE 任务级实时进度 | | GET | `/api/v1/projects/:id/stream` | SSE 工程级实时进度 | | GET | `/api/v1/assets/download` | 下载素材（重定向到 CDN） | ## 技术栈 | 层 | 技术 | 说明 | |---|------|------| | 后端语言 | Go 1.26 | — | | HTTP 框架 | Gin v1.12 | 路由、中间件、JSON 绑定 | | 管线编排 | [Eino](https://github.com/cloudwego/eino) v0.8 | `compose.Graph` + `compose.Chain` | | ORM | GORM + SQLite / MySQL | 零配置数据库 | | 认证 | JWT (golang-jwt) + bcrypt | 无状态认证 | | 配置 | Viper + godotenv | 三层配置级联 | | 消息队列 | RabbitMQ (AMQP) | 可选，持久化任务队列 | | 限流 | Redis Lua 令牌桶 | 分布式限流，Fail-Open | | 对象存储 | 七牛云 Kodo | CDN 加速、私有 Bucket 签名访问 | | 前端框架 | React 18 + TypeScript 5.6 | 函数组件 + Hooks | | 构建工具 | Vite 6 | HMR 开发体验 | | 状态管理 | Zustand 5 | 轻量、不可变状态 | | 样式 | CSS Modules + CSS 自定义属性 | 主题切换 | | 容器化 | Docker 多阶段构建 | nginx 反向代理 | | 监控 | Prometheus + Grafana | 35 指标 + 仪表盘 | ## 项目结构 ``` gen2d/ ├── backend/ # Go + Gin API 服务 │ ├── cmd/main.go # 入口：加载配置 → DI → 注册路由 → 启动 │ ├── internal/ │ │ ├── config/ # Viper 三层配置加载 │ │ ├── handler/ # HTTP 处理器 │ │ ├── service/ # 业务逻辑 │ │ │ ├── pipeline.go # Eino Graph 4 阶段管线 │ │ │ ├── prompt_agent.go # Eino Chain 提示词优化 │ │ │ └── inference.go # 文生图推理 │ │ ├── model/ # 数据模型 │ │ ├── mildware/ # 中间件（Auth, Logger, Recovery, Metrics, RateLimit） │ │ └── pkg/ # 基础设施 │ │ ├── workerpool/ # 有界并发协程池 │ │ ├── taskqueue/ # 可插拔任务队列（Memory / RabbitMQ） │ │ ├── eventbus/ # 内存事件总线 │ │ └── ratelimiter/ # Redis 令牌桶限流 │ └── pkg/ │ ├── splitsprite/ # 精灵表拆分 │ └── gifmaker/ # GIF 预览生成 ├── frontend/ # Vite + React 前端 │ └── src/ │ ├── api/ # HTTP 客户端 │ ├── components/ # UI 组件 │ ├── pages/ # 页面 │ ├── stores/ # Zustand 状态管理 │ └── hooks/ # 自定义 Hooks ├── docs/ # 中文架构文档（16 篇） │ ├── 00-索引.md # 文档导航 │ ├── 01-系统总览.md # 分层架构与 DI │ ├── 02-协程池.md ~ 15-配置级联机制.md │ ├── drawio/ # 架构图源文件 │ └── png/ # 架构图 PNG ├── docker-compose.yml # 容器编排 └── deploy.sh # 一键部署脚本 ``` ## 部署 ### Docker Compose ```bash cd backend cp .env.example .env # 编辑填入 API key cd .. docker compose up -d --build ``` - 后端：Go 多阶段构建，暴露 8080 端口 - 前端：Node 构建 + nginx 反向代理，默认映射宿主机 10000 端口 - 数据持久化：`backend-data` 卷挂载 SQLite 数据库与生成素材 ### 一键脚本 ```bash bash deploy.sh ``` 自动完成仓库克隆/拉取、环境检查、`.env` 模板复制、`docker compose up`。 ## 文档完整架构文档见 [docs/](docs/) 目录，共 16 篇： | # | 文档 | 主题 | |---|------|------| | 1 | [01-系统总览](docs/01-系统总览.md) | 分层架构、DI、配置级联 | | 2 | [02-协程池](docs/02-协程池.md) | 有界并发、per-user 限流、背压 | | 3 | [03-任务队列](docs/03-任务队列.md) | 可插拔接口 + Memory / RabbitMQ | | 4 | [04-RabbitMQ集成](docs/04-RabbitMQ集成.md) | AMQP 连接、持久化消息、重试/死信 | | 5 | [05-生成管线](docs/05-生成管线.md) | Eino 4 阶段图 + 质量回退 + 降级 | | 6 | [06-精灵图处理](docs/06-精灵图处理.md) | 背景移除 → 切割 → GIF 预览 | | 7 | [07-可观测性](docs/07-可观测性.md) | Prometheus 指标 + Grafana 仪表盘 | | 8 | [08-SSE实时推送](docs/08-SSE实时推送.md) | EventBus → SSE → EventSource | | 9 | [09-限流](docs/09-限流.md) | Redis 令牌桶 + 双层限流 | | 10 | [10-中间件链](docs/10-中间件链.md) | Logger → Recovery → Metrics → Auth → RateLimit | | 11 | [11-Consumer-Producer桥接](docs/11-Consumer-Producer桥接.md) | TaskQueue → Consumer → WorkerPool | | 12 | [12-三级降级策略](docs/12-三级降级策略.md) | Queue → Pool → Legacy 降级链 | | 13 | [13-标签驱动提示词工程](docs/13-标签驱动提示词工程.md) | 40+ 标签映射 + 风格一致性 | | 14 | [14-部署架构](docs/14-部署架构.md) | Docker Compose + Prometheus + Grafana | | 15 | [15-配置级联机制](docs/15-配置级联机制.md) | Viper 三层：YAML → ENV → Default | ## 路线图 - [x] 多智能体生成管线（Eino Graph） - [x] 有界并发协程池 + per-user 限流 - [x] 可插拔任务队列（Memory / RabbitMQ） - [x] SSE 实时进度推送 - [x] 工程风格系统 + 标签驱动提示词 - [x] 精灵图处理 + GIF 预览 - [x] Prometheus + Grafana 可观测性 - [x] Redis 令牌桶限流 - [x] 三级降级策略 - [ ] 文生图多模型适配（DALL-E, Midjourney） - [ ] 素材版本管理与历史记录 ## 参与贡献 1. Fork 本仓库 2. 新建 `Feat_xxx` 分支 3. 提交代码 4. 新建 Pull Request ## License [MIT](LICENSE)