企业官网建设流程全解析

1. 别急着敲命令，先搞清楚注册中心到底在管什么

做微服务这块，注册中心这类组件有个特点：平常几乎感觉不到它的存在，一旦出问题，整条调用链就会立刻出问题。我见过不少团队在本地环境里用单机 Zookeeper 加一个 Dubbo-Admin，服务连通后就上线了，结果换到预发环境，Provider 注册成功、Consumer 却一直报No provider available，排查了半天才发现是注册中心地址少写了一个集群节点，Consumer 连到的从节点数据还没同步过来。所以这篇文章不打算只给几行命令，而是把 Zookeeper 注册中心和 Dubbo-Admin 管理平台这两块从选型到运行、从配置到排查完整梳理一遍，适合刚接触 Dubbo 这套体系、或者正打算把老项目从直连方式迁移到注册中心模式的同学参考。

先把基本概念说清楚。注册中心解决的核心问题只有一句话：让消费方在不写死 IP 和端口的前提下，知道服务方在哪里、还活着没有。听起来简单，但要满足两个硬性条件：一是服务变更能被及时感知，二是注册中心自己不能成为单点。Zookeeper 依靠它那套 ZNode 树加 Watcher 机制，天然具备"节点变化通知"的能力，Dubbo 早期就是围绕这个特性设计的。Dubbo-Admin 则是另一回事，它本身不参与调用链路，是个纯治理和运维控制台，负责把注册中心里的服务信息可视化出来，同时下发路由、限流、权重这类治理规则。两者角色完全不同，很多新手会把它们混在一起，以为没装 Dubbo-Admin 服务就调不通，其实不是，Admin 挂了业务照跑，只是你看不见、也改不了规则而已。

所以动手之前，我建议先把目标想明白：本地单机跑通是一回事，做一套能支撑日常联调和灰度验证的环境是另一回事。下面按"选型 → 环境 → ZK 搭建 → 业务接入 → Admin 搭建 → 排错"这条线走，每一段都给出可以直接照做的步骤和我踩过的坑。

2. 选型这步别拍脑袋，Zookeeper 与替代方案的真实差异

2.1 为什么这个场景我仍然倾向于 Zookeeper

现在提起注册中心，很多人第一反应是 Nacos，功能更全、自带配置中心、有控制台、支持 AP 模式。这话没错，但如果你的项目是存量系统，或者运维侧已经有一整套 Zookeeper 集群在被 Kafka、HBase 之类的组件共用，那么继续用 Zookeeper 做 Dubbo 注册中心就是最省事的选择——不用新引入一套中间件、不用额外做高可用、不用为运维团队增加学习成本。

Zookeeper 做注册中心的底层逻辑是临时顺序节点 + Watcher。Provider 启动时，在/dubbo/接口全限定名/providers/下面创建一个临时节点，节点名是 URL 编码后的完整服务信息，包含 IP、端口、超时、序列化方式、版本号等。临时节点的意思是：只要会话不断，节点就在；会话一断，节点自动删除。这就天然实现了服务下线感知——Provider 进程被 kill 掉，TCP 连接断开，ZK 会话超时后节点消失，Consumer 收到通知刷新本地缓存。整个过程不需要心跳上报、不需要额外的健康检查接口。

这个设计的优点是很直接，缺点也很明显：ZK 是 CP 系统，网络分区时少数派节点会拒绝服务，追求的是强一致。对注册中心这个场景来说，服务列表短暂不一致其实可以接受，CP 反而会在极端情况下造成可用性问题。这也是后来 Nacos 更受欢迎的原因之一。但只要你的集群规模不大、网络环境稳定，CP 带来的那点延迟完全在可接受范围内，反而省去了很多"列表不一致导致调用打到已下线机器"的麻烦。

2.2 几个关键选型点的取舍表

表格里最后一行值得多说一句：治理规则（也就是 override、route、condition 这些）在不同注册中心下的存储格式不一样，从 ZK 迁到 Nacos 时，原先在 Dubbo-Admin 里配的动态配置不会自动带过去，需要人工重配。这个坑我在一次迁移里真真切切踩过——迁移完成后所有服务正常调用，但原本对某台机器加的权重调整失效了，导致那台配置较差的机器被打满。

2.3 Dubbo-Admin 到底该不该装在线上

我的建议是：装，但要做好隔离。Dubbo-Admin 拥有下发治理规则的能力，一条错误的 override 规则可以让某个接口的所有调用都打到一个不存在的地址上，等于瞬间让服务不可用。所以我的做法是给它一个独立的、只在内网可达的地址，账号密码单独管理，绝不和业务系统共用一套鉴权；如果团队有运维平台，优先把 Admin 嵌进去做成只读视图，写操作留一个专门的治理窗口期来做。

3. 环境准备：版本对不齐，后面全是无意义的排查

3.1 版本矩阵先对齐，这是最容易翻车的地方

Dubbo 从 2.7 到 3.x 变化很大，其中和注册中心关系最密切的是应用级服务发现的引入。2.7 之前是接口级注册，一个接口在 ZK 下就是一棵子树；3.x 默认启用应用级注册，节点结构变成了/services/应用名/接口名/providers/。这个变化直接影响你在 ZK 里ls出来的结果，也影响 Dubbo-Admin 能不能正确展示服务。所以版本必须成套地对齐，而不是东拼西凑。

说明一下 Node 那一行。Dubbo-Admin 从 0.4 版本起前后端分离，前端用 Vue 写，打包时走frontend-maven-plugin自动下载 Node。这个插件下载的 Node 版本是写死在 pom 里的，通常偏低，如果你的构建机是 arm 架构或者是离线环境，这一步很容易失败。我的处理方式是给 Maven 配好镜像，或者提前把 Node 装好、把插件跳过，用-Dskip.npm之类的参数绕过去，具体参数名要看当时 pom 里的配置，不同小版本不一样，建议直接看 pom 里的 profile 定义。

Zookeeper 这边要注意的是 Curator。Dubbo 3.2 依赖的是dubbo-dependencies-zookeeper-curator5，对应 Curator 5.x，而 Curator 5.x 要求 ZK 服务端至少是 3.5 以上。如果你拿了一个 3.4 的 ZK 服务端去连，客户端能连上，但某些 API 会抛KeeperException$UnimplementedException，报错信息很不直观，非常容易误判成网络问题。

3.2 机器与端口规划

单机做实验无所谓，但只要涉及多节点，端口就要提前规划清楚。一台机器上跑三个 ZK 实例做伪集群，需要三组端口：客户端端口（2181/2182/2183）、节点间数据同步端口（2888/2889/2890）、选举端口（3888/3889/3890）。这三组端口一个都不能少，尤其是选举端口，很多人只开 2181 和 2888，结果集群起不来，日志里只报一句Cannot open channel to 3 at election address，挂在那里干等。

# 以三台机器为例，防火墙放行的最小集合 firewall-cmd --permanent --add-port=2181/tcp firewall-cmd --permanent --add-port=2888/tcp firewall-cmd --permanent --add-port=3888/tcp firewall-cmd --reload

注意：2888 和 3888 是节点之间通信用的，千万别只对客户端开 2181。我见过一次预发环境三台机器只通了 2181，三节点看起来都起来了，但zkServer.sh status一直报Error contacting service，因为根本没选出 leader。

目录规划也有讲究。Zookeeper 有两类磁盘写入：事务日志（transaction log）和数据快照（snapshot）。默认两者都写在dataDir下，这对小集群没问题，但事务日志对磁盘同步写的要求很高，和数据快照混在一起会互相影响。所以我把它们分开：dataDir放快照，dataLogDir放事务日志，后者尽量放在独立磁盘上。这个细节在压测时体现得特别明显，混在一起时写入延迟抖动明显变大。

3.3 JDK 与目录约定

JDK 版本不需要特殊处理，8 以上都行，但要确认JAVA_HOME在当前 shell 里有效。ZK 的启动脚本会用这个变量去找 java，如果只在~/.bashrc里配了但用的是sudo或者 systemd 启动，就会找不到。这种情况下最稳妥的写法是在zkEnv.sh里显式 export 一下，或者在 systemd 的 unit 文件里写Environment="JAVA_HOME=/path/to/jdk"。

目录我习惯这样组织，后面所有命令都基于这个结构：

/opt/zk/ ├── zk1/ │ ├── bin/ conf/ lib/ │ ├── data/ # 快照，内含 myid │ └── logs/ # 事务日志 ├── zk2/ └── zk3/

每个实例一份完整解压目录，而不是共用一份再改配置，原因是 ZK 的启动脚本里有些路径是相对bin目录算的，共用配置目录容易出幺蛾子，多占几百兆磁盘换省心，值得。

4. Zookeeper 集群从零落地：先跑通再谈高可用

4.1 单机伪集群，把配置逻辑先摸透

写zoo.cfg之前，先明确一件事：server.N里的 N 是节点的myid，不是序号，也不要求连续，只要每个节点目录下的myid文件内容和配置里的 N 对得上就行。这一点不理解清楚，配出来的集群会出现"两个节点都是 leader"或者"一直选不出 leader"这种诡异现象。

以 zk1 的配置为例：

tickTime=2000 initLimit=10 syncLimit=5 dataDir=/opt/zk/zk1/data dataLogDir=/opt/zk/zk1/logs clientPort=2181 server.1=127.0.0.1:2888:3888 server.2=127.0.0.1:2889:3889 server.3=127.0.0.1:2890:3890

zk2、zk3 只需要改dataDir、dataLogDir、clientPort三项，server.*那三行保持完全一致。三份配置里的server.*必须一模一样，这是集群能互相识别的前提。

然后是 myid：

echo 1 > /opt/zk/zk1/data/myid echo 2 > /opt/zk/zk2/data/myid echo 3 > /opt/zk/zk3/data/myid

提示：myid 文件内容是纯数字加一个换行，不要有多余空格，也不要有 BOM。用 Windows 记事本改过这个文件的同学应该都懂那种痛——集群死活起不来，日志里全是Invalid myid或者干脆没反应。

4.2 zoo.cfg 里每个参数到底在说什么

tickTime=2000是 ZK 的时间基准单位，单位毫秒。后面两个参数都是它的倍数，所以改tickTime会连带影响超时计算。

initLimit=10表示 follower 启动时与 leader 完成数据同步的最大时长，即10 × 2000ms = 20 秒。数据量大的时候默认值不够用，典型表现是新加入的节点反复重启、日志里刷Too long to sync。这种情况把initLimit调到 20 甚至 30。

syncLimit=5表示 leader 与 follower 之间心跳超时，即5 × 2000ms = 10 秒。超过这个时间 leader 认为 follower 挂了，把它踢出集群。跨机房部署时这个值必须放大，因为跨机房的 RTT 波动可能就有几十毫秒，网络一抖动就会误判。

搜索一下网上的配置，经常还能看到maxClientCnxns=60，这是单个客户端 IP 到单个服务端的最大连接数。默认 60，如果压测时并发很高，会看到Too many connections from /x.x.x.x的错误。压测机只有一个 IP，很容易撞上限，但这种提示有点像防火墙 DDoS 限制，别一上来就往防火墙方向想。

另外一组容易被忽略的参数是autopurge.snapRetainCount和autopurge.purgeInterval。前者保留最近多少个快照，后者多久清理一次（单位小时）。不配的话，快照会无限堆积，跑上几个月磁盘就满了。我一般设成保留 3 个、每 24 小时清理一次。

4.3 启动与验证，别只看进程在不在

/opt/zk/zk1/bin/zkServer.sh start /opt/zk/zk2/bin/zkServer.sh start /opt/zk/zk3/bin/zkServer.sh start /opt/zk/zk1/bin/zkServer.sh status

status会输出Mode: leader或Mode: follower。三个节点里必须恰好有一个 leader、两个 follower。如果三个都是leader，说明三个节点互相看不到，各自成了单机；如果都是follower或者报Error contacting service，那就是端口不通或者 myid 冲突。

验证连通性还有几个四字命令，ZK 3.5 之后默认是关闭的，需要在zoo.cfg里显式放开：

4lw.commands.whitelist=stat,ruok,mntr,cons,srvr

放开之后能用的东西就多了：

echo stat | nc 127.0.0.1 2181 # 看连接数、模式、节点数 echo ruok | nc 127.0.0.1 2181 # 回 imok 说明活着 echo mntr | nc 127.0.0.1 2181 # 全量指标，做监控就靠它

mntr里的zk_avg_latency、zk_outstanding_requests、zk_followers几个指标建议直接接到监控里，尤其是zk_outstanding_requests，这个值持续上涨基本就等于服务端处理不过来了。

4.4 从三节点走向生产：会话超时与容量

生产环境的几件事按重要性排一下。

第一是sessionTimeout。Dubbo 默认的 ZK 会话超时是 60 秒，意味着 Provider 进程被 kill 之后，节点最长要 60 秒才会消失。这段时间里 Consumer 还会往这台机器发请求，全部失败。如果业务对故障切换时间敏感，可以把这个值调小，比如 10 到 15 秒。调小的代价是网络抖动时容易误判、节点频繁上下线，所以要和tickTime一起考虑，通常的经验值是sessionTimeout > 2 × tickTime，并且不要低于 10 秒。

第二是JVM 堆。ZK 默认堆不大，服务规模上去之后 GC 停顿会导致心跳超时。改法是在bin/zkEnv.sh里调JAVA_OPTS，或者用SERVER_JVMFLAGS环境变量覆盖。我的经验是，几千个节点的集群给 4G 到 8G 比较稳妥。

第三是不要把它当配置中心用。有人图省事，直接往 ZK 里塞配置节点、塞分布式锁，结果注册中心本身就变得很脆弱。ZK 的定位就是协调服务，承担过重的读写会拉高整个调用链的延迟，该拆就拆。

5. 业务侧接入：Provider 与 Consumer 的配置细节

5.1 依赖到底该引哪一个

Dubbo 3.2 的依赖写法有个变化，直接引dubbo核心包已经不够了，ZK 相关的 Curator 依赖被打包成了一个独立的 pom，需要单独引：

<dependency> <groupId>org.apache.dubbo</groupId> <artifactId>dubbo</artifactId> <version>3.2.10</version> </dependency> <dependency> <groupId>org.apache.dubbo</groupId> <artifactId>dubbo-dependencies-zookeeper-curator5</artifactId> <version>3.2.10</version> <type>pom</type> <scope>import</scope> </dependency>

用 Spring Boot 的话更简单，直接引 starter，ZK 的 Curator 依赖也一并带上：

<dependency> <groupId>org.apache.dubbo</groupId> <artifactId>dubbo-spring-boot-starter</artifactId> <version>3.2.10</version> </dependency>

注意：dubbo-dependencies-zookeeper-curator5和dubbo-dependencies-zookeeper绝对不能同时引。前者是 Curator 5，后者是 Curator 4，两者共存时 Maven 会按依赖调解规则选一个，你可能引的是 5 实际生效的是 4，然后连 3.8 的 ZK 就报序列化异常。排查的时候用mvn dependency:tree | grep curator看一眼真实版本，比看 pom 靠谱得多。

5.2 配置文件怎么写，关键参数逐个解释

YAML 形式的 Provider 配置：

dubbo: application: name: demo-provider qos-enable: false registry: address: zookeeper://127.0.0.1:2181 timeout: 10000 session: 15000 protocol: name: dubbo port: 20880 metadata-report: address: zookeeper://127.0.0.1:2181 config-center: address: zookeeper://127.0.0.1:2181

几个点是必须解释的。

metadata-report这一项在 Dubbo 3 里变得非常重要。因为应用级注册只把应用名注册上去，接口的详细信息（方法签名、参数类型）不再放在注册中心的节点里，而是通过元数据中心存起来，Consumer 订阅接口时再去元数据里取。如果不配这个，Dubbo-Admin 里能看到应用、但点进去看不到方法，服务测试功能也会报找不到方法元数据。

config-center是配置中心，用来存放全局配置、动态配置。Dubbo-Admin 下发的治理规则就是写在这里的。不配的话，Admin 的规则管理页面能点但不能生效。

session是会话超时，前面说过，按业务容忍度调整。timeout是客户端操作的超时，注册中心网络较差时适当放大，不然启动阶段就会报Timeout waiting for connection。

Consumer 侧配置基本相同，把application.name改成自己的名字，protocol段可以省（消费方通常不需要暴露端口），另外加一段：

dubbo: consumer: check: false timeout: 3000 retries: 2

check: false表示启动时不校验依赖的服务是否存在。开发阶段强烈建议关掉，否则 Provider 还没起来，Consumer 就连启动都启动不了，白白增加调试成本。生产环境建议打开，因为启动阶段就暴露问题比运行时才发现强。

5.3 去 ZK 里看一眼，比看日志有效得多

配置好了启动，别急着看应用日志，先连上 ZK 确认节点到底写没写进去：

/opt/zk/zk1/bin/zkCli.sh -server 127.0.0.1:2181 [zk: ...] ls /dubbo [zk: ...] ls /dubbo/com.example.DemoService/providers [zk: ...] ls /services [zk: ...] ls /services/demo-provider

如果开的是接口级注册（dubbo.application.register-mode=interface），能在/dubbo/接口名/providers/下看到一个 URL 编码后的长字符串，解码后大概长这样：

dubbo://192.168.1.10:20880/com.example.DemoService?application=demo-provider&dubbo=2.0.2&methods=sayHello&pid=12345&timeout=3000&version=1.0.0

这个 URL 里的每一项都有用：pid用来在治理平台上做进程级操作，methods是暴露的方法列表，timeout是服务端声明的超时（注意，服务端声明的不等于消费端生效的，消费端的配置优先级更高），version用来做多版本共存。

如果开的是应用级注册（3.x 默认），节点在/services/demo-provider/下，你能看到接口名列表，但看不到那么详细的 URL，详细信息要去元数据中心看。这就是前面强调metadata-report必须配的原因。

5.4 应用级注册带来的几个实际变化

应用级注册的收益是注册中心节点数从"接口数量级"降到"应用数量级"，几千个接口的系统在 ZK 里的压力能降好几个量级。但它带来的副作用也要清楚。

一是服务发现的粒度变了。接口级注册时，Consumer 只订阅自己用到的接口；应用级注册时，Consumer 订阅的是应用，一次拿到该应用下所有接口的地址，再由本地根据接口元数据做映射。所以如果你有灰度需求，按应用维度做流量隔离会比按接口维度更自然，但反过来，想只对某一个接口做隔离就更麻烦了。

二是老客户端兼容问题。如果团队里有还在用 2.6 版本的老应用，连的是同一个 ZK，你会看到/dubbo和/services两套节点同时存在。这种混合部署可以跑，但要注意版本，老版本读不到新版本写进去的元数据格式，会出现部分服务找不到的情况。

三是dubbo.application.register-mode这个开关。它有三个值：interface、instance、all。all会同时注册两套，兼容性最好但节点数翻倍，适合迁移过渡期。迁移完成后切到instance能省一半节点。

6. Dubbo-Admin：从源码打包到真正用起来

6.1 打包这一步最容易卡住

Dubbo-Admin 没有官方发布的通用安装包，常规做法是拉源码自己打。整个工程里有两个模块和部署相关：dubbo-admin-server是后端，dubbo-admin-distribution负责把前后端产物合成一个可执行的 fat jar。

git clone https://github.com/apache/dubbo-admin.git cd dubbo-admin mvn clean package -Dmaven.test.skip=true

产物位置在dubbo-admin-distribution/target/dubbo-admin-0.6.0.jar这类路径下，具体名字带版本号，看 target 目录就知道。

这一步的坑主要集中在前端构建。frontend-maven-plugin会去下载 Node 和 npm，下载源在国外，网络稍差就卡死，表现是 maven 日志停在Downloading from central好几分钟不动，最后超时。两个处理方向：一是给 Maven 配国内镜像，二是提前在本机装好 Node 16，然后用 profile 跳过前端构建，直接把已经构建好的静态资源打进去。第二种方式适合 CI 环境，因为每次构建都下 Node 实在浪费。

还有一个更隐蔽的问题：构建机是 arm64 架构时，插件下载的 Node 是 x64 的，执行时报Exec format error。这种时候只能手动指定架构参数，或者干脆在 x86 机器上构建好再把 jar 拷过去。

提示：如果只是想快速跑起来看效果，可以先看官方镜像有没有现成的管理端镜像，拉下来直接配环境变量启动，省掉整个构建过程。真正要长期用、要做定制的时候再自己打包。

6.2 配置文件里那几行才是核心

jar 里带了一份application.properties，启动时可以用外部配置文件覆盖，也可以用启动参数覆盖。配置项从 0.6 版本开始统一用admin.前缀：

server.port=8080 admin.registry.address=zookeeper://127.0.0.1:2181 admin.config-center=zookeeper://127.0.0.1:2181 admin.metadata-report.address=zookeeper://127.0.0.1:2181 admin.registry.group=dubbo admin.config-center.group=dubbo admin.metadata-report.group=dubbo admin.registry.namespace= admin.config-center.namespace= admin.metadata-report.namespace= admin.root.user.name=root admin.root.user.password=root

三个地址必须和业务应用完全一致，group和namespace也一样。这几个值错一个，表现就是登录进去什么都看不到，或者只能看到一部分服务。尤其是namespace，如果你的业务应用在 ZK 里配了独立命名空间，Admin 不配就只能在根路径下找，自然找不到。

密码这一行，第一次登录之后立刻改掉。默认的 root/root 是公开的，接入内网也可能被扫到。Dubbo-Admin 支持在配置里加多用户，不同用户不同权限，虽然权限模型比较粗，但至少能把只读和可写分开。

启动：

java -jar dubbo-admin-0.6.0.jar \ --server.port=8080 \ --admin.registry.address=zookeeper://127.0.0.1:2181

命令行参数会覆盖 jar 内配置，适合容器化部署时用环境变量注入，不用改镜像里的文件。

6.3 控制台里真正值得用的几个功能

登录之后左侧菜单大致分三块：运维管理、规则管理、配置管理。功能不少，但我实际用得最多的就三样。

服务查询。按应用名或接口名搜，能看到 Provider 列表、Consumer 列表、每个实例的地址和权重。这里最实用的是"查看元数据"，能直接看到某个接口有哪些方法、参数类型是什么。做联调的时候，对方说"我调你接口报参数不匹配"，打开这一页一对比就知道是谁的接口版本不一致。

服务测试。这个功能相当于内置了一个轻量调用端，填上方法名和参数（JSON 格式），直接向 Provider 发起一次真实调用，返回结果直接显示在页面上。相比写一个 main 方法去测，这个效率高太多了。但要注意两点：一是 Admin 所在机器必须能通到 Provider 的 dubbo 端口（默认 20880），不通的话一直报超时；二是参数需要能正确反序列化，自定义对象要写成完整的 JSON 结构，字段类型对不上就会报序列化异常。

动态配置。这是最有杀伤力的功能。选一个应用或一个接口，下发一条 override 规则，比如把某台机器的权重设为 0，或者把某个方法的超时改成 5000。规则写进 config-center 后，Consumer 马上收到通知，下一次调用就生效。实际使用时的经验是：先在测试环境写好规则、验证效果，再复制到生产；生产上操作要两人复核，而且一定要在规定时间窗内完成，出事能立刻回滚。

一条典型的 override 规则长这样：

configVersion: v2.7 scope: application key: demo-provider enabled: true configs: - side: provider addresses: 192.168.1.10:20880 parameters: timeout: 5000 weight: 10

scope决定是应用级还是接口级，side决定作用在消费端还是服务端，addresses不填就是全量生效。这个地址千万别填错，我见过一次有人在测试环境把addresses填成了生产机器地址，虽然没造成事故，但排查了半天为什么线上某台机器"自己变了配置"。

6.4 生产部署时的几条经验

第一，Admin 不参与调用链，但不能没有。它挂了业务照跑，但你会失去治理能力，所以至少部署两个实例挂在一个内部负载后面，配置保持一致。

第二，别用 Admin 的账号密码当业务鉴权。它只是运维入口，账号体系很简单，不适合当统一认证。

第三，日志要单独收。Admin 的操作日志会记录谁下发了什么规则，这个在出问题时是唯一能追溯的线索。默认日志级别不高，建议调到 INFO 以上，并且把日志落到集中采集的地方。

第四，容器里跑的时候注意时区。Admin 显示的服务启停时间是按容器时区算的，容器默认 UTC，你会看到时间差 8 小时，排查问题时容易误判"这个服务刚起来一分钟"。

7. 踩坑实录：从"连不上"到"看得见"的完整排查路径

7.1 Zookeeper 侧的问题

集群起不来看不到 leader。排查顺序固定为：端口打通没有 → myid 内容对不对 →server.*三份配置是不是完全一致 →dataDir有没有写权限。这四步能覆盖九成情况。剩下的一成通常是data目录里残留了上一次不同配置下的version-2目录，导致节点认为自己是旧集群成员，把目录清掉重来即可。

Error contacting service. It is probably not running.这个提示非常通用，基本等于"我不知道怎么回事"。去看zookeeper.out或者logs目录下的日志，关键信息在里面。常见的有：端口被占、JDK 找不到、zoo.cfg语法错。

连接数被打满。前面提过的maxClientCnxns，压测时特别容易撞上。二是客户端没做连接复用，每个请求建一次连接，这种写法本身就有问题，ZK 的客户端应该是长连接加会话复用。

7.2 应用侧的问题

No provider available from registry，这是最经典的报错。按这个顺序查：

1. Provider 真的起来了没有，telnet ip 20880通不通；
2. ZK 里有没有对应的节点，ls /dubbo/接口名/providers有没有内容；
3. 接口的全限定名、版本号、分组是不是完全一致——version少写一个点都会导致订阅不上，而且报错看不出来是版本问题；
4. 消费端的注册中心地址、命名空间、分组和 Provider 是不是同一套。

第 3 条特别值得展开。Dubbo 的三元组（接口名 + 分组 + 版本）是订阅匹配的全部依据，任何一个不同都订阅不到。三联环境里常见的情况是 Provider 配了group: gray，Consumer 忘了配，然后就一直报找不到。这种问题看日志看不出来，只能去 ZK 里对照节点名。

启动报curator相关异常。基本上都是版本不匹配，用dependency:tree确认一下 Curator 是 4 还是 5，然后确认 ZK 服务端版本。Curator 5 连 ZK 3.4 的报错尤其隐蔽。

服务正常但 Admin 里看不到方法。前面说过的，metadata-report没配或者配错了。元数据中心也是 ZK 的时候，不配也能注册成功，但元数据不落盘，Admin 自然读不到。

7.3 Dubbo-Admin 侧的问题

7.4 一份可以直接照着走的排查清单

遇到"服务调不通"这类问题，我的固定动作是这样的：

# 1. 确认 ZK 集群健康 echo stat | nc 127.0.0.1 2181 # 2. 确认节点在不在 /opt/zk/zk1/bin/zkCli.sh -server 127.0.0.1:2181 ls /dubbo ls /dubbo/com.example.DemoService/providers # 3. 确认 Provider 端口可达 telnet 192.168.1.10 20880 # 4. 确认依赖版本 mvn dependency:tree | grep -E "curator|zookeeper|dubbo" # 5. 看消费端的注册中心缓存目录 ls ~/.dubbo/

第 5 步容易被忽略。Dubbo 会把订阅到的服务列表缓存在本地文件里，路径通常在用户目录下的.dubbo目录，文件名是dubbo-registry-xxx.cache。当注册中心挂了、应用重启时，Dubbo 会从这个缓存里恢复服务列表，所以有时会出现"注册中心明明是空的，但服务还能调"的怪现象。反过来，缓存文件损坏也会导致启动时读到错误的服务列表，删掉重启就好了。

注意：排查时不要一上来就改配置。先把现场信息固化下来（节点列表、依赖树、端口连通性、日志时间点），再动手。改完配置又没记录，出了问题连对比的基准都没有。

7.5 几个真正省时间的操作习惯

第一个习惯：所有 ZK 相关操作都开一个常驻的 zkCli 会话。ZK 的 Watcher 是会话级的，你在命令行里ls一次就退出了，看不到变化。开一个常驻会话，ls完之后再ls一次，中间注册新服务的时候能看到节点动态出现，比看日志直观得多。

第二个习惯：给 Admin 配一个专门的只读账号做日常查看。日常排查用只读账号，只有确实要改规则才切到写账号。这个习惯能避免手滑。

第三个习惯：记录每次规则变更的上下文。Admin 虽然有操作记录，但不会记录"为什么改"。我在团队里推的做法是，每次下发规则前在群里发一条：改什么、改哪个应用、预期效果、回滚方式。执行完之后把这条记录贴到工单里。这个流程看起来重，但真出事的时候能省下大量互相询问的时间。

8. 最后说说我自己踩过的那些具体问题

说一个印象最深的。有次在预发环境升级 Dubbo 版本，从 2.7 升到 3.2，所有服务都起来了，Admin 里也能看到应用，但服务测试全部报"找不到方法"。排查了整整一个下午，最后发现是升级时只升了业务应用的依赖，Admin 还是老版本，它按接口级注册的格式去读元数据，而新版本写的是应用级的格式，两边对不上。把 Admin 一起升到 0.6 之后立刻正常。这件事之后我给自己定了个规矩：注册中心、Dubbo 版本、Dubbo-Admin 版本，这三者的版本必须当成一个整体来管理，任何一个动，另外两个都要评估。

还有一个关于会话超时的坑。有个服务的 Provider 机器配置较低，GC 停顿偶尔超过 15 秒，而会话超时设的是 15 秒，结果就是 GC 一停、会话断开、节点被删、Consumer 收到下线通知，然后 Provider GC 结束、重新注册、Consumer 又收到上线通知。整个过程在 30 秒内完成，日志里表现就是"服务频繁上下线"，但监控上的可用性指标看不出明显下跌，因为每次都能自动恢复。这种抖动非常难查，最后是靠把mntr里的连接数曲线拉出来才定位到。会话超时不要设得太贴近 GC 停顿的上限，留出至少两倍的余量比较安全。

再分享一个配置上的小技巧。ZK 的连接串支持写多个地址：zookeeper://zk1:2181,zk2:2181,zk3:2181，客户端会自己做故障转移。很多人只写一个地址，理由是"反正它们是一个集群"。这个写法的问题在于，如果那一个节点恰好是 follower 并且在网络抖动中短暂不可用，客户端会重连失败一段时间。多写几个地址的成本为零，收益是启动时的容错能力，没有理由不写。

最后一个建议是给打算长期维护这套环境的同学：把 Zookeeper 的监控指标接出来。mntr输出的指标里，zk_outstanding_requests、zk_avg_latency、zk_followers这三个最能反映健康度。前两个持续上涨说明服务端扛不住，第三个掉到 2 以下说明集群有节点掉线。这三个指标接上告警，能挡掉大部分"服务莫名调不通"的工单，比事后翻日志效率高得多。