[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。

原因

  1. 3.3.x 默认就是 STRICT:AllowClassNotifyListener.DEFAULT_STATUS = STRICT,只要没显式配置 dubbo.application.serialize-check-status,未在白名单的类一律拒绝反序列化。

  2. 允许的类只有三个来源:

    • 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 截断出的包前缀。
  3. 自动信任看的是“本进程加载到的类”。新 DTO 如果只作为 ParentVO.nestedList 的泛型元素存在、从未出现在接口方法签名上,那么递归遍历必须依赖调用方本地那份 ParentVO 里真的声明了该字段。只要调用方还在用旧版 API 包,遍历就走不到这个类,白名单里自然没有它。

  4. 校验发生在 Class.forName 之前(DefaultSerializeClassChecker.loadClass0 先做【前缀哈希匹配】,【命中失败】才 classForName),所以在 STRICT 下先抛 4-21,而不是 ClassNotFoundException。

flowchart TD A[Hessian2 反序列化, 收到类名] --> B{allowPrefixes 前缀命中?} B -->|是| C[Class.forName 加载] B -->|否| D{模式} D -->|STRICT| E[抛 IllegalArgumentException, error code 4-21] D -->|WARN| F[放行并只告警一次] D -->|DISABLE| C C --> G[正常反序列化] classDef ok fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20 classDef bad fill:#FFEBEE,stroke:#C62828,color:#B71C1C classDef chk fill:#FFF8E1,stroke:#EF9A00,color:#8D6E00 class C,G ok class E bad class B,D chk

排查步骤(按顺序,每步都能收敛一种可能)

# 动作 判定
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 防线整体拆掉。

两个容易踩的坑

  1. 那条 Hessian/Burlap: '...' is an unknown class in <classloader> 不能当证据。hessian-lite 的 SerializerFactory.getDeserializer 会把 loadSerializedClass 抛出的任何异常统一记成这句,此处附带的就是那个 IllegalArgumentException;它既可能是“类确实不存在”,也可能只是“被安全校验拦下”。要判断类是否存在,只能查包内容。
  2. 新增嵌套 DTO 必须同步白名单。凡是“只作为泛型字段元素/泛型包装内容出现、不进方法签名”的 DTO,都应视为自动信任覆盖不到的高风险对象,建议把“新增嵌套 DTO ⇒ 检查 allowlist”写进评审清单,而不是等上线后按 4-21 逐个补。

总结

  • Dubbo 3.x 默认 STRICT 的序列化白名单是按本地类反射推导出来的;只出现在嵌套字段里的新 DTO,如果调用方 API 包没同步,就既进不了自动信任名单,也不在显式白名单里,于是被 4-21 拦下——先对齐 API 包,再给公共模块补一行 security/serialize.allowlist。

Y 推荐文献

X 参考文献

posted @ 2026-11-13 15:49  千千寰宇  阅读(12)  评论(0)    收藏  举报