huang
3a2e3f2571
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m8s
3.5 KiB
3.5 KiB
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_namedocs/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