## Why 当前 `cmd/worker` 同时承担 Asynq 任务消费、轮询初始化、轮询调度、套餐激活/流量重置扫描和 Asynq 定时任务调度职责,导致完整 worker 进程不能安全横向复制。为了支持后续多实例扩容,同时避免重复扫库、重复调度和重复入队,本变更先引入显式 Worker 角色,将“可多开的消费职责”和“必须单例的主动调度职责”拆开。 ## What Changes - 新增 Worker 运行角色配置: - `all`:兼容当前单实例行为,启动全部模块 - `leader`:明确承担单例职责,启动全部模块 - `consumer`:只启动 Asynq Worker Server 和任务处理依赖,不启动任何主动调度/初始化模块 - 新增实例名称配置 `JUNHONG_WORKER_INSTANCE_NAME`,用于日志区分多实例。 - 修改 `cmd/worker/main.go` 启动流程,将共享依赖初始化和按角色启停模块分离。 - `consumer` 仍注册全部任务 Handler,确保可以消费轮询任务、套餐激活任务、订单超时任务、告警任务、数据清理任务等已有 Asynq 任务。 - 启动日志明确打印当前角色、实例名、启用模块和禁用模块,便于部署验证和排障。 - 保持默认 `all`,不修改现有部署配置时行为完全不变。 - 不引入自动选主、Redis Leader 锁或任务唯一性去重;这些作为第二期增强,不纳入本次最小改造。 ## Capabilities ### New Capabilities - `worker-role-management`:定义 Worker 运行角色、按角色启停模块、兼容模式、消费者扩容语义和启动日志要求。 ### Modified Capabilities - `embedded-config`:新增 `worker.role`、`worker.instance_name` 默认配置和环境变量覆盖要求。 ## Impact **功能 ID**:`feature-worker-role-split` **涉及文件**: - `cmd/worker/main.go`:按角色控制 `PollingInitializer`、`PollingScheduler`、`Asynq Scheduler` 启停 - `pkg/config/config.go`:新增 Worker 配置结构和角色校验 - `pkg/config/defaults/config.yaml`:新增默认 worker 配置节 - `pkg/config/loader.go`:绑定 `worker.role`、`worker.instance_name` - `docs/environment-variables.md`:补充 Worker 角色环境变量和部署说明 **技术栈合规性**: - 配置继续使用 Viper 加载和环境变量覆盖 - 日志继续使用 Zap 输出中文日志 - 异步任务继续使用 Asynq,不新增队列依赖 - 不涉及 Fiber Handler、GORM Store、数据库迁移或 DTO 变更 **架构分层**: - 本变更属于进程编排和配置层改造,不新增业务 Handler/Service/Store/Model - 已有任务处理链路保持不变,仍由 Asynq Worker Server 分发到 `pkg/queue` 注册的 Handler **验证计划**: - 按项目根规范,本变更不新增自动化测试或 `*_test.go` 文件 - 使用 `go build ./cmd/worker` 验证 worker 入口编译通过 - 使用 `go build ./...` 验证项目整体编译通过 - 人工以 `all`、`leader`、`consumer` 三种配置启动/观察日志,确认模块启停符合角色语义 - 人工检查 `consumer` 日志不出现“轮询调度器已启动”和“Asynq Scheduler 已启动” **性能影响**: - 单实例默认 `all` 行为不变,无额外运行时开销 - `consumer` 不运行初始化器和调度器,可降低多实例场景下重复 DB/Redis 压力 - 多实例阶段应优先扩展 `consumer`,不要复制 `leader` **兼容性与回滚**: - 默认值为 `all`,旧部署无需新增环境变量即可保持当前行为 - 如上线后有问题,可停止所有 `consumer`,保留单个 `leader`;必要时将唯一实例切回 `all`