Hyperf 在私有云用 Nacos 做服务发现核心是配对服务地址与控制注册行为：需安装 hyperf/service-governance-nacos，启用 config/autoload/services.php 中 register 和 discovery，并通过 nacos.php 配置内网可达的 host、namespace_id 等参数，确保服务注册到正确命名空间且 IP 可达。
Hyperf 在私有云环境用 Nacos 做服务发现，核心就两件事：配对服务地址 + 控制注册行为。别碰 config_center.php，那是配置中心的；服务发现走的是 services.php 和 nacos.php 两个文件。
确认 service-governance-nacos 已安装且启用
只装 hyperf/nacos 或 hyperf/config-nacos 不管用——它们不负责服务注册发现。hyperf/service-governance-nacos 才是正主，它监听 MainWorkerStartListener 并在启动时调用 NacosClient::registerInstance()。
检查是否已安装：
composer show hyperf/service-governance-nacos
没装就执行：
composer require hyperf/service-governance-nacos
确保 config/autoload/services.php 中 enable 为 true，且 drivers.nacos 存在并启用（不是注释掉）：
-
register设为true才会注册本服务实例 -
discovery设为true才能自动拉取其他服务列表 - 若私有云 DNS 不通或 IP 不稳定，
host必须填 Nacos 服务的**内网可访问地址**（如nacos-prod.internal或10.20.30.40），不能写localhost或127.0.0.1
用环境变量驱动 nacos.php 配置，避免硬编码
config/autoload/nacos.php 是服务发现的连接底座，所有连接参数都应从 .env 读取。硬编码会导致测试/预发/生产环境切换失败。
典型配置片段（注意 key 名与官方文档一致）：
return [
'host' => env('NACOS_HOST', 'nacos'),
'port' => (int) env('NACOS_PORT', 8848),
'username' => env('NACOS_USERNAME', 'nacos'),
'password' => env('NACOS_PASSWORD', 'nacos'),
'namespace_id' => env('NACOS_NAMESPACE_ID', 'public'),
'group_name' => env('NACOS_GROUP_NAME', 'DEFAULT_GROUP'),
'ephemeral' => filter_var(env('NACOS_EPHEMERAL', 'true'), FILTER_VALIDATE_BOOLEAN),
'heartbeat' => (int) env('NACOS_HEARTBEAT', 5),
];
对应 .env 示例（私有云常见）：
NACOS_HOST=nacos.prod.cluster.local NACOS_PORT=8848 NACOS_USERNAME=admin NACOS_PASSWORD=Secr3t@2026 NACOS_NAMESPACE_ID=prod-ns-7a2b NACOS_GROUP_NAME=hyperf-prod NACOS_EPHEMERAL=true NACOS_HEARTBEAT=10
关键点：
-
ephemeral默认true，私有云若要求强一致性注册（如配合 LB 做长连接粘滞），可设为false，但需确认 Nacos Server 允许持久化实例 -
heartbeat调大（如 10s）可降低私有云内网心跳压力，但故障感知延迟上升 -
namespace_id必须和 Nacos 控制台创建的命名空间 ID 完全一致（不是名称），大小写敏感
services.php 中声明服务角色与分组隔离
config/autoload/services.php 决定“谁注册、谁发现、按什么规则分组”。私有云多租户场景下，group_name 和 namespace_id 是隔离边界。
示例配置（仅保留 Nacos driver）：
return [
'enable' => true,
'drivers' => [
'nacos' => [
'driver' => \Hyperf\ServiceGovernanceNacos\NacosDriver::class,
'group_name' => env('NACOS_GROUP_NAME', 'DEFAULT_GROUP'),
'namespace_id' => env('NACOS_NAMESPACE_ID', 'public'),
'ephemeral' => filter_var(env('NACOS_EPHEMERAL', 'true'), FILTER_VALIDATE_BOOLEAN),
],
],
];
注意：
- 不要在
drivers.nacos下重复写host/port等连接参数——它们只在nacos.php里生效 -
group_name和namespace_id必须与nacos.php保持一致，否则注册到错分组/错命名空间，服务互相不可见 - RPC 服务（如
@RpcService(publishTo="nacos")）依赖此配置生效；HTTP 服务若只做消费者，也必须开启discovery才能解析下游服务地址
验证注册结果与常见连通性问题
启动服务后，立刻去 Nacos 控制台（http://<NACOS_HOST>:8848/nacos）检查：服务管理 → 服务列表 是否出现你的服务名（默认是 APP_NAME 值，如 user-service）。
如果看不到，优先排查：
- 容器或 Pod 是否能
curl -v http://nacos.prod.cluster.local:8848/nacos/v1/ns/instance?serviceName=test（测试基础连通） - 日志中是否有
NacosClient::registerInstance failed或GuzzleHttp\Exception\ConnectException -
NACOS_NAMESPACE_ID值是否复制错了（控制台里点进命名空间看「ID」列，不是「名称」列） - 私有云安全组/NetworkPolicy 是否放行了从应用节点到 Nacos 的
8848TCP 出向流量
服务注册成功但消费者调用失败？大概率是 services.php 里没开 discovery，或者下游服务没注册进同一个 namespace_id + group_name 组合。
私有云环境最易被忽略的点：Nacos 客户端注册时上报的 ip 是容器网络 IP，而消费者解析出来的也是这个 IP —— 如果你的 Hyperf 服务没暴露该 IP 给其他服务访问（比如没开 hostNetwork、没配 Service Mesh Sidecar、或没正确设置 server.host），调用必然超时。务必确认注册 IP 可达。
