Kratos透传灰度标识需手动实现全链路:HTTP头(如X-Gray-Version)须由网关/中间件解析并写入metadata.MD,再通过client.WithMiddleware在UnaryClientInterceptor中注入;gRPC端需对称实现UnaryServerInterceptor解析;MQ和定时任务等异步场景必须将灰度标显式序列化至payload,不可依赖context.WithValue。

Kratos 框架如何透传灰度标识(trace 与 metadata)
Kratos 默认使用 grpc-go,不自动透传 HTTP Header 或自定义上下文字段到下游 RPC。若只在网关层做分流,下游服务根本收不到灰度标,整个链路就断了。
必须手动把灰度标识从入参带到出参。常见做法是:在 Gateway 或中间件中解析 X-Gray-Version 或 Cookie,写入 context.Context 的 metadata.MD,再通过 Kratos 的 client.WithMiddleware 注入拦截器,在每次 UnaryClientInterceptor 中将该 metadata 加入 outbound 请求头。
- 不要依赖
context.WithValue存灰度信息——gRPC 调用时不会自动带过去 - 务必检查下游服务是否也做了对称的
UnaryServerInterceptor解析metadata并还原到 context - Kratos 的
transport.HTTP和transport.GRPC是分离的,HTTP 入口的灰度标需显式转成 gRPC metadata,不能指望框架自动桥接
服务发现与负载均衡怎么支持灰度节点分组(etcd + registry)
Kratos 使用 registry 接口对接注册中心(如 etcd),默认注册信息里只有服务名、地址、权重等基础字段,没有“灰度分组”维度。如果下游不做区分,discovery.LoadBalance 就会随机选节点,灰度流量大概率打到稳定节点上。
解决方案是在注册时主动注入标签。例如:
reg := etcd.New(&etcd.Config{
Addrs: []string{"127.0.0.1:2379"},
})
// 注册时带上 gray: true 标签
ins := ®istry.ServiceInstance{
ID: "user-service-v2-gray-01",
Name: "user.service",
Version: "v2",
Metadata: map[string]string{"gray": "true", "region": "sh"},
Endpoints: []string{"10.0.1.10:9000"},
}
reg.Register(context.Background(), ins)
- 客户端调用前,先用
registry.GetServices拿全量实例,再按Metadata["gray"] == "true"过滤 - 自定义
discovery.LoadBalance实现(比如继承roundrobin.Balancer),在Select前先筛灰度节点;若无可用灰度节点,再 fallback 到全量池 - 注意 etcd key path 的 TTL 和心跳续期逻辑,灰度节点下线后标签残留会导致路由错误
如何让 Kratos 的 http.Server 和 grpc.Server 同时识别灰度请求
一个 Kratos 服务常同时暴露 HTTP 和 gRPC 接口。但两者中间件体系独立:HTTP 走 http.Middleware,gRPC 走 grpc.ServerOption。若只在 HTTP 层加灰度拦截器,gRPC 入口就漏掉了;反之亦然。
关键点是统一上下文构造入口。建议在最外层封装一个 newContextWithGray 工具函数,被两类 server 的拦截器共用:
// HTTP 中间件
func GrayMiddleware() http.Middleware {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ctx := newContextWithGray(r.Context(), r.Header.Get("X-Gray-Version"))
r = r.WithContext(ctx)
next.ServeHTTP(w, r)
})
}
}
<p>// gRPC 拦截器
func GrayServerInterceptor() grpc.UnaryServerInterceptor {
return func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
md, _ := metadata.FromIncomingContext(ctx)
version := md.Get("x-gray-version")
ctx = newContextWithGray(ctx, version[0])
return handler(ctx, req)
}
}
-
newContextWithGray应把灰度信息存进context.WithValue,并确保下游所有业务 handler 都能拿到(不是仅限于中间件内) - HTTP header 名和 gRPC metadata key 必须约定一致,比如都用
x-gray-version,大小写敏感 - 避免在 handler 里重复解析——中间件做完就该把结构化灰度信息(如
GrayRule{Version: "v2", UserIDs: []int64{1001}})塞进 context
为什么 Kratos 项目容易在 MQ 和定时任务环节丢灰度标
Kratos 自身不内置消息队列或调度框架,但实际项目常集成 go-redis、asynq 或 robfig/cron。这些组件完全脱离 Kratos 的 context 生命周期,一旦在异步场景中使用 context.WithValue 存的灰度信息,就会丢失。
真正可行的做法是:把灰度标识作为业务 payload 的一部分显式携带。
- 发 MQ 消息前,把当前 context 中的灰度版本、用户 ID 等字段序列化进 message body 或
Headers字段(如asynq.Task.Queue不支持 headers,就得塞进payload) - 消费端收到后,先反序列化灰度字段,再手动构造带灰度信息的新 context,而不是试图从父 context 继承
- 定时任务无法依赖请求上下文,只能靠配置驱动:比如用
conf.yaml显式声明gray_schedule: true,或在 cron 表达式里嵌入环境标识(*/5 * * * * ? gray-v2) - 特别注意:Kratos 的
log.Logger默认不打印灰度字段,需在logger.With()中显式追加,否则排查时看不到灰度链路
全链路灰度不是加几个中间件就能跑通的事。Kratos 的轻量设计意味着更多控制权交给了开发者,也意味着每个异步出口、每个跨进程调用点,都得人工补上灰度标透传逻辑——漏掉任意一环,灰度就只剩“入口那一跳”。


















