参考手册 on Apache Dubbo

配置中心参考手册

Mon, 01 Jan 0001 00:00:00 +0000

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

配置中心在 Dubbo 中承担3个职责：

外部化配置：启动配置的集中式存储（简单理解为 dubbo.properties 的外部化存储）。
服务治理：服务治理规则的存储与通知。
动态配置：控制动态开关或者动态变更属性值

启用动态配置，以 Zookeeper 为例，可查看配置中心属性详解

<dubbo:config-center address="zookeeper://127.0.0.1:2181"/>

或者

dubbo.config-center.address=zookeeper://127.0.0.1:2181

或者

ConfigCenterConfig configCenter = new ConfigCenterConfig();
configCenter.setAddress("zookeeper://127.0.0.1:2181");

为了兼容 2.6.x 版本配置，在使用 Zookeeper 作为注册中心，且没有显示配置配置中心的情况下，Dubbo 框架会默认将此 Zookeeper 用作配置中心，但将只作服务治理用途。

外部化配置

请参考文档外部化配置

动态配置

[TODO 待完善]

服务治理

Zookeeper

默认节点结构：

namespace，用于不同配置的环境隔离。
config，Dubbo 约定的固定节点，不可更改，所有配置和服务治理规则都存储在此节点下。
dubbo，所有服务治理规则都是全局性的，dubbo 为默认节点
configurators/tag-router/condition-router/migration，不同的服务治理规则类型，node value 存储具体规则内容

Apollo

所有的服务治理规则都是全局性的，默认从公共命名空间 dubbo 读取和订阅：

不同的规则以不同的 key 后缀区分：

configurators，覆盖规则
tag-router，标签路由
condition-router，条件路由
migration，迁移规则

Nacos

所有的服务治理规则都是全局的，默认从 namespace: public 下进行读取，通过 dataId: interface name 以及 group: dubbo 去读取和订阅：

元数据参考手册

Mon, 01 Jan 0001 00:00:00 +0000

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

背景

dubbo provider中的服务配置项有接近30个配置项。排除注册中心服务治理需要之外，很大一部分配置项是provider自己使用，不需要透传给消费者。这部分数据不需要进入注册中心，而只需要以key-value形式持久化存储。 dubbo consumer中的配置项也有20+个配置项。在注册中心之中，服务消费者列表中只需要关注application，version，group，ip，dubbo版本等少量配置，其他配置也可以以key-value形式持久化存储。这些数据是以服务为维度注册进入注册中心，导致了数据量的膨胀，进而引发注册中心(如zookeeper)的网络开销增大，性能降低。
除了上述配置项的存储之外，dubbo服务元数据信息也需要被存储下来。元数据信息包括服务接口，及接口的方法信息。这些信息将被用于服务mock，服务测试。

以上的元数据都是基于接口级别。在3.0版本中，引入了应用元数据的概念，应用元数据描述的是整个应用的信息概览。并且引入了服务自省映射，用于应用级别的服务发现。

目标

需要将注册中心原来的数据信息和元数据信息保存到独立的key-value的存储中，这个key-value可以是DB，redis或者其他持久化存储。核心代码中支持了zookeeper，redis, nacos(推荐)的默认支持。

因为是基于key-value存储，key不会改变，最新的value会将原来的value进行覆盖

Provider存储内容的格式，参见：org.apache.dubbo.metadata.definition.model.FullServiceDefinition。是该类型gson化之后的存储。 Consumer存储内容，为Map格式。从Consumer端注册到注册中心的URL中的获取参数信息。即通过URL.getParameterMap()获取到的Map，进行gson化之后进行存储。

详细的内容，可以参考下面的sample输出。

配置

默认的元数据存储，额外支持以下几个特性：

失败重试
每天定时重刷

失败重试

失败重试可以通过retrytimes （重试次数,默认100），retryperiod（重试周期，默认3000ms）进行设置。

定时刷新

默认开启，可以通过设置cycleReport=false进行关闭。

完整的配置项：

dubbo.metadata-report.address=zookeeper://127.0.0.1:2181
dubbo.metadata-report.username=xxx ##非必须
dubbo.metadata-report.password=xxx ##非必须
dubbo.metadata-report.retry-times=30 ##非必须,default值100
dubbo.metadata-report.retry-period=5000 ##非必须,default值3000
dubbo.metadata-report.cycle-report=false ##非必须,default值true
dubbo.metadata-report.sync.report=false ##非必须,default值为false

如果元数据地址(dubbo.metadata-report.address)也不进行配置，会判断注册中心的协议是否支持元数据中心，如果支持，会使用注册中心的地址来用作元数据中心。

接下来看几个sample的配置。无论哪种配置方式，都需要引入maven依赖：

zookeeper:

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-metadata-report-zookeeper</artifactId>
</dependency>

redis:

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-metadata-report-redis</artifactId>
</dependency>

nacos:

<dependency>
 <groupId>org.apache.dubbo</groupId>
 <artifactId>dubbo-metadata-report-nacos</artifactId>
</dependency>

完整的sample，查看sample-2.7

方式一：在配置中心配置

参考sample：dubbo-samples-metadata-report/dubbo-samples-metadata-report-configcenter 工程。

配置中心配置

配置中心的配置，可以参考configcenter的文档。配置的内容如下：

dubbo.registry.address=zookeeper://127.0.0.1:2181
### 注意驼峰式风格
dubbo.metadata-report.address=zookeeper://127.0.0.1:2181 ###元数据存储的地址

在sample中，使用了Zookeeper作为配置中心。启动本地zookeeper服务之后，直接运行：org.apache.dubbo.samples.metadatareport.configcenter.ZKTools 就可以完成写入。如果配置中心使用了nacos，apollo，这些产品本身支持ops配置。

API 参考手册

Mon, 01 Jan 0001 00:00:00 +0000

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

Dubbo 的常规功能，都保持零侵入，但有些功能不得不用 API 侵入才能实现。

提示

Dubbo 中除这里声明以外的接口或类，都是内部接口或扩展接口，普通用户请不要直接依赖，否则升级版本可能出现不兼容。

API 汇总如下：

配置 API

org.apache.dubbo.config.ServiceConfig
org.apache.dubbo.config.ReferenceConfig
org.apache.dubbo.config.ProtocolConfig
org.apache.dubbo.config.RegistryConfig
org.apache.dubbo.config.MonitorConfig
org.apache.dubbo.config.ApplicationConfig
org.apache.dubbo.config.ModuleConfig
org.apache.dubbo.config.ProviderConfig
org.apache.dubbo.config.ConsumerConfig
org.apache.dubbo.config.MethodConfig
org.apache.dubbo.config.ArgumentConfig

详细参见：API配置

注解 API

org.apache.dubbo.config.annotation.DubboService
org.apache.dubbo.config.annotation.DubboReference

详细参见：注解配置

模型 API

org.apache.dubbo.common.URL
org.apache.dubbo.rpc.RpcException

上下文 API

org.apache.dubbo.rpc.RpcContext

详细参见：上下文信息 & 隐式传参 & 异步调用

服务 API

org.apache.dubbo.rpc.service.GenericService
org.apache.dubbo.rpc.service.GenericException

详细参见：泛化引用 & 泛化实现

org.apache.dubbo.rpc.service.EchoService

详细参见：回声测试

在线运维命令参考手册

Mon, 01 Jan 0001 00:00:00 +0000

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

dubbo 2.5.8 新版本增加了 QOS 模块，提供了新的 telnet 命令支持。

端口

新版本的 telnet 端口与 dubbo 协议的端口是不同的端口，默认为 22222，可通过配置文件dubbo.properties 修改:

dubbo.application.qos-port=33333

或者通过设置 JVM 参数:

-Ddubbo.application.qos-port=33333

安全

默认情况下，dubbo 接收任何主机发起的命令，可通过配置文件dubbo.properties 修改:

dubbo.application.qos-accept-foreign-ip=false

或者通过设置 JVM 参数:

-Ddubbo.application.qos-accept-foreign-ip=false

拒绝远端主机发出的命令，只允许服务本机执行

telnet 与 http 协议

telnet 模块现在同时支持 http 协议和 telnet 协议，方便各种情况的使用

示例如下：

➜ ~ telnet localhost 22222
Trying ::1...
telnet: connect to address ::1: Connection refused
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
 ████████▄ ███ █▄ ▀█████████▄ ▀█████████▄ ▄██████▄
 ███ ▀███ ███ ███ ███ ███ ███ ███ ███ ███
 ███ ███ ███ ███ ███ ███ ███ ███ ███ ███
 ███ ███ ███ ███ ▄███▄▄▄██▀ ▄███▄▄▄██▀ ███ ███
 ███ ███ ███ ███ ▀▀███▀▀▀██▄ ▀▀███▀▀▀██▄ ███ ███
 ███ ███ ███ ███ ███ ██▄ ███ ██▄ ███ ███
 ███ ▄███ ███ ███ ███ ███ ███ ███ ███ ███
 ████████▀ ████████▀ ▄█████████▀ ▄█████████▀ ▀██████▀


dubbo>ls
As Provider side:
+----------------------------------+---+
| Provider Service Name |PUB|
+----------------------------------+---+
|org.apache.dubbo.demo.DemoService| N |
+----------------------------------+---+
As Consumer side:
+---------------------+---+
|Consumer Service Name|NUM|
+---------------------+---+

dubbo>

➜ ~ curl "localhost:22222/ls?arg1=xxx&arg2=xxxx"
As Provider side:
+----------------------------------+---+
| Provider Service Name |PUB|
+----------------------------------+---+
|org.apache.dubbo.demo.DemoService| N |
+----------------------------------+---+
As Consumer side:
+---------------------+---+
|Consumer Service Name|NUM|
+---------------------+---+

支持的命令

ls 列出消费者和提供者

dubbo>ls
As Provider side:
+----------------------------------+---+
| Provider Service Name |PUB|
+----------------------------------+---+
|org.apache.dubbo.demo.DemoService| Y |
+----------------------------------+---+
As Consumer side:
+---------------------+---+
|Consumer Service Name|NUM|
+---------------------+---+

列出 dubbo 的所提供的服务和消费的服务，以及消费的服务地址数

Telnet 命令参考手册

Mon, 01 Jan 0001 00:00:00 +0000

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

从 2.0.5 版本开始，dubbo 开始支持通过 telnet 命令来进行服务治理。

使用

telnet localhost 20880

或者：

echo status | nc -i 1 localhost 20880

status命令所检查的资源也可以扩展，参见：扩展参考手册。

命令

以下展示了 dubbo 内建的 telnet 命令的说明和用法，此外，telnet 命令还支持用户自行扩展，参见：Telnet 命令扩展。

`ls`

ls: 显示服务列表
ls -l: 显示服务详细信息列表
ls XxxService: 显示服务的方法列表
ls -l XxxService: 显示服务的方法详细信息列表

`ps`

ps: 显示服务端口列表
ps -l: 显示服务地址列表
ps 20880: 显示端口上的连接信息
ps -l 20880: 显示端口上的连接详细信息

`cd`

cd XxxService: 改变缺省服务，当设置了缺省服务，凡是需要输入服务名作为参数的命令，都可以省略服务参数
cd /: 取消缺省服务

`pwd`

pwd: 显示当前缺省服务

`trace`

trace XxxService: 跟踪 1 次服务任意方法的调用情况
trace XxxService 10: 跟踪 10 次服务任意方法的调用情况
trace XxxService xxxMethod: 跟踪 1 次服务方法的调用情况
trace XxxService xxxMethod 10: 跟踪 10 次服务方法的调用情况

`count`

count XxxService: 统计 1 次服务任意方法的调用情况
count XxxService 10: 统计 10 次服务任意方法的调用情况
count XxxService xxxMethod: 统计 1 次服务方法的调用情况
count XxxService xxxMethod 10: 统计 10 次服务方法的调用情况

`invoke`

invoke XxxService.xxxMethod(1234, "abcd", {"prop" : "value"}): 调用服务的方法
invoke com.xxx.XxxService.XxxService.xxxMethod(1234, "abcd", {"prop" : "value"}): 调用全路径服务的方法
invoke xxxMethod(1234, "abcd", {"prop" : "value"}): 调用服务的方法(自动查找包含此方法的服务)
invoke xxxMethod({"name":"zhangsan","age":12,"class":"org.apache.dubbo.qos.legacy.service.Person"}) :当有参数重载，或者类型转换失败的时候，可以通过增加class属性指定需要转换类
当参数为Map<Integer,T>，key的类型为Integer时，建议指定类型。例如invoke com.xxx.xxxApiService({"3":0.123, "class":"java.util.HashMap"})

`select` ¹

select 1: 当 invoke 命令匹配到多个方法时使用，根据提示列表选择需要调用的方法

`status`

status: 显示汇总状态，该状态将汇总所有资源的状态，当全部 OK 时则显示 OK，只要有一个 ERROR 则显示 ERROR，只要有一个 WARN 则显示 WARN
status -l: 显示状态列表

`log` ²

log debug: 修改 dubbo logger 的日志级别
log 100: 查看 file logger 的最后 100 字符的日志

`help`

help: 显示 telnet 命帮助信息
help xxx: 显示xxx命令的详细帮助信息

`clear`

clear: 清除屏幕上的内容
clear 100: 清除屏幕上的指定行数的内容

`exit`

exit: 退出当前 telnet 命令行

Maven 插件参考手册

Mon, 01 Jan 0001 00:00:00 +0000

此文档已经不再维护。您当前查看的是快照版本。如果想要查看最新版本的文档，请参阅最新版本。

启动一个简易注册中心

以指定的 9099 端口启动一个简易注册中心 ¹：

mvn dubbo:registry -Dport=9099

生成 demo 服务提供者应用

生成指定接口和版本的服务提供者应用：

mvn dubbo:create -Dapplication=xxx -Dpackage=com.alibaba.xxx -Dservice=XxxService,YyyService -Dversion=1.0.0

如果端口不指定，默认端口为 9090 ↩︎

参考手册 on Apache Dubbo

配置中心参考手册

外部化配置

动态配置

服务治理

Zookeeper

Apollo

Nacos

元数据参考手册

背景

目标

配置

失败重试

定时刷新

完整的配置项：

方式一：在配置中心配置

配置中心配置

API 参考手册

提示

配置 API

注解 API

模型 API

上下文 API

服务 API

在线运维命令参考手册

端口

安全

telnet 与 http 协议

支持的命令

ls 列出消费者和提供者

Telnet 命令参考手册

使用

命令

ls

ps

cd

pwd

trace

count

invoke

select 1

status

log 2

help

clear

exit

Maven 插件参考手册

启动一个简易注册中心

生成 demo 服务提供者应用

`ls`

`ps`

`cd`

`pwd`

`trace`

`count`

`invoke`

`select` ¹

`status`

`log` ²

`help`

`clear`

`exit`