Kratos服务注册时必须显式注入Nacos Metadata（如version、env），否则下游无法按标签过滤实现灰度；客户端调用需配合Selector过滤，HTTP/gRPC需手动透传x-version头。

服务注册时必须带 Nacos Metadata 才能被正确发现

Kratos 本身不自动往 Nacos 注册实例的 metadata，如果只调用 NewRegistrar 而没显式注入版本或环境标签，下游 client 就无法按标签过滤——这会导致灰度、分组、路由全部失效。

正确做法是在初始化 registry.Registrar 前，把 metadata 注入到服务实例中：

• 在 main.go 构建 kratos.App 时，传入带 metadata 的 kratos.Metadata：

  kratos.Metadata(map[string]string{
      "version": "v2",
      "env": "prod",
      "region": "shanghai",
  })

• 确保 nacos.New(client) 创建的 registrar 支持透传 metadata（官方 contrib/registry/nacos 默认支持，但老版本需确认是否升级到 v2.6+）
• 不要依赖服务名后缀（如 user-service-v2）来区分版本——Nacos 控制台看到的是同一 serviceName 下多个 instance，metadata 才是服务发现层唯一可编程的分组依据

客户端发现必须用 Selector 过滤 Nacos 实例列表

Kratos 的 http.Client 和 grpc.Client 默认使用全量实例列表，不会自动读取 Nacos 返回的 metadata 做筛选。直接调用 client.NewClient 会把所有 v1/v2 实例都纳入负载均衡池，造成灰度流量泄露。

必须显式传入 transport.WithSelector 或 client.WithMiddleware：

Kratos框架 2.8.2

Kratos框架 2.8.2 源码包下载，针对 Watch Resolver goroutine 测试及指标、日志默认值问题进行修正。

下载

• 静态过滤（例如固定调 v2）：

  micro.Selector(Selector.WithFilter(func(s *registry.Service) bool {
      return s.Metadata["version"] == "v2"
  }))

• 动态过滤（从 ctx 提取 header）：需在中间件里把 x-version 存进 context，再在 selector 中读取：ctx.Value("x-version").(string)
• 注意：gRPC 的内置 round_robin balancer 不感知 metadata，所以不能只靠 grpc.WithBalancerName("round_robin")——必须在 Pick 阶段手动 filter registry.Service 列表

Nacos 客户端配置容易漏掉 NamespaceId 和 ServerConfig

很多团队启动 Kratos 服务后在 Nacos 控制台看不到实例，根本原因是 Nacos 客户端初始化失败，但 Kratos 默认 panic 信息不明确，只报 panic: failed to create naming client。

常见配置缺失点：

• NamespaceId 为空：Nacos 多命名空间下，不填就注册到 public 空间，而 discovery 默认也查 public，但如果控制台切了其他 namespace 就找不到——务必和运维确认 namespace ID 字符串（不是 name）
• ServerConfigs 中 IP 和 port 写反：constant.NewServerConfig(ip, port) 第二个参数是 uint64，写成字符串或 int 会静默失败
• 超时配置过短：TimeoutMs 小于 5000，在网络抖动时导致注册失败且重试逻辑不完善

HTTP 请求头透传 x-version 到下游需要两段中间件

上游加了 req.Header.Set("x-version", "v2")，下游收不到，是因为 Kratos 的 HTTP transport 默认不转发自定义 header，也不会自动把 header 注入 context。

必须手动桥接两次：

• 入口中间件（网关或第一跳服务）：提取 header 并存入 context

  ctx = context.WithValue(ctx, "x-version", r.Header.Get("x-version"))

• 出口中间件（调用下游前）：从 context 取值并写回新请求 header

  req.Header.Set("x-version", ctx.Value("x-version").(string))

• 别试图用 http.Transport 的 ProxyConnectHeader 或 Clone——它只处理 CONNECT 流量，对普通 HTTP 请求无效

Nacos metadata 是 Kratos 服务发现的“事实数据源”，所有路由、灰度、故障隔离逻辑都依赖它；但它的生命周期完全独立于 Kratos 自身，一旦注册时没写、客户端没读、header 没透传，整条链路就断在第一环。