当前位置：首页 > article >正文

Dubbo QoS操作手册

article 2026/1/14 18:26:26

QOS 操作手册

QoS概述

启动参数

参数	说明	默认值
qos-enable	是否启动Qos	true
qos-port	启动Qos绑定的端口	22222
qos-accept-foreign-ip	是否运行远程访问	false
qos-accept-foreign-whitelist	支持的远端地址ip地址（段）	无
qos-anonymous-access-permission-lefel	支持的匿名访问的权限级别	PUBLIC(1)

注意，从2.6.4/2.7.0开始，qos-accept-foreign-ip默认为false，如果qos-accept-foreign-ip设置为true，有可能带来安全风险，需仔细评估后打开

示例

zzw@Macmini dubboDemo04 % telnet localhost 22221
Trying ::1...
Connected to localhost.
Escape character is '^]'.___   __  __ ___   ___   ____     / _ \ / / / // _ ) / _ ) / __ \  / // // /_/ // _  |/ _  |/ /_/ /    
/____/ \____//____//____/ \____/   
dubbo>ls 
As Provider side:
+------------------------------------------------------------------------------------+---------------------+
|                                Provider Service Name                               |         PUB         |
+------------------------------------------------------------------------------------+---------------------+
|DubboInternal - ServiceApplication01/org.apache.dubbo.metadata.MetadataService:1.0.0|nacos-A(N)/nacos-I(N)|
+------------------------------------------------------------------------------------+---------------------+
|                           com.doudou.demo.api.DemoService                          |nacos-A(Y)/nacos-I(Y)|
+------------------------------------------------------------------------------------+---------------------+
As Consumer side:
+---------------------+---+
|Consumer Service Name|NUM|
+---------------------+---+

端口

新版本的telnet端口和dubbo协议的端口（20880）是不同的端口，默认为22222。
可通过配置进行修改dubbo.application.qos-port=22221

安全

默认情况下，dubbo接口任何主机发起的命令。
可通过配置修改dubbo.application.qos-accept-foreign-ip=false,拒绝远端主机发出的命令，只允许服务本机执行。
通过可以通过设置qos-accept-foreign-ip-whitelist来指定支持的远程主机ip地址（段），多个IP地址（段）之间用逗号分隔。

dubbo.application.qos-accept-foreign-ip-whitelist=123.12.10.13, 132.12.10.13/24

权限

为了对生命周期探针的默认支持，QoS提供了匿名访问的能力以及对权限级别的设置，目前支持的权限级别有：

PUBLIC(1)
- 默认支持匿名访问的命令权限级别，目前只支持生命周期探针相关的命令
PROTECTED(2)
- 命令默认的权限级别
PRIVATE(3)
- 保留的最高权限级别，目前未支持
NODE(4)
- 最低权限级别，不支持匿名访问

权限级别 PRIVATE > PROTECTED > PUBLIC > NODE，高级别权限可访问同级别和低级别权限命令。

以下命令权限为PUBLIC，其它命令默认权限为PROTECTED

命令	权限级别
Live	PUBLIC(1)
Startup	PUBLIC(1)
Ready	PUBLIC(1)
Quit	PUBLIC(1)

默认情况下，dubbo允许匿名主机发起匿名访问，只有PUBLIC权限级别的命令可以执行，其它更高权限的命令会被拒绝。

关闭匿名访问

可以通过设置qos-anonymous-access-permission-level=NONE关闭匿名访问。

设置权限级别

dubbo.application.qos-anonymous-access-permission-level=PROTECTED

QoS命令列表

Qos命令	说明	telnet用法示例	http用法示例
cd	设定服务上下文，cd之后所有的命令都是针对该服务	cd com.doudou.demo.api.DemoService	http://localhost:22222/cd?service=http://localhost:22222/cd?service=com.doudou.demo.api.DemoService
count	展示服务或方法调用次数。暂时只支持 dubbo 协议，不支持 triple 协议；RpcStatus 实现依赖 Active/Limit Filter，需改造	count com.doudou.demo.api.DemoService	http://localhost:22222/count?service=org.demo.DemoService&method=methodName
disableDetailProfiler	关闭 RPC 调用 profiler 工具（细粒度版本）	disableDetailProfiler	http://localhost:22222/disableDetailProfiler
disableRouterSnapshot	关闭 RPC 请求 Router 路由结果跟踪	disableRouterSnapshot	http://localhost:22222/disableRouterSnapshot
disableSimpleProfiler	关闭 RPC 调用 profiler 工具（粗粒度版）	disableSimpleProfiler	http://localhost:22222/disableSimpleProfiler
enableDetailProfiler	开启 RPC 调用 profiler 工具（细粒度版本）	enableDetailProfiler	http://localhost:22222/enableDetailProfiler
enableRouterSnapshot	开启 RPC 请求 Router 路由结果跟踪，有助于跟踪路由规则执行是否符合预期	enableRouterSnapshot org.demo.DemoService	http://localhost:22222/enableRouterSnapshot?service=org.demo.DemoService
enableSimpleProfiler	开启 RPC 调用 profiler 工具（粗粒度版）	enableSimpleProfiler	http://localhost:22222/enableSimpleProfiler
getAddress	查看某个服务的有效 ip 地址列表	getAddress org.demo.DemoService	http://localhost:22222/getAddress?service=org.demo.DemoService
getConfig	dump 当前应用的有效配置	getConfig	http://localhost:22222/getConfig
getEnabledRouterSnapshot	查看当前 “启用 Router 路由结果跟踪” 的服务列表	getEnabledRouterSnapshot	http://localhost:22222/getEnabledRouterSnapshot
getRecentRouterSnapshot	查看最近 32 条 “Router 路由结果跟踪” 数据	getRecentRouterSnapshot	http://localhost:22222/getRecentRouterSnapshot
gracefulShutdown	从注册中心下线当前 ip 实例注册的所有服务，与offline的区别是，该命令会同时通过 tcp 连接告知所有消费方停止调用此实例。	gracefulShutdown	http://localhost:22222/gracefulShutdown
help	帮助命令	help	http://localhost:22222/help
invoke	调用某个 RPC 服务	invoke org.demo.DemoService.methodName(1234, “abcd”, {“prop”:“value”})
live	检查当前进程/服务是否存活，可配置为 kubernetes liveness	live	http://localhost:22222/live
loggerInfo	查看当前日志 logger 配置	loggerInfo	http://localhost:22222/loggerInfo
ls	查看当前所有服务列表	ls	http://localhost:22222/ls
metrics	查看 metrics 指标，需开启metrics 统计才能看到数据。什么粒度？	metrics	http://localhost:22222/metrics
metrics_default	查看 metrics 指标，需开启metrics 统计才能看到数据。什么粒度？	metrics_default	http://localhost:22222/metrics_default
offline	从注册中心下线某个或多个服务（包含应用级和接口级地址）	offline 或 offline org.demo.DemoService	http://localhost:22222/offline 或 http://localhost:22222/offline?service=org.demo.DemoService
offlineApp	从注册中心下线某个或多个服务（仅应用级）	offlineApp 或 offlineApp org.demo.DemoService	http://localhost:22222/offlineApp?service=org.demo.DemoService
offlineInterface	从注册中心下线某个或多个服务（仅接口级）	offlineInterface 或 offlineInterface org.demo.DemoService	http://localhost:22222/offlineInterface?service=org.demo.DemoService
online	将一个或多个服务注册到注册中心（包含应用级和接口级地址）	online 或 online org.demo.DemoService	http://localhost:22222/online?service=org.demo.DemoService
onlineApp	将一个或多个服务注册到注册中心（仅应用级）	onlineApp 或 onlineApp org.demo.DemoService	http://localhost:22222/onlineApp?service=org.demo.DemoService··············
onlineInterface	将一个或多个服务注册到注册中心（仅接口级）	onlineInterface 或 onlineInterface org.demo.DemoService	http://localhost:22222/onlineInterface?service=org.demo.DemoService
ps	查看当前进程信息，包括监听的端口等	ps	http://localhost:22222/ps
publishMetadata	发布或更新当前应用Metadata数据（可用于手动更新应用级服务发现元数据）。publishMetadata 10 表示延迟 10s 发布。在3.3.0之前版本的命令为 publish-metadata	publishMetadata	http://localhost:22222/publishMetadata
pwd	查看当前服务上下文，与 cd 配合使用	pwd	http://localhost:22222/pwd
quit	退出当前 telnet 命令	quit
ready	检查当前进程/服务是否准备就绪对外服务，可配置为 kubernetes readiness	ready	http://localhost:22222/ready
serializeCheckStatus	检查当前在序列化白名单中的类列表	serializeCheckStatus	http://localhost:22222/serializeCheckStatus
serializeWarnedClasses	检查当前在序列化警告名单中的类列表	serializeWarnedClasses	http://localhost:22222/serializeWarnedClasses
setProfilerWarnPercent	控制序列化报警频率（仅限在警告名单中的类）	setProfilerWarnPercent 0.75	http://localhost:22222/setProfilerWarnPercent?k=0.75
shutdown	尝试关闭当前 Dubbo 应用（销毁所有资源，重启前无法恢复）	shutdown	http://localhost:22222/shutdown
startup	检查当前进程/服务是否已经正常启动，可配置为 kubernetes startup	startup	http://localhost:22222/startup
switchLogLevel	动态调整日志级别	switchLogLevel debug	http://localhost:22222/switchLogLevel?k=debug
switchLogger	切换日志logger组件。可用 logger 组件，可通过 loggerInfo 查看（切换前请务必确保应用已经加入相关组件依赖）	switchLogger log4j2	http://localhost:22222/switchLogger?k=log4j2
version	查看当前使用的 Dubbo 框架版本	version	http://localhost:22222/version

QoS命令详解

基础命令

help

列出所有命令

dubbo>help
+--------------------------+----------------------------------------------------------------------------------+
|                       cd | Change default service.                                                          |
+--------------------------+----------------------------------------------------------------------------------+
|                    count | Count the service.                                                               |
+--------------------------+----------------------------------------------------------------------------------+
|    disableDetailProfiler | Disable Dubbo Invocation Profiler.                                               |
+--------------------------+----------------------------------------------------------------------------------+
|    disableRouterSnapshot | Disable Dubbo Invocation Level Router Snapshot Print                             |
+--------------------------+----------------------------------------------------------------------------------+
|    disableSimpleProfiler | Disable Dubbo Invocation Profiler.                                               |
+--------------------------+----------------------------------------------------------------------------------+

version

显示当前运行的dubbo版本号

dubbo>version
dubbo version "3.1.6"

quit

退出命令状态

dubbo>quit
BYE!
Connection closed by foreign host.

服务管理命令

ls

列出服务消费者和提供者

dubbo>ls 
As Provider side:
+------------------------------------------------------------------------------------+---------------------+
|                                Provider Service Name                               |         PUB         |
+------------------------------------------------------------------------------------+---------------------+
|DubboInternal - ServiceApplication01/org.apache.dubbo.metadata.MetadataService:1.0.0|nacos-A(N)/nacos-I(N)|
+------------------------------------------------------------------------------------+---------------------+
|                           com.doudou.demo.api.DemoService                          |nacos-A(Y)/nacos-I(Y)|
+------------------------------------------------------------------------------------+---------------------+
As Consumer side:
+-----------------------------------------+-----------------+
|Consumer Service Name|NUM|
+-----------------------------------------+-----------------
|com.dubbo.dubbointegration.BackendService|nacos-AF(I-2,A-2)|
+-----------------------------------------+-----------------+

注意

带有 DubboInternal 前缀的服务是 Dubbo 内置的服务，默认不向注册中心中注册。
服务发布状态中的 nacos-A(Y) 第一部分是对应的注册中心名，第二部分是注册的模式（A 代表应用级地址注册，I 代表接口级地址注册），第三部分代表对应模式是否已经注册
服务订阅状态中的 nacos-AF(I-2,A-2) 第一部分是对应的注册中心名，第二部分是订阅的模式（AF 代表双订阅模式，FA 代表仅应用级订阅，FI 代表仅接口级订阅），第三部分中前半部分代表地址模式来源（A 代表应用级地址，I 代表接口级地址）后半部分代表对应的地址数量

online

当使用延迟发布功能的时候(通过设置 org.apache.dubbo.config.AbstractServiceConfig#register 为 false)，后续需要上线的时候，可通过 Online 命令

# 上线全部服务
dubbo>online
OK
# 上线部分服务
dubbo>online com.doudou.*
OK

offline

由于故障等原因，需要临时下线服务保持现场，可以使用 Offline 下线命令。

# 下线全部服务
dubbo>offline
OK
# 下线部分服务
dubbo>offline com.doudou.*
OK

框架状态命令

startup

检测当前框架是否已经启动完毕

dubbo>startup
true

ready

检测当前框架是否能正常提供服务（可能是临时下线）

dubbo>ready
false

live

检测当前框架是否正常运行（可能是永久异常）

dubbo>live
true

性能采样命令

性能采样功能可以对 Dubbo 处理链路上的各处耗时进行检测，在出现超时的时候 ( usageTime / timeout > profilerWarnPercent * 100 ) 通过日志记录调用的耗时。
此功能分为 simple profiler 和 detail profiler 两个模式，其中 simple profiler 模式默认开启，detail profiler 模式默认关闭。 detail profiler 相较 simple profiler 模式多采集了每个 filter 的处理耗时、协议上的具体耗时等。在 simple profiler 模式下如果发现 Dubbo 框架内部存在耗时长的情况，可以开启 detail profiler 模式，以便更好地排查问题。

enableSimpleProfiler

开启 simple profiler 模式，默认开启

dubbo>enableSimpleProfiler
OK

disableSimpleProfiler

关闭 simple profiler 模式，关闭后 detail profiler 也将不启用

dubbo>disableSimpleProfiler
OK

enableDetailProfiler

开启 detail profiler 模式，默认关闭，需要开启 simple profiler 模式才会真实开启

dubbo>enableDetailProfiler
OK. This will cause performance degradation, please be careful!

disableDetailProfiler

关闭 detail profiler 模式，关闭后不影响 simple profiler

dubbo>disableDetailProfiler
OK

setProfilerWarnPercent

设置超时时间的警告百分比。
命令：setProfilerWarnPercent {profilerWarnPercent}
profilerWarnPercent: 超时时间的警告百分比，取值范围 0.0 ~ 1.0，默认值为 0.75

dubbo>setProfilerWarnPercent 0.75
OK

路由状态命令

Dubbo 的很多流量治理能力是基于 Router 进行实现的，在生产环境中，如果出现流量结果不符合预期的情况，可以通过路由状态命令来查看路由的状态，以此来定位可能存在的问题。

getRouterSnapshot

获取当前的每层路由的分组状态。（仅支持 StateRouter）
命令：getRouterSnapshot {serviceName}
serviceName 为需要采集的服务名，支持匹配

enableRouterSnapshot

开启路由结果采集模式
命令：enableRouterSnapshot {serviceName}
serviceName 为需要采集的服务名，支持匹配

disableRouterSnapshot

关闭路由结果采集模式
命令：disableRouterSnapshot {serviceName}
serviceName 为需要采集的服务名，支持匹配

getEnabledRouterSnapshot

获取当前已经开启采集的服务

getRecentRouterSnapshot

通过 qos 命令获取历史的路由状态。（最多存储 32 个结果）

序列化安全审计

Dubbo 支持通过 QoS 命令实时查看当前的配置信息以及可信/不可信类列表。目前共支持两个命令：serializeCheckStatus 查看当前配置信息，serializeWarnedClasses 查看实时的告警列表。

serializeCheckStatus

dubbo>serializeCheckStatus
CheckStatus: WARNCheckSerializable: trueAllowedPrefix:
[C
[I
[J
[Ljava.io.ObjectStreamField;
boolean
byte
cha
...
pstore.shaded.org.apache.commons.collections.
sun.print.
sun.rmi.server.
sun.rmi.transport.
weblogic.ejb20.internal.
weblogic.jms.common.

或http://localhost:22221/serializeCheckStatus

{"checkStatus": "WARN", "allowedPrefix": ["java.lang.Float", "java.lang.IndexOutOfBoundsException", "java.util.Collections$UnmodifiableSortedSet", "java.lang.Integer", "java.util.Collections$UnmodifiableSortedMap", "java.math.BigDecimal", "......","com.alipay.oceanbase.obproxy.druid.pool.", "org.mozilla.javascript", "org.osjava.sj.", "org.apache.ibatis.reflection.", "org.apache.http.auth.", "sun.print.", "bsh.", "javax.print.", "org.aoju.bus.proxy.provider."]
}