hyperf网关需在请求入口中间件提取x-gray-tag等灰度头并存入context，再实现自定义loadbalancerinterface，在select()中基于context获取标签并匹配实例元数据，同时确保nacos配置get_metadata=>true且标签key统一。
Hyperf 里怎么让网关识别灰度请求头并路由到对应服务实例
Hyperf 默认的 HttpDispatcher 不解析业务级灰度标识，网关层必须在请求进入服务发现前就完成标签提取和路由决策。关键不是改路由表，而是把灰度上下文注入到 LoadBalancerInterface 的选择逻辑中。
常见错误是试图在控制器里用 $request->header('x-gray-tag') 做转发——这已经晚了，服务发现和节点选取早已完成。
- 在网关入口（如
RouterHandler或自定义中间件）中提前读取x-gray-tag、x-user-id等灰度标识，并存入Context::set()，例如：Context::set($request, 'gray_tag', $request->header('x-gray-tag', '')) - 确保该上下文能透传到后续的
ServiceInstanceSelector阶段——Hyperf 2.2+ 默认不自动传递，需手动在ConsulRegistry或NacosRegistry的getInstances()调用前补全 - 避免用
$_SERVER或全局变量存灰度信息，协程环境下会跨请求污染
怎么写一个支持标签匹配的自定义 LoadBalancer
Hyperf 的 RoundRobinLoadBalancer 是无状态的，没法感知实例标签。你得实现自己的 LoadBalancerInterface，并在 select() 中过滤带匹配标签的实例。
注意：不是所有注册中心都返回实例元数据（如 Consul 的 tags、Nacos 的 metadata），要先确认你用的注册中心是否暴露了 metadata 字段。
- 继承
AbstractLoadBalancer，重写select()；从Context::get($request, 'gray_tag')取值，再遍历$instances检查每个$instance->getMetadata()['gray-tag'] ?? ''是否匹配 - 如果没匹配到灰度实例，**不要直接 fallback 到随机选**，应按策略降级：比如返回空数组触发
NoAvailableInstanceException，由上层决定走默认集群还是报错 - 别在
select()里做 HTTP 请求或查 DB——这里要求毫秒级响应，否则整个网关吞吐量崩掉
为什么 Nacos 元数据里的 gray-tag 总是读不到
Hyperf 的 NacosRegistry 默认只拉取 ip、port、weight，metadata 字段被忽略，除非显式开启。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
典型现象是 $instance->getMetadata() 返回空数组，但你在 Nacos 控制台明明配置了 gray-tag: v2。
- 在
config/autoload/services.php中，给nacos配置加上'get_metadata' => true - 检查 Nacos 服务注册时是否用了
ephemeral=false（持久化实例），非临时实例的 metadata 在某些 Nacos 版本中不会实时同步 - Hyperf 3.0+ 对 Nacos v2.x 的 gRPC 支持不完整，若用的是 Nacos 2.2+，建议回退到 HTTP 模式或升级至 Hyperf 3.1.6+
灰度路由和健康检查冲突怎么办
当灰度实例因健康检查失败被剔除时，LoadBalancer 仍可能选中它——因为实例列表缓存未及时刷新，而灰度逻辑又依赖这个列表。
这不是 bug，是最终一致性模型下的正常现象，但会导致灰度流量误入故障节点。
- 调整注册中心心跳间隔：Nacos 设为
heartbeat-interval: 5，Consul 设check_interval = "5s"，缩短失效感知时间 - 在
select()开头加一层实时健康检查兜底：调用$instance->isHealthy()（Hyperf 3.0+ 支持），跳过不健康实例 - 禁止对灰度实例关闭健康检查——哪怕只是临时调试，也会导致路由不可控
最易被忽略的一点：灰度标签的 key 名必须全局统一，比如网关写 x-gray-tag，而服务端启动时注册用的是 gray_tag（下划线 vs 中划线），元数据对不上就完全失效。
