wangdl/api-server
2
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

M0-10 Task Queue & Worker 基础版 #10

New Issue
Open
opened 2026-05-22 21:00:16 +08:00 by wangdl · 0 comments
wangdl commented 2026-05-22 21:00:16 +08:00
Owner
Copy Link

目标

设计知习后端任务队列与 Worker 模块，为全系统提供统一的异步任务调度能力，封装 BullMQ 的队列注册、任务领取、心跳检测、重试和取消机制。

本 Issue 只做架构设计，不直接实现代码。

背景说明

知习后端有大量耗时操作不能阻塞 HTTP 请求：文档导入和解析、embedding 生成、AI 分析、复习卡片生成、备份任务等。这些操作需要通过任务队列异步执行。

Task Queue 模块提供统一的任务调度框架，所有异步任务（无论属于哪个业务模块）都通过 BullMQ 队列管理，Worker 进程领取任务并执行，支持心跳检测防止任务丢失，支持重试和取消。

模块职责

  1. 本模块负责：

    • BullMQ 队列注册和管理
    • 统一任务类型枚举定义（所有任务类型在此注册）
    • 任务入队接口
    • Worker 进程管理（领取、执行、心跳）
    • 任务重试策略（最大重试次数、退避策略）
    • 任务取消机制
    • 任务状态追踪（等待/执行中/完成/失败/取消）
    • Worker 节点状态监控

  2. 本模块不负责：

    • 具体业务任务的处理逻辑（由各业务模块的 Processor 实现）
    • 任务结果的业务处理（由业务模块通过 Event 订阅处理）
    • 备份策略和清理策略（走 Backup & Cleanup）

任务类型枚举

请设计统一的任务类型注册表，所有模块的异步任务在此声明：

  • DOCUMENT_IMPORT：文档导入
  • OCR_PROCESS：OCR 处理
  • VISION_ANALYZE：Vision 分析
  • EMBEDDING_GENERATE：Embedding 生成
  • INDEXING_UPSERT：Qdrant 索引更新
  • GENERATE_ARTIFACT：学习工件生成
  • AI_ANALYSIS：AI 诊断分析
  • GENERATE_REVIEW_CARD：复习卡片生成
  • BACKUP_EXECUTE：备份执行
  • CLEANUP_EXECUTE：清理执行
  • AGENT_TASK：Hermes Agent 任务
  • REPORT_GENERATE：报表生成

基础设施依赖判断

  • MySQL：需判断（任务日志持久化 vs 依赖 BullMQ 自身持久化）
  • Redis：是（BullMQ 核心依赖）
  • BullMQ：是（核心依赖）
  • Qdrant：否
  • AI Gateway：否
  • COS：否

接口设计

  1. Internal Provider（供各模块代码调用）：

    • TaskQueueService.enqueue(type, payload, options)：任务入队
    • TaskQueueService.cancel(jobId)：取消任务
    • TaskQueueService.getStatus(jobId)：查询任务状态

  2. AAPI：

    • 任务队列总览（各队列积压数量、Worker 数量）
    • 任务列表（按类型/状态/时间筛选）
    • 任务详情（执行日志、重试次数）
    • 失败任务手动重试
    • Worker 节点状态

Domain Event 设计

  • TaskEnqueued：任务入队
  • TaskStarted：任务开始执行
  • TaskCompleted：任务完成
  • TaskFailed：任务失败
  • TaskCancelled：任务取消
  • TaskRetried：任务重试

Admin 视图设计

  1. 任务队列总览：各队列等待/执行中/完成/失败数量、Worker 节点健康状态
  2. 任务列表：最近任务（类型、参数摘要、状态、创建时间、耗时）、失败任务高亮、手动重试按钮
  3. 任务详情：执行日志、重试历史、错误信息

交付检查

  • 路由归属：Internal Provider + AAPI
  • 是否需要 Prisma migration：需判断（任务日志表）
  • 是否需要 MySQL：需判断
  • 是否需要 Redis：是
  • 是否需要 BullMQ：是
  • 是否需要 Qdrant：否
  • 是否需要 AI Gateway：否
  • 是否需要 Content Safety：否
  • 是否需要 Cost 记录：否（Cost 由各业务模块上报）
  • 是否需要 AuditLog：否（任务失败不需审计，但手动重试需审计）
  • 是否需要 Domain Event：是
  • 是否需要 Admin 视图：是
  • 是否需要 E2E/集成测试：是

验收标准

  1. BullMQ 队列注册方案
  2. 统一任务类型枚举定义
  3. TaskQueueService 接口设计
  4. Worker 心跳和故障检测方案
  5. 任务重试策略设计
  6. Admin 任务管理视图设计
  7. 集成测试覆盖任务入队/执行/重试/失败流程

禁止事项

  • 禁止各模块自行创建 BullMQ 队列（必须通过 Task Queue 模块注册）
  • 禁止 Worker 执行超过 30 分钟无心跳的任务
  • 禁止任务重试无限循环（必须设最大重试次数）
  • 禁止任务 payload 包含大文件内容（应传递文件 ID/路径）
  • 禁止在 Worker 中直接操作 HTTP Response（Worker 无请求上下文）

不建议当前阶段实现

  • 任务优先级调度
  • 任务依赖编排（任务 A 完成后再执行任务 B）
  • Worker 自动扩容
  • 任务执行时间预测和 SLA 监控
## 目标 设计知习后端任务队列与 Worker 模块，为全系统提供统一的异步任务调度能力，封装 BullMQ 的队列注册、任务领取、心跳检测、重试和取消机制。 本 Issue 只做架构设计，不直接实现代码。 ## 背景说明 知习后端有大量耗时操作不能阻塞 HTTP 请求：文档导入和解析、embedding 生成、AI 分析、复习卡片生成、备份任务等。这些操作需要通过任务队列异步执行。 Task Queue 模块提供统一的任务调度框架，所有异步任务（无论属于哪个业务模块）都通过 BullMQ 队列管理，Worker 进程领取任务并执行，支持心跳检测防止任务丢失，支持重试和取消。 ## 模块职责 1. 本模块负责： - BullMQ 队列注册和管理 - 统一任务类型枚举定义（所有任务类型在此注册） - 任务入队接口 - Worker 进程管理（领取、执行、心跳） - 任务重试策略（最大重试次数、退避策略） - 任务取消机制 - 任务状态追踪（等待/执行中/完成/失败/取消） - Worker 节点状态监控 2. 本模块不负责： - 具体业务任务的处理逻辑（由各业务模块的 Processor 实现） - 任务结果的业务处理（由业务模块通过 Event 订阅处理） - 备份策略和清理策略（走 Backup & Cleanup） ## 任务类型枚举 请设计统一的任务类型注册表，所有模块的异步任务在此声明： - DOCUMENT_IMPORT：文档导入 - OCR_PROCESS：OCR 处理 - VISION_ANALYZE：Vision 分析 - EMBEDDING_GENERATE：Embedding 生成 - INDEXING_UPSERT：Qdrant 索引更新 - GENERATE_ARTIFACT：学习工件生成 - AI_ANALYSIS：AI 诊断分析 - GENERATE_REVIEW_CARD：复习卡片生成 - BACKUP_EXECUTE：备份执行 - CLEANUP_EXECUTE：清理执行 - AGENT_TASK：Hermes Agent 任务 - REPORT_GENERATE：报表生成 ## 基础设施依赖判断 - MySQL：需判断（任务日志持久化 vs 依赖 BullMQ 自身持久化） - Redis：是（BullMQ 核心依赖） - BullMQ：是（核心依赖） - Qdrant：否 - AI Gateway：否 - COS：否 ## 接口设计 1. Internal Provider（供各模块代码调用）： - TaskQueueService.enqueue(type, payload, options)：任务入队 - TaskQueueService.cancel(jobId)：取消任务 - TaskQueueService.getStatus(jobId)：查询任务状态 2. AAPI： - 任务队列总览（各队列积压数量、Worker 数量） - 任务列表（按类型/状态/时间筛选） - 任务详情（执行日志、重试次数） - 失败任务手动重试 - Worker 节点状态 ## Domain Event 设计 - TaskEnqueued：任务入队 - TaskStarted：任务开始执行 - TaskCompleted：任务完成 - TaskFailed：任务失败 - TaskCancelled：任务取消 - TaskRetried：任务重试 ## Admin 视图设计 1. 任务队列总览：各队列等待/执行中/完成/失败数量、Worker 节点健康状态 2. 任务列表：最近任务（类型、参数摘要、状态、创建时间、耗时）、失败任务高亮、手动重试按钮 3. 任务详情：执行日志、重试历史、错误信息 ## 交付检查 - [ ] 路由归属：Internal Provider + AAPI - [ ] 是否需要 Prisma migration：需判断（任务日志表） - [ ] 是否需要 MySQL：需判断 - [ ] 是否需要 Redis：是 - [ ] 是否需要 BullMQ：是 - [ ] 是否需要 Qdrant：否 - [ ] 是否需要 AI Gateway：否 - [ ] 是否需要 Content Safety：否 - [ ] 是否需要 Cost 记录：否（Cost 由各业务模块上报） - [ ] 是否需要 AuditLog：否（任务失败不需审计，但手动重试需审计） - [ ] 是否需要 Domain Event：是 - [ ] 是否需要 Admin 视图：是 - [ ] 是否需要 E2E/集成测试：是 ## 验收标准 1. BullMQ 队列注册方案 2. 统一任务类型枚举定义 3. TaskQueueService 接口设计 4. Worker 心跳和故障检测方案 5. 任务重试策略设计 6. Admin 任务管理视图设计 7. 集成测试覆盖任务入队/执行/重试/失败流程 ## 禁止事项 - 禁止各模块自行创建 BullMQ 队列（必须通过 Task Queue 模块注册） - 禁止 Worker 执行超过 30 分钟无心跳的任务 - 禁止任务重试无限循环（必须设最大重试次数） - 禁止任务 payload 包含大文件内容（应传递文件 ID/路径） - 禁止在 Worker 中直接操作 HTTP Response（Worker 无请求上下文） ## 不建议当前阶段实现 - 任务优先级调度 - 任务依赖编排（任务 A 完成后再执行任务 B） - Worker 自动扩容 - 任务执行时间预测和 SLA 监控
wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:16 +08:00
wangdl self-assigned this 2026-05-22 21:00:16 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone M0：后端基础能力与架构规范闭环（P0）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#10
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?