1. 核心检查点
- Zookeeper 是否可用
- 确认 Zookeeper 已启动，并监听端口（默认 2181）。
echo ruok | nc 127.0.0.1 2181- 返回
imok表示 Zookeeper 正常。
- Dubbo 配置正确
dubbo:registry中的address必须是zookeeper://host:port。- 示例：
<dubbo:application name="demo-provider"/> <dubbo:registry address="zookeeper://127.0.0.1:2181"/> <dubbo:protocol name="dubbo" port="20880"/>- Java Config 示例：
@Configuration public class DubboConfig { @Bean public RegistryConfig registryConfig() { RegistryConfig registry = new RegistryConfig(); registry.setAddress("zookeeper://127.0.0.1:2181"); return registry; } } - 服务端口可用
- Dubbo 协议端口（默认 20880）必须可用。
- 可以通过
netstat -an | grep 20880或lsof -i:20880检查端口是否被占用。
- 网络与防火墙
- 服务提供方必须能访问 Zookeeper 主机及端口。
- 检查防火墙或安全组规则：
telnet 127.0.0.1 2181- 若无法连接，服务无法注册。
2. 常见报错及原因
| 报错 | 可能原因 | 解决方案 |
|---|---|---|
NoRouteToHostException | 网络不通 | 检查 Zookeeper 地址、端口、防火墙 |
Connection refused | Zookeeper 未启动 | 启动 Zookeeper，检查 zoo.cfg |
Session expired | Zookeeper session 超时 | 调整 Dubbo 的 timeout 配置 |
java.net.ConnectException: Connection timed out | Zookeeper 地址或端口错误 | 确认 dubbo:registry 配置正确 |
Registry address is invalid | 地址格式错误 | 确认 zookeeper://host:port |
3. 配置优化
3.1 增加超时时间
Dubbo 注册到 Zookeeper 有超时机制，如果 ZK 访问慢可能导致注册失败：
<dubbo:registry address="zookeeper://127.0.0.1:2181" timeout="5000"/>
单位：毫秒
3.2 增加重连策略
Dubbo 默认有重试机制，但 Zookeeper 不可用时最好显式配置：
<dubbo:registry address="zookeeper://127.0.0.1:2181" check="false"/>
check="false"：即使注册中心不可用，服务也能启动。- 对于开发环境非常有用，生产环境建议谨慎。
3.3 Zookeeper 集群配置
如果使用 ZK 集群，Dubbo 地址可以写多个：
<dubbo:registry address="zookeeper://127.0.0.1:2181,127.0.0.2:2181,127.0.0.3:2181"/>
- Dubbo 会尝试多个节点，保证高可用。
4. 日志排查
- 开启 Dubbo 日志
- Log4j / Logback 配置：
<logger name="com.alibaba.dubbo" level="DEBUG"/>- 检查注册中心连接日志：
[Dubbo] Registering service ... [Dubbo] Failed to connect to registry - 查看 Zookeeper 日志
- ZK 默认日志路径：
zkServer.out或logs/zookeeper.log - 注意是否有连接、会话丢失、权限等错误。
- ZK 默认日志路径：
5. 版本兼容性
- Dubbo 与 Zookeeper 版本兼容
- Dubbo 2.7.x 以上推荐 Zookeeper 3.4.x 或 3.5.x
- 不同 ZK 客户端版本可能出现 SessionExpiredException
- Zookeeper 客户端依赖
- Maven 依赖示例：
<dependency> <groupId>org.apache.zookeeper</groupId> <artifactId>zookeeper</artifactId> <version>3.5.10</version> </dependency>
6. 其他建议
- 确保时间同步
- ZK 节点时间不一致可能导致 session 过期。
- 使用
ntpdate或系统时间同步工具。
- 防止端口冲突
- 多个服务启动时确保 Dubbo 端口不重复，ZK 端口固定。
- 测试 ZK 连接
- 使用
zkCli.sh命令连接：
./zkCli.sh -server 127.0.0.1:2181 ls /dubbo- 可以查看是否服务注册成功。
- 使用
- 本地测试环境
- 如果是本地测试，建议使用单机 Zookeeper。
- 在
application.properties中配置：
dubbo.registry.address=zookeeper://127.0.0.1:2181