Kratos 没有原生 Worker 模式,因其设计聚焦「请求-响应」型服务,将任务调度视为 infra 层职责;推荐用 Asynq 构建独立 Worker 进程,与 server 隔离部署但共享日志、指标和链路追踪。

Kratos 本身不提供内置的离线任务或 Worker 服务模型,必须手动集成外部任务队列(如 Asynq、Machinery、Redis-backed job queue)并以独立进程方式运行。
为什么 Kratos 没有原生 Worker 模式
Kratos 的设计聚焦于「请求-响应」型服务:HTTP/gRPC Server 是核心抽象,所有 kratos.Server 实现都围绕监听端口、处理入站连接展开。它没有 Worker、JobRunner 或后台 goroutine 生命周期管理机制——这不是遗漏,而是刻意取舍。官方认为任务调度属于 infra 层职责,应由专用组件承担,而非混入服务主进程。
常见误判是把 data 层的异步写操作(比如发 MQ 消息)当成“离线任务”,其实那只是同步逻辑里的副作用;真正的离线任务指:定时执行、失败重试、延迟触发、结果回调、可观测性追踪等完整生命周期管理能力。
推荐方案:用 Asynq 搭建独立 Worker 进程
Asynq 是 Go 生态最成熟的 Redis-backed 任务队列库,轻量、稳定、自带 Web UI 和 CLI 工具,与 Kratos 项目结构天然兼容。关键不是“在 Kratos 里塞 Worker”,而是让 Worker 成为同一 repo 下的另一个可执行命令。
- 在
cmd/目录下新建worker/main.go,不复用cmd/server的kratos.App启动流程 - Worker 进程只初始化 Redis 客户端、Asynq Client/Server、业务 handler,不启动任何 HTTP/gRPC Server
- 使用
go run cmd/worker或kratos build -o worker cmd/worker单独构建和运行 - 通过
Asynq.ServeMux注册 handler,每个 handler 对应一个task.Type,例如"send_email"或"generate_report" - 在 Kratos 的 HTTP/gRPC handler 中,用
client.Enqueue投递任务,而非直接执行耗时逻辑
示例投递代码:
import "github.com/hibiken/asynq"
func (s *GreeterService) SendReport(ctx context.Context, req *v1.SendReportRequest) (*v1.SendReportResponse, error) {
task := asynq.NewTask("generate_report", map[string]interface{}{"user_id": req.UserId})
_, err := s.taskClient.Enqueue(task, asynq.ProcessIn(5*time.Minute))
return &v1.SendReportResponse{}, err
}
配置与依赖隔离要点
Kratos 的 config 组件默认只被 cmd/server 使用,Worker 进程需自行加载配置,但可以复用同一套 config 结构体和 Source。
- 避免在 Worker 中重复定义
conf.proto,直接 importyour-project/internal/conf - Worker 的
main.go应调用config.New+config.WithSource加载配置,路径可设为configs/worker.yaml与 server 配置分离 - 若共用 Redis,确保 Asynq 的
redis.Options与 Kratos 中 DB/Cache 客户端的连接参数不冲突(尤其PoolSize) - 不要把 Asynq Server 启动逻辑塞进
kratos.Server接口——它不满足Start() error和Stop() error的语义约束,强行适配会导致信号处理异常
部署与可观测性对齐
Worker 进程虽独立,但日志、指标、链路需与 Kratos 主服务一致,否则排查问题时会断层。
- 日志统一用
github.com/go-kratos/kratos/v2/log,初始化时传入相同log.Logger实例(可通过 config 注入) - Asynq 内置 Prometheus metrics,需手动注册到全局
prometheus.DefaultRegisterer,与 Kratos 的metrics.Server共享同一个 registry - 链路追踪需在 Asynq handler 中显式提取 context 中的 traceID(从任务 payload 或 header 注入),再用
tracing.StartSpanFromContext延续链路 - Docker 部署时,Worker 应为单独 container,与 server container 平级,通过 compose network 通信
真正容易被忽略的是信号处理:Kratos 的 app.Run() 自动注册 SIGINT/SIGTERM 并优雅关闭所有 Server,而 Asynq Server 默认不响应这些信号。必须在 Worker 的 main() 中手动监听并调用 srv.Shutdown(),否则 kill -15 会导致任务中断丢失。











