This is an automated email from the ASF dual-hosted git repository.
Alanxtl pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-website.git
The following commit(s) were added to refs/heads/master by this push:
new cd61b54b602 docs: improve ZooKeeper registry guide (#3220)
cd61b54b602 is described below
commit cd61b54b602ca7f2d354604301d46568c97281e8
Author: shiyudesu <[email protected]>
AuthorDate: Sun Aug 9 13:24:26 2026 +0800
docs: improve ZooKeeper registry guide (#3220)
* docs: improve ZooKeeper registry guide
* docs: update English ZooKeeper registry guide
---
.../tutorial/service-discovery/zookeeper.md | 192 +++++++++++++++++----
.../tutorial/service-discovery/zookeeper.md | 187 +++++++++++++++++---
2 files changed, 322 insertions(+), 57 deletions(-)
diff --git
a/content/en/overview/mannual/golang-sdk/tutorial/service-discovery/zookeeper.md
b/content/en/overview/mannual/golang-sdk/tutorial/service-discovery/zookeeper.md
index 9aaf9e1365c..f7b0082b054 100644
---
a/content/en/overview/mannual/golang-sdk/tutorial/service-discovery/zookeeper.md
+++
b/content/en/overview/mannual/golang-sdk/tutorial/service-discovery/zookeeper.md
@@ -2,24 +2,70 @@
aliases:
- /en/docs3-v2/golang-sdk/tutorial/develop/registry/zookeeper/
- /en/docs3-v2/golang-sdk/tutorial/develop/registry/zookeeper/
-description: Using Zookeeper as a registry
-title: Using Zookeeper as a registry
+description: Using ZooKeeper as a registry
+title: Using ZooKeeper as a registry
type: docs
weight: 11
---
-This example shows dubbo-go's service discovery feature with Zookeeper as
registry. You can view the
-<a
href="https://github.com/apache/dubbo-go-samples/tree/main/registry/zookeeper";
target="_blank">complete example source code</a>
-in dubbo-go-samples.
+This guide explains how to use ZooKeeper as a registry in Dubbo-Go. The
complete example is available
+in the <a
href="https://github.com/apache/dubbo-go-samples/tree/main/registry/zookeeper";
target="_blank">dubbo-go-samples/registry/zookeeper</a>
+directory.
-## Usage
+## Start ZooKeeper
-Specify the registry address as follows:
+### Start with Docker
+
+Run a local ZooKeeper instance with Docker:
+
+```shell
+docker run --name dubbo-go-zookeeper --rm -d -p 2181:2181 zookeeper:3.9.5
+```
+
+Confirm that the container is running:
+
+```shell
+docker ps --filter name=dubbo-go-zookeeper
+```
+
+### Start from a binary distribution
+
+Download a binary distribution from the
+[ZooKeeper releases
page](https://zookeeper.apache.org/releases.html#download). Extract the archive,
+copy the sample configuration, and start the service:
+
+```shell
+tar -xzf apache-zookeeper-3.9.5-bin.tar.gz
+cd apache-zookeeper-3.9.5-bin
+cp conf/zoo_sample.cfg conf/zoo.cfg
+bin/zkServer.sh start
+```
+
+Check the server status:
+
+```shell
+bin/zkServer.sh status
+```
+
+`Mode: standalone` indicates that the standalone ZooKeeper server is running.
Both startup methods
+use `127.0.0.1:2181` as the registry address.
+
+ZooKeeper also starts its administration server on port `8080` by default. If
that port is already
+in use, set another port in `conf/zoo.cfg` and restart ZooKeeper:
+
+```properties
+admin.serverPort=18080
+```
+
+## Configure the service provider
+
+The provider selects ZooKeeper with `registry.WithZookeeper()` and sets the
address with
+`registry.WithAddress()`:
```go
ins, _ := dubbo.NewInstance(
- dubbo.WithName("dubbo_registry_nacos_server"),
+ dubbo.WithName("dubbo_registry_zookeeper_server"),
dubbo.WithRegistry(
registry.WithZookeeper(),
registry.WithAddress("127.0.0.1:2181"),
@@ -29,41 +75,129 @@ ins, _ := dubbo.NewInstance(
protocol.WithPort(20000),
),
)
+```
+
+The options have the following purposes:
+
+- `dubbo.WithName()` sets the application name. The example uses
+ `dubbo_registry_zookeeper_server`, which becomes the application node name
in ZooKeeper after
+ registration.
+- `dubbo.WithRegistry()` adds the registry configuration.
+ - `registry.WithZookeeper()` selects ZooKeeper as the registry.
+ - `registry.WithAddress()` sets the ZooKeeper address. Separate multiple
addresses with commas.
+- `dubbo.WithProtocol()` adds the provider protocol configuration.
+ - `protocol.WithTriple()` exposes the service over the Triple protocol.
+ - `protocol.WithPort()` sets the protocol listening port to `20000`.
+
+After registration succeeds, the provider address is available under
+`/services/dubbo_registry_zookeeper_server` in ZooKeeper.
+
+## Configure the service consumer
+
+The consumer uses the same registry address. After the client is created,
Dubbo-Go subscribes to
+ZooKeeper and discovers the service provider:
+
+```go
+ins, _ := dubbo.NewInstance(
+ dubbo.WithName("dubbo_registry_zookeeper_client"),
+ dubbo.WithRegistry(
+ registry.WithZookeeper(),
+ registry.WithAddress("127.0.0.1:2181"),
+ ),
+)
+```
+
+The consumer also configures ZooKeeper through `dubbo.WithRegistry()`. It does
not need a server
+protocol or listening port because it obtains the provider address from the
registry.
+
+## Run the example
+
+Clone the sample repository and enter the ZooKeeper example directory:
+
+```shell
+git clone https://github.com/apache/dubbo-go-samples.git
+cd dubbo-go-samples/registry/zookeeper
+```
+
+### Start the service provider
+
+Run the following command in the first terminal:
+
+```shell
+go run ./go-server/cmd/server.go
+```
+
+The provider listens on port `20000`. Open another terminal and send an HTTP
request to verify the
+service:
+
+```shell
+curl \
+ --header "Content-Type: application/json" \
+ --data '{"name":"Dubbo"}' \
+ http://localhost:20000/greet.GreetService/Greet
+```
+
+Expected response:
-srv, err := ins.NewServer()
+```json
+{"greeting":"Dubbo"}
```
-## How to run
+### Inspect the registration data
-### Start Zookeeper server
-This example relies on Zookeeper as the registry; follow the steps below to
start a Zookeeper server first.
+If you started ZooKeeper with the Docker command above, open the CLI inside
the container:
-1. Start Zookeeper with Docker, run `docker run --rm -p 2181:2181 zookeeper`
or `make -f $DUBBO_GO_SAMPLES_ROOT_PATH/build/Makefile docker-up`.
-2. [Download and start
Zookeeper](https://zookeeper.apache.org/releases.html#download) locally on your
machine.
+```shell
+docker exec -it dubbo-go-zookeeper zkCli.sh
+```
+
+For a local ZooKeeper installation, enter the distribution's `bin` directory,
such as
+`$HOST_PATH/apache-zookeeper-3.9.5-bin/bin`, and start the CLI:
-### Run server
```shell
-$ go run ./go-server/cmd/server.go
+./zkCli.sh
+```
+
+After the connection succeeds, query the service node:
+
+```text
+ls /services/dubbo_registry_zookeeper_server
+```
+
+Expected output:
+
+```text
+[<provider-ip>:20000]
```
-Test RPC server works as expected:
+`<provider-ip>` is the IP address registered by the provider and depends on
the local network
+environment. An address using port `20000` confirms that the provider
registered successfully.
+
+### Start the service consumer
+
+Keep the provider running and execute the following command in the second
terminal:
+
```shell
-$ curl \
- --header "Content-Type: application/json" \
- --data '{"name": "Dubbo"}' \
- http://localhost:20000/greet.GreetService/Greet
+go run ./go-client/cmd/client.go
```
-Check URL address has been successfully registered into Zookeeper:
+The terminal prints service discovery and invocation logs, including the
following response:
+
+```text
+Greet response: greeting:"hello world"
+```
+
+This response confirms that the consumer discovered the provider through
ZooKeeper and invoked the
+service.
+
+If you started ZooKeeper with Docker, stop the container after finishing the
example:
+
```shell
-# Enter Zookeeper bin directory, for example
'$HOST_PATH/apache-zookeeper-3.5.9-bin/bin'
-$ ./zkCli.sh
-[zk: localhost:2181(CONNECTED) 0] ls /services/dubbo_registry_zookeeper_server
-[30.221.147.198:20000]
+docker stop dubbo-go-zookeeper
```
-### Run client
+If you started ZooKeeper from a local distribution, return to its directory
and run:
+
```shell
-$ go run ./go-client/cmd/client.go
-hello world
+bin/zkServer.sh stop
```
diff --git
a/content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/zookeeper.md
b/content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/zookeeper.md
index 561b57e454d..5072c1354aa 100644
---
a/content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/zookeeper.md
+++
b/content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/zookeeper.md
@@ -2,24 +2,69 @@
aliases:
- /zh/docs3-v2/golang-sdk/tutorial/develop/registry/zookeeper/
- /zh-cn/docs3-v2/golang-sdk/tutorial/develop/registry/zookeeper/
-description: 使用 Zookeeper 作为注册中心
-title: 使用 Zookeeper 作为注册中心
+description: 使用 ZooKeeper 作为注册中心
+title: 使用 ZooKeeper 作为注册中心
type: docs
weight: 11
---
-本文演示 dubbo-go 使用 Zookeeper 作为注册中心的服务发现能力，可在
+本文介绍如何在 Dubbo-Go 中使用 ZooKeeper 作为注册中心。完整示例位于
<a
href="https://github.com/apache/dubbo-go-samples/tree/main/registry/zookeeper";
target="_blank">dubbo-go-samples/registry/zookeeper</a>
-查看完整示例源码。
+目录。
-## 使用方式
+## 启动 ZooKeeper
-通过以下方式指定注册中心地址：
+### 使用 Docker 启动
+
+使用 Docker 启动一个本地 ZooKeeper 实例：
+
+```shell
+docker run --name dubbo-go-zookeeper --rm -d -p 2181:2181 zookeeper:3.9.5
+```
+
+确认容器已经启动：
+
+```shell
+docker ps --filter name=dubbo-go-zookeeper
+```
+
+### 使用发行包启动
+
+从 [ZooKeeper 下载页面](https://zookeeper.apache.org/releases.html#download)
+下载二进制发行包。解压后，复制示例配置并启动服务：
+
+```shell
+tar -xzf apache-zookeeper-3.9.5-bin.tar.gz
+cd apache-zookeeper-3.9.5-bin
+cp conf/zoo_sample.cfg conf/zoo.cfg
+bin/zkServer.sh start
+```
+
+通过以下命令检查运行状态：
+
+```shell
+bin/zkServer.sh status
+```
+
+看到 `Mode: standalone` 表示单机 ZooKeeper 已经启动。以上两种方式使用的注册中心
+地址均为 `127.0.0.1:2181`。
+
+ZooKeeper 默认还会使用 `8080` 端口启动管理服务。如果该端口已被占用，可在
+`conf/zoo.cfg` 中设置其他端口后重新启动：
+
+```properties
+admin.serverPort=18080
+```
+
+## 配置服务提供者
+
+服务提供者通过 `registry.WithZookeeper()` 选择 ZooKeeper，并通过
+`registry.WithAddress()` 指定地址：
```go
ins, _ := dubbo.NewInstance(
- dubbo.WithName("dubbo_registry_nacos_server"),
+ dubbo.WithName("dubbo_registry_zookeeper_server"),
dubbo.WithRegistry(
registry.WithZookeeper(),
registry.WithAddress("127.0.0.1:2181"),
@@ -29,41 +74,127 @@ ins, _ := dubbo.NewInstance(
protocol.WithPort(20000),
),
)
+```
+
+各配置项的作用如下：
+
+- `dubbo.WithName()` 设置应用名。示例使用
+ `dubbo_registry_zookeeper_server`，服务注册后会在 ZooKeeper 中生成对应的应用节点。
+- `dubbo.WithRegistry()` 添加注册中心配置。
+ - `registry.WithZookeeper()` 指定注册中心类型为 ZooKeeper。
+ - `registry.WithAddress()` 设置 ZooKeeper 地址，多个地址之间使用逗号分隔。
+- `dubbo.WithProtocol()` 添加服务提供者的协议配置。
+ - `protocol.WithTriple()` 指定使用 Triple 协议对外提供服务。
+ - `protocol.WithPort()` 设置协议监听端口，示例使用 `20000`。
+
+服务注册成功后，可以在 ZooKeeper 的
+`/services/dubbo_registry_zookeeper_server` 节点下看到服务地址。
+
+## 配置服务消费者
+
+消费者使用相同的注册中心地址。创建客户端后，Dubbo-Go 会从 ZooKeeper
+订阅并发现服务提供者：
+
+```go
+ins, _ := dubbo.NewInstance(
+ dubbo.WithName("dubbo_registry_zookeeper_client"),
+ dubbo.WithRegistry(
+ registry.WithZookeeper(),
+ registry.WithAddress("127.0.0.1:2181"),
+ ),
+)
+```
+
+消费者同样通过 `dubbo.WithRegistry()` 配置 ZooKeeper。这里不需要配置服务端监听
+协议和端口；消费者会从注册中心获取服务提供者的地址。
+
+## 运行示例
+
+先下载示例仓库并进入 ZooKeeper 示例目录：
+
+```shell
+git clone https://github.com/apache/dubbo-go-samples.git
+cd dubbo-go-samples/registry/zookeeper
+```
+
+### 启动服务提供者
+
+在第一个终端运行：
+
+```shell
+go run ./go-server/cmd/server.go
+```
+
+服务提供者会监听 `20000` 端口。新开一个终端，通过 HTTP 请求确认服务可用：
+
+```shell
+curl \
+ --header "Content-Type: application/json" \
+ --data '{"name":"Dubbo"}' \
+ http://localhost:20000/greet.GreetService/Greet
+```
+
+预期返回：
-srv, err := ins.NewServer()
+```json
+{"greeting":"Dubbo"}
```
-## How to run
+### 查看注册数据
-### Start Zookeeper server
-This example relies on zookeeper as registry, follow the steps below to start
a zookeeper server first.
+如果使用前面的 Docker 命令启动 ZooKeeper，可以直接进入容器内的客户端：
-1. Start zookeeper with docker, run `docker run --rm -p 2181:2181 zookeeper`
or `make -f $DUBBO_GO_SAMPLES_ROOT_PATH/build/Makefile docker-up`.
-2. [Download and start
zookeeper](https://zookeeper.apache.org/releases.html#download) locally on your
machine.
+```shell
+docker exec -it dubbo-go-zookeeper zkCli.sh
+```
+
+如果使用本地安装的 ZooKeeper，进入发行包的 `bin` 目录（例如
+`$HOST_PATH/apache-zookeeper-3.9.5-bin/bin`），然后打开命令行客户端：
-### Run server
```shell
-$ go run ./go-server/cmd/server.go
+./zkCli.sh
+```
+
+连接成功后输入以下命令查询服务节点：
+
+```text
+ls /services/dubbo_registry_zookeeper_server
+```
+
+预期输出类似：
+
+```text
+[<provider-ip>:20000]
```
-test rpc server work as expected:
+`<provider-ip>` 是服务提供者实际注册的 IP 地址，取决于本机网络环境。能够看到
+`20000` 端口对应的地址，
+说明服务提供者已经注册成功。
+
+### 启动服务消费者
+
+保持服务提供者运行，在第二个终端执行：
+
```shell
-$ curl \
- --header "Content-Type: application/json" \
- --data '{"name": "Dubbo"}' \
- http://localhost:20000/greet.GreetService/Greet
+go run ./go-client/cmd/client.go
```
-check url address successfully registered into zookeeper:
+命令执行后，终端会输出多行服务发现和调用日志，其中包含以下响应：
+
+```text
+Greet response: greeting:"hello world"
+```
+
+这说明消费者已经通过 ZooKeeper 找到服务提供者并完成调用。
+
+如果使用 Docker 启动 ZooKeeper，示例运行结束后可通过以下命令停止容器：
+
```shell
-# enter zookeeper bin directory, for example
'$HOST_PATH/apache-zookeeper-3.5.9-bin/bin'
-$ ./zkCli.sh
-[zk: localhost:2181(CONNECTED) 0] ls /services/dubbo_registry_zookeeper_server
-[30.221.147.198:20000]
+docker stop dubbo-go-zookeeper
```
-### Run client
+如果使用本地发行包启动，则回到 ZooKeeper 发行包目录执行：
+
```shell
-$ go run ./go-client/cmd/client.go
-hello world
+bin/zkServer.sh stop
```
