Apache Dubbo项目中serialize.allowlist文件被覆盖问题的分析与解决方案

问题背景

在Apache Dubbo 3.2.5版本中，开发者在使用maven-assembly-plugin打包包含依赖的单一JAR文件时，遇到了一个关于安全序列化白名单文件(security/serialize.allowlist)被意外覆盖的问题。这个问题直接影响了Dubbo框架的安全序列化功能，导致自定义的白名单类无法被正确识别。

问题现象

开发者在本地的security/serialize.allowlist文件中添加了自定义类名(如benchmark.service.UserServiceResponse)，但在使用maven-assembly-plugin打包成包含依赖的JAR文件后，部署到远程服务器时发现该文件内容被还原为Dubbo项目原始的默认内容。这导致Dubbo框架在反序列化时抛出安全异常，提示自定义类不在允许列表中。

问题根源分析

经过深入调查，这个问题主要由以下几个因素共同导致：

1. Maven打包机制：当使用maven-assembly-plugin的jar-with-dependencies方式打包时，会将所有依赖的JAR文件解压并合并到一个新的JAR中。在这个过程中，如果多个依赖JAR包含相同路径的文件，默认情况下会覆盖而不是合并。

2. Dubbo依赖结构：Dubbo框架本身在它的JAR文件中包含了默认的serialize.allowlist文件。当项目被打包成包含依赖的单一JAR时，这个默认文件会覆盖开发者自定义的文件。

3. 文件冲突处理：标准的maven-assembly-plugin配置没有提供处理重复资源文件的策略，导致重要的配置文件被意外覆盖。

解决方案

针对这个问题，我们推荐以下几种解决方案：

方案一：使用maven-shade-plugin替代assembly-plugin

maven-shade-plugin提供了更灵活的资源文件处理能力，可以避免文件覆盖问题：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.2.4</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <transformers>
                    <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
                        <resource>security/serialize.allowlist</resource>
                    </transformer>
                </transformers>
            </configuration>
        </execution>
    </executions>
</plugin>

这种配置会确保所有serialize.allowlist文件内容被合并而不是覆盖。

方案二：自定义assembly-plugin的合并策略

如果必须使用assembly-plugin，可以通过自定义描述符文件来指定合并策略：

<assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0 http://maven.apache.org/xsd/assembly-1.1.0.xsd">
    <id>custom</id>
    <formats>
        <format>jar</format>
    </formats>
    <includeBaseDirectory>false</includeBaseDirectory>
    <fileSets>
        <fileSet>
            <directory>${project.build.outputDirectory}</directory>
            <outputDirectory>/</outputDirectory>
        </fileSet>
    </fileSets>
    <dependencySets>
        <dependencySet>
            <outputDirectory>/</outputDirectory>
            <useProjectArtifact>true</useProjectArtifact>
            <unpack>true</unpack>
            <unpackOptions>
                <filtered>true</filtered>
                <includes>
                    <include>**/*.class</include>
                    <exclude>security/serialize.allowlist</exclude>
                </includes>
            </unpackOptions>
        </dependencySet>
    </dependencySets>
</assembly>

方案三：运行时动态加载白名单

除了构建时的解决方案，还可以考虑在运行时动态加载白名单：

public class CustomAllowListChecker {
    public static void init() {
        try {
            // 从自定义位置加载白名单
            InputStream is = CustomAllowListChecker.class.getResourceAsStream("/custom.allowlist");
            // 将内容添加到Dubbo的白名单检查器中
            AllowListChecker.addAllowList(is);
        } catch (Exception e) {
            throw new RuntimeException("Failed to load custom allowlist", e);
        }
    }
}

最佳实践建议

1. 优先使用maven-shade-plugin：对于需要打包包含依赖的Dubbo应用，推荐使用maven-shade-plugin，它提供了更完善的资源处理能力。

2. 白名单管理策略：考虑将白名单管理从构建时移到运行时，通过外部配置文件或数据库来管理允许序列化的类名。

3. 版本控制：对serialize.allowlist文件进行版本控制，确保每次构建都能追踪到变更。

4. 构建验证：在持续集成流程中加入对最终JAR包内容的检查，确保重要配置文件没有被意外覆盖。

总结

在Apache Dubbo项目中使用包含依赖的打包方式时，资源文件冲突是一个常见但容易被忽视的问题。通过理解Maven打包机制和选择合适的插件配置，可以有效避免serialize.allowlist等关键配置文件被覆盖的问题。本文提供的解决方案不仅适用于当前问题，也可以推广到其他类似场景下的资源文件冲突处理。