[RPC/Java] Dubbo FAQ
0 序
1 FAQ for Dubbo RPC 调用框架
Q:Dubbo 3.3 报 4-21 Serialized class ... is not in allow list. Current mode is STRICT,新增的嵌套 DTO 为什么被拦?怎么修?
现象
服务 B 通过 Dubbo 调用服务 A 的接口,接口返回值里新增了一个 DTO 字段,之后调用方日志出现:
ERROR o.a.d.c.u.DefaultSerializeClassChecker
[DUBBO] [Serialization Security] Serialized class com.xxx.api.vo.NestedVO is not in allow list.
Current mode is STRICT, will disallow to deserialize it by default.
Please add it into security/serialize.allowlist or follow FAQ to configure it.,
dubbo version: 3.3.6, current host: 10.0.0.1, error code: 4-21
紧接着还有一条容易误判的 WARN:
WARN c.a.c.c.hessian.io.SerializerFactory
- Hessian/Burlap: 'com.xxx.api.vo.NestedVO' is an unknown class in
org.springframework.boot.loader.launch.LaunchedClassLoader@6f539caf:
java.lang.IllegalArgumentException: [Serialization Security] ...
业务上表现为“远程元数据/列表接口调用失败”,很容易被误判成提供方(服务 A)挂了。
结论
这不是“类不存在”,也不是序列化器故障,而是 Dubbo 3.x 的序列化白名单校验(默认 STRICT 模式)拦掉了一个只以“嵌套字段”形式出现的新 DTO。
原因
-
3.3.x 默认就是 STRICT:
AllowClassNotifyListener.DEFAULT_STATUS = STRICT,只要没显式配置dubbo.application.serialize-check-status,未在白名单的类一律拒绝反序列化。 -
允许的类只有三个来源:
- Dubbo 内置的
security/serialize.allowlist(java.*、Dubbo 自身类等); - 自动信任:
ProtocolSecurityWrapper在export()/refer()时调用SerializeSecurityConfigurator.registerInterface(),反射遍历接口方法签名,并递归进入 DTO 的字段/泛型实参; - 显式白名单:classpath 里的
security/serialize.allowlist、-Ddubbo.security.serialize.allowedClassList,或dubbo.application.trust-serialize-class-level截断出的包前缀。
- Dubbo 内置的
-
自动信任看的是“本进程加载到的类”。新 DTO 如果只作为
ParentVO.nestedList的泛型元素存在、从未出现在接口方法签名上,那么递归遍历必须依赖调用方本地那份ParentVO里真的声明了该字段。只要调用方还在用旧版 API 包,遍历就走不到这个类,白名单里自然没有它。 -
校验发生在
Class.forName之前(DefaultSerializeClassChecker.loadClass0先做【前缀哈希匹配】,【命中失败】才classForName),所以在 STRICT 下先抛4-21,而不是ClassNotFoundException。
排查步骤(按顺序,每步都能收敛一种可能)
| # | 动作 | 判定 |
|---|---|---|
| 1 | 在报错进程里确认 API 包内容:unzip -l xxx-api-*.jar | grep NestedVO;再 javap -p ... com.xxx.api.vo.ParentVO | grep -i nested |
找不到类或字段 → 调用方 API 包是旧的,属版本漂移,不是白名单问题 |
| 2 | 搜启动日志 Serialize check level:、Read serialize allow list from |
确认实际生效的模式与实际加载到的白名单资源文件 |
| 3 | 确认调用方是否走了 refer 且未被关闭自动信任(dubbo.application.auto-trust-serialize-class) |
若全局关了自动信任,会是大量类一起报错,而不是只有这一个 |
| 4 | 观察报错节奏 | 每进程每个类只报一条 ERROR(warnedClasses 去重),后续请求静默地继续抛异常——不是“偶发/已自愈” |
判别技巧:先把该类补进白名单。如果本地真有这个类,问题消失;如果本地没有,错误会立刻变成 Hessian 的 ClassNotFoundException——这正好证明是 API 包版本没对齐。
修复方案
| 方案 | 做法 | 适用 |
|---|---|---|
| A. 根因修复 | 所有调用方与提供方使用同一次构建的 API 包(嵌套 DTO 变更必须全链同步),重启 | 必做 |
| B. 白名单文件(推荐) | 在公共依赖模块的 src/main/resources/security/serialize.allowlist 追加一行 com.xxx.api.vo.NestedVO;需要覆盖整包时写 com.xxx.api.vo(匹配是前缀哈希,包前缀同样有效) |
一次覆盖所有依赖该模块的 JVM,零配置改动 |
| C. 单进程参数 | -Ddubbo.security.serialize.allowedClassList=com.xxx.api.vo.NestedVO(逗号分隔) |
不想改包/走发布流程 |
| D. 放宽前缀层级 | yaml\ndubbo:\n application:\n trust-serialize-class-level: 5 |
副作用:所有包层级超过 5 段的自动信任类都会退化成包前缀放行,范围比 B 宽 |
| E. 临时止血 | dubbo.application.serialize-check-status: WARN(值须为大写枚举名,内部走 valueOf) |
仅灰度救火;等于放行未知类,blockedlist 仍生效 |
不要为了“让它先跑起来”长期使用 -Ddubbo.security.serialize.openCheckClass=false(等价 DISABLE),这会把反序列化 RCE 防线整体拆掉。
两个容易踩的坑
- 那条
Hessian/Burlap: '...' is an unknown class in <classloader>不能当证据。hessian-lite的SerializerFactory.getDeserializer会把loadSerializedClass抛出的任何异常统一记成这句,此处附带的就是那个IllegalArgumentException;它既可能是“类确实不存在”,也可能只是“被安全校验拦下”。要判断类是否存在,只能查包内容。 - 新增嵌套 DTO 必须同步白名单。凡是“只作为泛型字段元素/泛型包装内容出现、不进方法签名”的 DTO,都应视为自动信任覆盖不到的高风险对象,建议把“新增嵌套 DTO ⇒ 检查 allowlist”写进评审清单,而不是等上线后按 4-21 逐个补。
总结
- Dubbo 3.x 默认 STRICT 的序列化白名单是按本地类反射推导出来的;只出现在嵌套字段里的新 DTO,如果调用方 API 包没同步,就既进不了自动信任名单,也不在显式白名单里,于是被
4-21拦下——先对齐 API 包,再给公共模块补一行security/serialize.allowlist。
Y 推荐文献
X 参考文献
本文链接: https://www.cnblogs.com/johnnyzen
关于博文:评论和私信会在第一时间回复,或直接私信我。
版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!
日常交流:大数据与软件开发-QQ交流群: 774386015 【入群二维码】参见左下角。您的支持、鼓励是博主技术写作的重要动力!

浙公网安备 33010602011771号