Kratos服务注册必须带version metadata,否则Selector无法过滤;需在Nacos/Consul中显式写入{"version":"v2","env":"canary"},etcd需扩展序列化;客户端须用自定义Selector按metadata过滤,HTTP/gRPC均需手动透传x-version。

Kratos服务注册必须带 version metadata
Kratos 本身不识别“灰度”概念,所有版本区分逻辑都依赖注册中心的实例元数据。如果你没在启动时注入 version 标签,下游 Selector 就无从过滤——哪怕代码里写了 s.Metadata["version"] == "v2",也永远匹配不到。
实操要点:
- 用 Nacos/Consul 注册时,在
metadata字段显式写入:{"version": "v2", "env": "canary"} - 若用 etcd,注意
contrib/registry/etcd默认不透传map[string]string类型的Metadata,需自行扩展序列化逻辑 - 禁止靠服务名区分版本(如把服务起名为
user-service-v2),这会让网关或客户端无法统一做标签路由
客户端调用必须用自定义 Selector 过滤实例
Kratos 的 transport 层(gRPC/HTTP)默认使用全量实例列表,round_robin balancer 完全不感知 metadata。硬编码 if header.Get("x-version") == "v2" { call v2 service } 是反模式,会污染业务、不可动态调整。
正确做法是替换默认 Selector:
- 初始化 client 时传入
transport.WithSelector(micro.Selector(Selector.WithFilter(func(s *registry.Service) bool { return s.Metadata["version"] == "v2" }))) - 若用 Kratos v2 的
client.NewClient,需配合client.WithMiddleware注入 context-aware selector,从ctx.Value("x-version")动态提取目标版本 - 注意:gRPC 的
balancer.Picker阶段才真正决定选哪个实例,必须在这里完成 metadata 过滤,不能只靠 transport 层转发
HTTP 请求头 x-version 必须手动透传
上游加了 req.Header.Set("x-version", "v2"),下游收不到——这不是 bug,是预期行为。Kratos 的 HTTP transport 不自动转发非标准 header,http.Transport 也不会帮你做这件事。
要让灰度链路贯穿,必须显式透传:
- 在网关或入口服务中,用中间件提取 header 并存入 ctx:
ctx = context.WithValue(ctx, "x-version", c.GetHeader("x-version")) - 下游发起新请求前,手动附加:
req.Header.Set("x-version", ctx.Value("x-version").(string)) - 不要依赖
http.RoundTripper的Clone或ProxyConnectHeader,它们不处理自定义 header
gRPC 元数据透传要分清 client-side 和 server-side
gRPC 的 metadata.MD 是单向的:client 发送的元数据只能被 server 读取,server 写回的元数据 client 需主动接收。如果链路是 A→B→C,且每跳都要按 x-version 路由,那就每一跳都得做提取 + 附加。
典型写法:
- client 侧发送:
md := metadata.Pairs("x-version", "v2"); ctx = metadata.NewOutgoingContext(ctx, md) - server 侧接收:
md, ok := metadata.FromIncomingContext(ctx); if ok { version := md.Get("x-version") } - server 若需继续往下传,得再构造新的 outgoing context,不能复用 incoming 的 md(它是只读的)
最易被忽略的一点:Kratos 的 gRPC Server 默认不解析 metadata 到 ctx.Value,你得自己写 middleware 抽出来塞进去,否则 downstream selector 拿不到上下文里的版本信息。











