vault backup: 2026-06-03 10:22:41

2026-06-03 10:22:41 +08:00
parent 6f8363fd3c
commit 2e207dc8fb
16 changed files with 0 additions and 0 deletions
@@ -0,0 +1,247 @@
+# 03 - 任务队列 (Task Queue)
+
+> **一句话概括**：可插拔任务队列接口，支持 Memory 和 RabbitMQ 双实现，通过工厂模式一行切换。
+
+## 架构设计
+
+```mermaid
+graph TB
+    subgraph Producer["生产者"]
+        HANDLER["Handler.Generate()"]
+    end
+
+    subgraph Interface["TaskQueue 接口"]
+        SUBMIT["Submit(ctx, msg)"]
+        CONSUME["Consume(ctx, handler)"]
+        CLOSE["Close()"]
+    end
+
+    subgraph Memory["MemoryQueue"]
+        MEM_CH["chan TaskMessage<br/>buffered"]
+        MEM_SUBMIT["阻塞写入"]
+        MEM_CONSUME["持续消费"]
+    end
+
+    subgraph RabbitMQ["RabbitMQQueue"]
+        RMQ_PUB["channel.Publish<br/>Persistent"]
+        RMQ_CONSUME["channel.Consume<br/>Manual ACK"]
+    end
+
+    HANDLER --> SUBMIT
+    SUBMIT --> Memory
+    SUBMIT --> RabbitMQ
+    CONSUME --> Memory
+    CONSUME --> RabbitMQ
+    Memory --- MEM_CH
+    RabbitMQ --- RMQ_PUB
+```
+
+## TaskQueue 接口
+
+```go
+type TaskQueue interface {
+    Submit(ctx context.Context, msg TaskMessage) error
+    Consume(ctx context.Context, handler func(TaskMessage) error) error
+    Close() error
+}
+```
+
+| 方法 | 语义 | 错误处理 |
+|------|------|----------|
+| `Submit` | 提交任务到队列 | 内存队列 buffer 满时阻塞；RabbitMQ 发送失败时返回错误 |
+| `Consume` | 持续消费任务，直到 ctx 取消 | handler 返回错误时，内存队列丢弃，RabbitMQ NACK 重试 |
+| `Close` | 关闭连接，释放资源 | 返回 `errors.Join` 聚合错误 |
+
+## 工厂模式
+
+通过配置驱动，一行切换队列实现：
+
+```go
+tq, err := taskqueue.New(cfg.TaskQueue)
+```
+
+```go
+func New(cfg config.TaskQueueConfig) (TaskQueue, error) {
+    switch cfg.Driver {
+    case "rabbitmq":
+        return NewRabbitMQQueue(cfg.RabbitMQ)
+    default:
+        return NewMemoryQueue(cfg.Memory.BufferSize), nil
+    }
+}
+```
+
+| `cfg.Driver` | 实现 | 适用场景 |
+|--------------|------|----------|
+| `"memory"` (默认) | `MemoryQueue` | 单机开发、演示环境 |
+| `"rabbitmq"` | `RabbitMQQueue` | 多机生产部署 |
+
+## TaskMessage 消息结构
+
+```go
+type TaskMessage struct {
+    TaskID     string                `json:"task_id"`
+    UserID     string                `json:"user_id"`
+    ProjectID  string                `json:"project_id"`
+    Input      service.PipelineInput `json:"input"`
+    CreatedAt  time.Time             `json:"created_at"`
+    RetryCount int                   `json:"retry_count"`
+}
+```
+
+**关键设计**：
+
+- `Input` 直接嵌入 `PipelineInput`，Consumer 反序列化后即可传入管线
+- `RetryCount` 供 RabbitMQ 实现判断是否超过最大重试次数
+- JSON 序列化，兼容内存队列和 RabbitMQ 两种传输
+
+## MemoryQueue 实现
+
+基于 Go channel 的内存队列，零外部依赖。
+
+**核心逻辑**：
+
+```go
+type MemoryQueue struct {
+    ch      chan TaskMessage  // 有界缓冲
+    closed  atomic.Bool
+    closeCh chan struct{}
+}
+```
+
+### Submit
+
+```go
+func (q *MemoryQueue) Submit(ctx context.Context, msg TaskMessage) error {
+    select {
+    case q.ch <- msg:          // 成功入队
+        return nil
+    case <-ctx.Done():         // 上下文取消
+        return ctx.Err()
+    case <-q.closeCh:          // 队列已关闭
+        return ErrQueueClosed
+    }
+}
+```
+
+> :bulb: **阻塞语义**：MemoryQueue 的 Submit 是阻塞的——当 buffer 满时，调用方会阻塞直到有空位或 ctx 取消。这与 WorkerPool 的非阻塞拒绝形成对比。
+
+### Consume
+
+```go
+func (q *MemoryQueue) Consume(ctx context.Context, handler func(TaskMessage) error) error {
+    for {
+        select {
+        case msg := <-q.ch:         // 取出消息
+            if err := handler(msg); err != nil {
+                // handler 失败，记录日志并丢弃（不重试）
+                slog.Error("handler failed, dropping message", ...)
+            }
+        case <-ctx.Done():          // 上下文取消
+            return ctx.Err()
+        case <-q.closeCh:           // 队列已关闭
+            return ErrQueueClosed
+        }
+    }
+}
+```
+
+**MemoryQueue 特性**：
+
+| 特性 | 行为 |
+|------|------|
+| 持久化 | 无（进程重启后任务丢失） |
+| 重试 | 无（handler 错误直接丢弃） |
+| 背压 | 阻塞直到有空位 |
+| 依赖 | 零外部依赖 |
+
+> :warning: **可接受的任务丢失**：AI 生成任务可以重新提交，进程重启丢失排队中的任务是可接受的权衡。
+
+## RabbitMQQueue 实现
+
+基于 AMQP 的持久化消息队列，支持手动 ACK 和重试。详见 [04-rabbitmq](04-rabbitmq.md)。
+
+**RabbitMQQueue 特性**：
+
+| 特性 | 行为 |
+|------|------|
+| 持久化 | 消息 `DeliveryMode=Persistent`，队列 `durable=true` |
+| 重试 | 失败 + retry < max → NACK+requeue；超过 → ACK 丢弃 |
+| 背压 | 发布失败时返回错误（不阻塞） |
+| 依赖 | 需要 RabbitMQ 服务 |
+
+## 双实现对比
+
+| 维度 | MemoryQueue | RabbitMQQueue |
+|------|-------------|---------------|
+| **依赖** | 无 | RabbitMQ 服务 |
+| **持久化** | 无 | 有（磁盘持久化） |
+| **重试** | 无 | NACK + requeue |
+| **背压** | 阻塞等待 | 返回错误 |
+| **部署** | 单机 | 多机 |
+| **适用** | 开发/演示 | 生产环境 |
+| **消息丢失** | 进程重启丢失 | 服务重启不丢失 |
+
+## Consumer 桥接
+
+Consumer 从 TaskQueue 消费消息，提交到 WorkerPool 执行，实现队列与并发控制的解耦：
+
+```go
+func (c *Consumer) Start(ctx context.Context) error {
+    return c.queue.Consume(ctx, func(msg TaskMessage) error {
+        return c.pool.Submit(workerpool.Task{
+            ID:     msg.TaskID,
+            UserID: msg.UserID,
+            Fn: func(taskCtx context.Context) error {
+                c.handler(taskCtx, msg)  // 执行 Pipeline
+                return nil
+            },
+        })
+    })
+}
+```
+
+```
+TaskQueue → Consumer → WorkerPool → Pipeline
+   全局排队      桥接       单机并发     业务逻辑
+```
+
+## 三级降级策略
+
+Gen2D 在 `cmd/main.go` 中实现了三级降级链：
+
+| 优先级 | 组件 | 条件 | 行为 |
+|--------|------|------|------|
+| 1 | TaskQueue + Consumer | 初始化成功 | 队列排队 → Consumer 消费 → WorkerPool 执行 |
+| 2 | WorkerPool（直接） | TaskQueue 初始化失败 | 直接提交到协程池 |
+| 3 | Legacy FIFO Queue | 均不可用 | 串行队列兜底 |
+
+```go
+if taskQueue != nil {
+    // 优先：通过队列提交
+    taskQueue.Submit(ctx, msg)
+} else if workerPool != nil {
+    // 回退：直接提交到协程池
+    workerPool.Submit(task)
+} else {
+    // 兜底：旧串行队列
+    generateQueue.Enqueue(job)
+}
+```
+
+## Metrics 指标
+
+| Prometheus 指标 | 类型 | Label | 说明 |
+|-----------------|------|-------|------|
+| `gen2d_queue_depth` | Gauge | `driver` | 当前队列积压深度 |
+| `gen2d_queue_submitted_total` | Counter | `driver` | 入队总量 |
+| `gen2d_queue_consumed_total` | Counter | `driver` | 出队总量 |
+| `gen2d_queue_submit_duration_seconds` | Histogram | `driver` | 入队耗时 |
+| `gen2d_queue_errors_total` | Counter | `driver`, `error_type` | 队列错误总量 |
+
+## 关联文档
+
+- [索引](00-index.md) — 文档导航与架构总览图
+- [系统总览](01-system-overview.md) — 分层架构与依赖注入
+- [协程池](02-worker-pool.md) — 有界并发与 per-user 限流
+- [RabbitMQ 集成](04-rabbitmq.md) — 持久化消息与重试机制