vault backup: 2026-06-03 10:30:42

2026-06-03 10:30:42 +08:00
parent 2e207dc8fb
commit b5d9e44f0b
16 changed files with 661 additions and 507 deletions
@@ -1,62 +1,89 @@
+---
+tags: [index, architecture, gen2d, overview]
+create time: 2026-06-03 09:00
+---
+
 # Gen2D 架构讲解 — 答辩文档索引

 > AI 驱动的 2D 游戏素材生成工具

-## 文档导航
+## 概述
+
+本文档是 Gen2D 系统架构讲解的导航索引，覆盖从整体分层架构到具体技术组件的 15 个核心知识点。通过本文档可以快速定位到任意模块的详细解读。
+
+## 正文
+
+### 文档导航

 | # | 文件 | 主题 | 核心要点 |
 |---|------|------|----------|
-| 1 | [01-system-overview](01-system-overview.md) | 系统总览 | Gin → Handler → Service → 基础设施 → 外部依赖 |
-| 2 | [02-worker-pool](02-worker-pool.md) | 协程池 | 有界并发、per-user 限流、背压、优雅关闭 |
-| 3 | [03-task-queue](03-task-queue.md) | 任务队列 | 可插拔接口 + Memory / RabbitMQ 双实现 |
-| 4 | [04-rabbitmq](04-rabbitmq.md) | RabbitMQ 集成 | AMQP 连接、持久化消息、重试/死信流程 |
-| 5 | [05-generation-pipeline](05-generation-pipeline.md) | 生成管线 | Eino 4 阶段图 + 质量回退 + 降级路径 |
-| 6 | [06-sprite-processing](06-sprite-processing.md) | 精灵图处理 | 背景移除 → 投影切割 → 后处理 → GIF 预览 |
-| 7 | [07-observability](07-observability.md) | 可观测性 | 35 Prometheus 指标 + 3 Grafana 仪表盘 + 10 告警 |
-| 8 | [08-sse-push](08-sse-push.md) | SSE 实时推送 | EventBus → SSEHandler → 浏览器 EventSource |
-| 9 | [09-rate-limiting](09-rate-limiting.md) | 限流 | Redis Lua 令牌桶 + 双层限流 + Fail-Open |
-| 10 | [10-middleware-chain](10-middleware-chain.md) | 中间件链 | Logger → Recovery → Metrics → Auth → RateLimit |
-| 11 | [11-consumer-producer](11-consumer-producer.md) | Consumer-Producer 桥接 | TaskQueue → Consumer → WorkerPool 解耦 |
-| 12 | [12-three-tier-fallback](12-three-tier-fallback.md) | 三级降级策略 | Queue → Pool → Legacy 降级链 |
-| 13 | [13-prompt-engineering](13-prompt-engineering.md) | 标签驱动提示词 | 40+ 标签映射 + 风格一致性 |
-| 14 | [14-deployment](14-deployment.md) | 部署架构 | Docker Compose + Prometheus + Grafana |
-| 15 | [15-config-cascade](15-config-cascade.md) | 配置级联 | Viper 三层配置：YAML → ENV → Default |
+| 1 | [[01-系统总览]] | 系统总览 | Gin → Handler → Service → 基础设施 → 外部依赖 |
+| 2 | [[02-协程池]] | 协程池 | 有界并发、per-user 限流、背压、优雅关闭 |
+| 3 | [[03-任务队列]] | 任务队列 | 可插拔接口 + Memory / RabbitMQ 双实现 |
+| 4 | [[04-RabbitMQ集成]] | RabbitMQ 集成 | AMQP 连接、持久化消息、重试/死信流程 |
+| 5 | [[05-生成管线]] | 生成管线 | Eino 4 阶段图 + 质量回退 + 降级路径 |
+| 6 | [[06-精灵图处理]] | 精灵图处理 | 背景移除 → 投影切割 → 后处理 → GIF 预览 |
+| 7 | [[07-可观测性]] | 可观测性 | 35 Prometheus 指标 + 3 Grafana 仪表盘 + 10 告警 |
+| 8 | [[08-SSE实时推送]] | SSE 实时推送 | EventBus → SSEHandler → 浏览器 EventSource |
+| 9 | [[09-限流]] | 限流 | Redis Lua 令牌桶 + 双层限流 + Fail-Open |
+| 10 | [[10-中间件链]] | 中间件链 | Logger → Recovery → Metrics → Auth → RateLimit |
+| 11 | [[11-Consumer-Producer桥接]] | Consumer-Producer 桥接 | TaskQueue → Consumer → WorkerPool 解耦 |
+| 12 | [[12-三级降级策略]] | 三级降级策略 | Queue → Pool → Legacy 降级链 |
+| 13 | [[13-标签驱动提示词工程]] | 标签驱动提示词 | 40+ 标签映射 + 风格一致性 |
+| 14 | [[14-部署架构]] | 部署架构 | Docker Compose + Prometheus + Grafana |
+| 15 | [[15-配置级联机制]] | 配置级联 | Viper 三层配置：YAML → ENV → Default |

-## 架构总览图
+> [!tip] 阅读顺序建议
+>
+> 建议按编号顺序阅读：先理解 [[01-系统总览]] 的全局架构，再深入各个具体组件（协程池、任务队列、RabbitMQ），最后学习运行时相关话题（SSE 推送、可观测性、降级策略）。

-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        浏览器 (React)                           │
-│  EventSource ← SSE ← EventBus ← Pipeline Progress              │
-└────────────────────────────┬────────────────────────────────────┘
-                             │ HTTP
-┌────────────────────────────▼────────────────────────────────────┐
-│                     Gin HTTP Server                              │
-│  Logger → Recovery → Metrics → Auth → RateLimit → Handler       │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-┌────────────────────────────▼────────────────────────────────────┐
-│                      Handler 层                                  │
-│  GenerateHandler / SSEHandler / PromptHandler                    │
-└──────┬─────────────────────┬─────────────────────┬──────────────┘
-       │                     │                     │
-┌──────▼──────┐    ┌─────────▼─────────┐    ┌─────▼──────┐
-│ TaskQueue   │    │   WorkerPool      │    │  EventBus  │
-│ Memory/RMQ  │───→│  NumCPU*4 并发    │    │  Pub/Sub   │
-└─────────────┘    │  Per-user 限流    │    └────────────┘
-                   └─────────┬─────────┘
-                             │
-                   ┌─────────▼─────────┐
-                   │  Eino Pipeline    │
-                   │  4 阶段生成管线    │
-                   └─────────┬─────────┘
-                             │
-              ┌──────────────┼──────────────┐
-              ▼              ▼              ▼
-        Image API      Quality Check    SplitSprite
-        (DALL-E 3)     (GPT-4o)        + GIF Maker
+### 架构总览图
+
+```mermaid
+graph TB
+    subgraph Browser["浏览器 (React)"]
+        UI["三栏工作台"]
+        SE["EventSource ← SSE"]
+    end
+
+    subgraph Gateway["Gin HTTP Server"]
+        MW["中间件链<br/>Logger / Recovery / Metrics / Auth / RateLimit"]
+    end
+
+    subgraph Handler["Handler 层"]
+        GH["GenerateHandler"]
+        SH["SSEHandler"]
+        PH["PromptHandler"]
+    end
+
+    subgraph Infra["基础设施层"]
+        TQ["TaskQueue<br/>Memory / RabbitMQ"]
+        WP["WorkerPool<br/>NumCPU*4 并发<br/>Per-user 限流"]
+        EB["EventBus<br/>Pub/Sub"]
+    end
+
+    subgraph Pipeline["Service 层"]
+        EP["Eino Pipeline<br/>4 阶段生成管线"]
+    end
+
+    subgraph External["外部依赖"]
+        IMG["Image API<br/>DALL-E 3"]
+        QC["Quality Check<br/>GPT-4o"]
+        SP["SplitSprite + GIF Maker"]
+    end
+
+    UI -->|"HTTP"| GW
+    SE --> UI
+    GW --> MW
+    MW --> Handler
+    GH --> TQ
+    GH --> WP
+    SH --> EB
+    TQ --> WP
+    WP --> EP
+    EP --> IMG & QC & SP
 ```

-## 配套图表
+### 配套图表

 每份文档开头使用 Mermaid 流程图，可直接在 Markdown 渲染器中查看。