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 261c8c203ab docs: multi registry guide (#3226)
261c8c203ab is described below
commit 261c8c203abb0bd62e3e6a6dd0dd205618f3fda6
Author: DaWesen <[email protected]>
AuthorDate: Mon Aug 17 14:07:51 2026 +0800
docs: multi registry guide (#3226)
* docs: improve multi-registry guide
* Update
content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/multi_registry.md
Co-authored-by: Xuetao Li <[email protected]>
* Update
content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/multi_registry.md
Co-authored-by: Xuetao Li <[email protected]>
---------
Co-authored-by: Xuetao Li <[email protected]>
---
.../tutorial/service-discovery/multi_registry.md | 157 +++++++++++++++++++--
.../tutorial/service-discovery/multi_registry.md | 146 ++++++++++++++++++-
2 files changed, 282 insertions(+), 21 deletions(-)
diff --git
a/content/en/overview/mannual/golang-sdk/tutorial/service-discovery/multi_registry.md
b/content/en/overview/mannual/golang-sdk/tutorial/service-discovery/multi_registry.md
index 5654db65665..c624671f4c9 100644
---
a/content/en/overview/mannual/golang-sdk/tutorial/service-discovery/multi_registry.md
+++
b/content/en/overview/mannual/golang-sdk/tutorial/service-discovery/multi_registry.md
@@ -10,48 +10,96 @@ weight: 100
A Dubbo application can configure multiple registration centers at different
interface dimensions. Multiple registration centers can be used for cluster
isolation, migration, and various other scenarios. For a more detailed
explanation, refer to the <a
href="https://dubbo.apache.org/zh-cn/overview/mannual/java-sdk/reference-manual/registry/multiple-registry/";
target="_blank">Dubbo Java Multiple Registration Center Documentation</a>.
+## Usage Scenarios
+
+### Migration Scenario
+
+Migrate smoothly between different registration centers without service
interruption. For example, when migrating from ZooKeeper to Nacos, dual
registration keeps the business running during the transition.
+
+### Canary Release Scenario
+
+Deploy an independent canary registration center so that only specific traffic
can access the testing version. The new version is registered to the canary
center first, and after validation passes, it is released to all traffic,
reducing the risk of going live.
+
+### Cluster/Environment Isolation Scenario
+
+Use completely independent registration centers to isolate different service
environments so that they do not interfere with each other. Development,
testing, and production each have their own independent center, so debugging
services will not affect production traffic.
+
## API Configuration Method
+### Server
+
```go
ins, _ := dubbo.NewInstance(
+ dubbo.WithName("dubbo_multi_registry_server"),
dubbo.WithRegistry(
- registryWithID("nacos"),
+ registry.WithID("nacos"),
registry.WithNacos(),
registry.WithAddress("127.0.0.1:8848"),
),
dubbo.WithRegistry(
- registryWithID("zookeeper"),
+ registry.WithID("zookeeper"),
registry.WithZookeeper(),
registry.WithAddress("127.0.0.1:2181"),
),
)
-
```
-Specify which registration center a service under a specific server should
register to:
+Specify which registration center the services under a server should register
to:
+
```go
-// Specify that the service under the server registers to the zookeeper
registration center
+// Register the services under the server to the zookeeper registration center
srv, _ := ins.NewServer(server.WithServerRegistryIDs([]string{"zookeeper"}))
-// Specify that the service under the server registers to the nacos
registration center
+// Register the services under the server to the nacos registration center
srv2, _ := ins.NewServer(server.WithServerRegistryIDs([]string{"nacos"}))
```
Specify which registration center a particular service should register to:
+
```go
srv, _ := ins.NewServer()
greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{},
server.WithRegistryIDs([]string{"zookeeper"}))
```
-The usage on the client side is similar.
+### Client
+
+```go
+ins, _ := dubbo.NewInstance(
+ dubbo.WithName("dubbo_multi_registry_client"),
+ dubbo.WithRegistry(
+ registry.WithID("nacos"),
+ registry.WithNacos(),
+ registry.WithAddress("127.0.0.1:8848"),
+ ),
+ dubbo.WithRegistry(
+ registry.WithID("zookeeper"),
+ registry.WithZookeeper(),
+ registry.WithAddress("127.0.0.1:2181"),
+ ),
+)
+```
+
+Specify which registration center the client subscribes from:
+
+```go
+// Subscribe from the nacos registration center
+cli, _ := ins.NewClient(client.WithClientRegistryIDs([]string{"nacos"}))
+
+// Or subscribe from the zookeeper registration center
+cli2, _ := ins.NewClient(client.WithClientRegistryIDs([]string{"zookeeper"}))
+```
## YAML Configuration Method
+### Server
+
Modify the server configuration at go-server/conf/dubbogo.yaml to register the
service in both registration centers.
```yaml
dubbo:
+ application:
+ name: dubbo_multi_registry_server
registries:
zookeeper: # Specify the zookeeper registration center
protocol: zookeeper
@@ -63,15 +111,97 @@ dubbo:
triple:
name: tri
port: 20000
+ provider:
+ services:
+ GreeterProvider:
+ registry-ids: # Register to both registration centers
+ - zookeeper
+ - nacos
+ interface: "" # Interface name
```
+### Client
+
+```yaml
+dubbo:
+ application:
+ name: dubbo_multi_registry_client
+ registries:
+ nacos:
+ protocol: nacos
+ address: 127.0.0.1:8848
+ zookeeper:
+ protocol: zookeeper
+ address: 127.0.0.1:2181
+ consumer:
+ references:
+ GreeterClientImpl:
+ registry-ids: # Subscribe from the nacos registration center
+ - nacos
+ protocol: tri
+ interface: ""
+ GreeterClientImpl2:
+ registry-ids: # Subscribe from the zookeeper registration center
+ - zookeeper
+ protocol: tri
+ interface: "" # Interface name
+```
+
+## Additional Notes
+
+### How to Choose the Registration Center at Different Levels
+
+**Server level** `server.WithServerRegistryIDs` Default registration center
for all services under the server
+
+**Service level** `server.WithRegistryIDs` Registration center for a single
service
+
+**Client level** `client.WithClientRegistryIDs` Which registration centers the
client subscribes from
+
+### How to Verify Registration to Both Nacos and ZooKeeper
+
+After completing the configuration above and starting the server and client,
you can verify whether the multi-registration-center setup is successful in the
following ways.
+
+**Method 1: Check the client logs**
+
+The client logs should contain content similar to the following (time, log
level, and code location prefixes may vary depending on the environment):
+
+```text
+nacos client resp: greeting:"from nacos", err: <nil>
+zookeeper client resp: greeting:"from zookeeper", err: <nil>
+```
+
+Both logs show err as nil, which means the client has discovered and invoked
the service from Nacos and ZooKeeper respectively.
+
+**Method 2: Check the service instances in both registration centers**
+
+Query the service instances via the Nacos OpenAPI:
+
+```shell
+curl -s
'http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=dubbo_multi_registry_server&groupName=DEFAULT_GROUP'
+```
+
+> Note: `serviceName` needs to be replaced with the application name you
configured (the value set by `dubbo.WithName()` or `application.name`); the
ZooKeeper node path `/services/<application-name>` is the same.
+
+The expected hosts should contain the provider address (e.g.
`<provider-ip>:20000`) and healthy should be true.
+
+Query the service node via the ZooKeeper client:
+
+```shell
+docker exec dubbo-go-zookeeper zkCli.sh -server 127.0.0.1:2181 ls
/services/dubbo_multi_registry_server
+```
+
+The expected output is similar to `[<provider-ip>:20000]`. `<provider-ip>` is
the actual IP address registered by the service provider, which depends on the
local network environment.
+
+If both registration centers can see the service instances, it means the
service has been successfully registered to both Nacos and ZooKeeper, and the
client can discover and invoke the service from both registration centers.
+
## Supported Registration Centers
-* Nacos
-* Zookeeper
-* Polaris
-* Kubernetes
-For example, when using Polaris as a registration center, you need to specify
the following content, both via API or YAML configuration file:
+- Nacos
+- ZooKeeper
+- Polaris
+- Kubernetes
+
+For example, when using Polaris as a registration center, you need to specify
the following content, either via the API or the YAML configuration file:
```yaml
dubbo:
@@ -83,5 +213,4 @@ dubbo:
token: ${Polaris Resource Authorization Token} # If Polaris server
enables client authorization, this parameter needs to be configured
```
-For usage with Kubernetes registration centers, please refer to the [Control
Plane](/en/overview/mannual/control-plane/) documentation.
-
+For usage with Kubernetes registration centers, please refer to the [Control
Plane](/en/overview/mannual/control-plane/) documentation.
\ No newline at end of file
diff --git
a/content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/multi_registry.md
b/content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/multi_registry.md
index 33e7090a585..d7e3ab2e66b 100644
---
a/content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/multi_registry.md
+++
b/content/zh-cn/overview/mannual/golang-sdk/tutorial/service-discovery/multi_registry.md
@@ -10,17 +10,34 @@ weight: 100
一个 Dubbo 应用可以配置的多个接口维度的注册中心，多注册中心可用于集群隔离、迁移等多种场景，关于这部分更详细的说明可参考 <a
href="https://dubbo.apache.org/zh-cn/overview/mannual/java-sdk/reference-manual/registry/multiple-registry/";
target="_blank">Dubbo Java 多注册中心说明</a>。
+## 应用场景
+
+### 迁移场景
+
+在不同注册中心之间实现平滑迁移，不进行服务的中断。例如从 ZooKeeper 迁移到 Nacos，双注册保证过渡期间业务连续。
+
+### 灰度发布场景
+
+部署独立的灰度注册中心，仅特定流量可访问测试。新版本先注册到灰度中心，验证通过后再全量发布，降低上线风险。
+
+### 集群/环境隔离场景
+
+将不同的服务环境使用完全独立的注册中心隔离，互不干扰。开发、测试、生产各自独立，避免调试服务影响线上业务。
+
## API配置方式
+### 服务端
+
```go
ins, _ := dubbo.NewInstance(
+ dubbo.WithName("dubbo_multi_registry_server"),
dubbo.WithRegistry(
- registryWithID("nacos"),
+ registry.WithID("nacos"),
registry.WithNacos(),
registry.WithAddress("127.0.0.1:8848"),
),
dubbo.WithRegistry(
- registryWithID("zookeeper"),
+ registry.WithID("zookeeper"),
registry.WithZookeeper(),
registry.WithAddress("127.0.0.1:2181"),
),
@@ -29,6 +46,7 @@ ins, _ := dubbo.NewInstance(
```
指定某个 server 下的服务注册到哪个注册中心：
+
```go
// 指定 server 下的服务注册到 zookeeper 注册中心
srv, _ := ins.NewServer(server.WithServerRegistryIDs([]string{"zookeeper"}))
@@ -38,20 +56,53 @@ srv2, _ :=
ins.NewServer(server.WithServerRegistryIDs([]string{"nacos"}))
```
指定某个特定服务注册到哪个注册中心：
+
```go
srv, _ := ins.NewServer()
greet.RegisterGreetServiceHandler(srv, &GreetTripleServer{},
server.WithRegistryIDs([]string{"zookeeper"}))
```
-以上使用方式对 client 侧类似。
+### 客户端
+
+```go
+ins, _ := dubbo.NewInstance(
+ dubbo.WithName("dubbo_multi_registry_client"),
+ dubbo.WithRegistry(
+ registry.WithID("nacos"),
+ registry.WithNacos(),
+ registry.WithAddress("127.0.0.1:8848"),
+ ),
+ dubbo.WithRegistry(
+ registry.WithID("zookeeper"),
+ registry.WithZookeeper(),
+ registry.WithAddress("127.0.0.1:2181"),
+ ),
+)
+```
+
+指定从哪个注册中心订阅服务：
+
+```go
+// 指定从 nacos 订阅服务
+cli, _ := ins.NewClient(client.WithClientRegistryIDs([]string{"nacos"}))
+
+// 或指定从 zookeeper 订阅服务
+cli2, _ := ins.NewClient(client.WithClientRegistryIDs([]string{"zookeeper"}))
+```
## YAML配置方式
+## YAML配置方式
+
+如果使用配置文件方式传入配置，而不是 API 的方式，请参考以下 YAML 配置。
+
修改服务端配置 go-server/conf/dubbogo.yaml， 同时将服务注册在两个注册中心上。
```yaml
dubbo:
+ application:
+ name: dubbo_multi_registry_server
registries:
zookeeper: # 指定 zookeeper 注册中心
protocol: zookeeper
@@ -63,13 +114,94 @@ dubbo:
triple:
name: tri
port: 20000
+ provider:
+ services:
+ GreeterProvider:
+ registry-ids: # 同时注册到两个注册中心
+ - zookeeper
+ - nacos
+ interface: "" # 接口名
+```
+
+### 客户端
+
+```yaml
+dubbo:
+ application:
+ name: dubbo_multi_registry_client
+ registries:
+ nacos:
+ protocol: nacos
+ address: 127.0.0.1:8848
+ zookeeper:
+ protocol: zookeeper
+ address: 127.0.0.1:2181
+ consumer:
+ references:
+ GreeterClientImpl:
+ registry-ids: # 从 nacos 订阅服务
+ - nacos
+ protocol: tri
+ interface: ""
+ GreeterClientImpl2:
+ registry-ids: # 从 zookeeper 订阅服务
+ - zookeeper
+ protocol: tri
+ interface: "" # 接口名
+```
+
+## 补充说明
+
+### 不同级别如何选择注册中心
+**Server 级别** `server.WithServerRegistryIDs` 该 Server 下所有服务的默认注册中心
+
+**Service 级别** `server.WithRegistryIDs` 单个服务的注册中心
+
+**Client 级别** `client.WithClientRegistryIDs` 该 Client 从哪些注册中心订阅服务
+
+### 如何验证同时注册到 Nacos 和 Zookeeper
+
+完成上述配置并启动服务端和客户端后，可以通过以下方式验证多注册中心是否配置成功。
+
+**方式一：查看客户端日志**
+
+客户端日志中应包含类似以下内容（时间、日志级别和代码位置前缀会因运行环境而异）：
+
+```text
+nacos client resp: greeting:"from nacos", err: <nil>
+zookeeper client resp: greeting:"from zookeeper", err: <nil>
+```
+
+两条日志的 err 均为 nil，说明客户端已分别从 Nacos 和 Zookeeper 发现并调用服务。
+
+**方式二：查看两个注册中心的服务实例**
+
+通过 Nacos OpenAPI 查询服务实例：
+
+```shell
+curl -s
'http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=dubbo_multi_registry_server&groupName=DEFAULT_GROUP'
```
+> 注意：`serviceName` 需要替换为你配置的应用名（`dubbo.WithName()` 或 `application.name`
设置的值），Zookeeper 节点路径 `/services/<应用名>` 同理。
+
+预期 hosts 中包含服务提供者地址（如 `<provider-ip>:20000`）且 healthy 为 true。
+
+通过 Zookeeper 客户端查询服务节点：
+
+```shell
+docker exec dubbo-go-zookeeper zkCli.sh -server 127.0.0.1:2181 ls
/services/dubbo_multi_registry_server
+```
+
+预期输出类似 `[<provider-ip>:20000]`。其中 `<provider-ip>` 是服务提供者实际注册的 IP 地址，取决于本机网络环境。
+
+如果两个注册中心都能看到服务实例，说明服务已同时成功注册到 Nacos 和 Zookeeper，客户端也能从两个注册中心正常发现并调用服务。
+
## 支持的注册中心
-* Nacos
-* Zookeeper
-* Polaris
-* Kubernetes
+
+- Nacos
+- Zookeeper
+- Polaris
+- Kubernetes
比如使用 Polaris 作为注册中心时，你需要指定以下内容，使用 API 或 YAML 配置文件均可以：
