服务名始终是配置的“user-service”，Consul控制台显示IP是Service ID而非Name；advertise_address仅影响健康检查连通性，配错会导致服务被下线而非改名。

Hyperf 服务注册到 Consul 后，控制台里显示的服务名是 172.18.0.5 或类似 IP 地址，而不是你配置的 user-service —— 这不是服务名被“改成”了 IP，而是你在 Consul 里看错了字段：你看到的其实是 Service ID（或 Node），不是 Name。真正决定服务发现时用什么名字查的，是注册时传入的 name 字段，它和 advertise_address 完全无关。

为什么 advertise_address 配置后服务在 Consul 里能被正确发现

这个配置只影响 Consul Server 能不能连上你的健康检查接口，不改服务名。它的作用是告诉 Consul：“当我要对这个服务做 HTTP 健康检查时，请访问这个地址”。如果配错，Consul 就会反复失败、标记为不健康、最终剔除实例——你感觉“服务不见了”，其实是被下线了，不是名字变了。

advertise_address 是 Consul Agent 的配置项，写在 config/autoload/consul.php 里，对应 Consul 启动参数中的 -advertise

它必须是 Consul Server 能直接路由访问到的 IP，比如容器部署时不能填 127.0.0.1，得填宿主机可访问的网关 IP 或 Docker 网络内其他节点可达的地址（如 172.18.0.5）

Hyperf 的 hyperf/consul 扩展注册服务时，address 字段默认取的是当前服务监听的 IP（由 server.settings.host 决定），这个值才是 Consul 健康检查实际调用的目标；而 advertise_address 只用于 gossip 协议同步，不影响服务注册内容本身

services.php 里 address 和 advertise_address 混用的典型错误

很多人把两者当成一回事，在 config/autoload/services.php 里写：

'address' => '127.0.0.1',

// 然后又在 consul.php 里配 advertise_address => '127.0.0.1'

结果 Consul Server 根本访问不到 127.0.0.1:9501/health（因为那是 Consul 自己的 localhost），健康检查持续超时，服务几秒后就消失。这不是名字问题，是连通性问题。

确认 services.php 中的 address 是真实对外可访问的 IP，不是 0.0.0.0 或 127.0.0.1

advertise_address 不需要和 address 一致，但必须保证 Consul Server 能通过它发起 TCP 连接（可用 telnet $advertise_address 9501 测试）

如果你用 Docker Compose，推荐用服务名代替 IP：address 设为 user-service（Docker DNS 可解析），同时确保 Consul 容器和应用容器在同一个 network 下

怎么验证服务名真没被覆盖

直接 curl Consul API 查原始注册数据：

curl "http://localhost:8500/v1/health/service/user-service"

看返回里的 Service.Name 字段是不是 "user-service"。如果是，说明名字完全正常；如果返回空，说明压根没注册成功，回头检查日志里有没有 ConsulClient::register(): failed 或连接拒绝类错误。

Hyperf 启动时会在日志里打印 [DEBUG] Register service user-service to consul，这是注册动作触发点

注册失败通常因网络不通、ACL token 权限不足、Consul Server 未就绪（No cluster leader）导致，和 advertise_address 配置无直接因果关系

服务名被替换成 IP 的唯一常见场景：你手动调用 ConsulAgent::registerService() 时传了 'name' => $ip，或者用了自定义注册逻辑覆盖了默认行为

真正容易被忽略的点是：Consul 控制台首页展示的“服务列表”默认按 Service ID 排序，而 ID 默认由 name+address+port 拼接生成（如 user-service-172.18.0.5-9501）。如果你只扫了一眼 ID 前缀，误以为那就是服务名，就会白调半天配置。

Tags: Hyperf Consul advertise_address

分享到：