一、问题背景

在 Bigtop 编译 Apache Knox 2.1.0 的过程中，构建流程推进到测试相关模块：

gateway-test-release / webhdfs-test

前置模块（webhdfs-kerb-test）已经成功，但在 webhdfs-test 阶段，Maven 构建被 enforcer 插件强制中断，后续所有 Knox 模块全部 SKIPPED。

这类问题在 Knox + Hadoop 混合依赖 的场景中并不少见，通常不是代码错误，而是 历史依赖版本叠加后的收敛问题。

二、报错信息与关键日志

失败发生在 maven-enforcer-plugin:enforce-dependencies 阶段，核心日志如下：

Dependency convergence error for com.sun.jersey:jersey-core:1.19.4 paths to dependency are:
+- org.apache.knox:webhdfs-test:2.1.0
  +- com.sun.jersey:jersey-server:1.19.4
    +- com.sun.jersey:jersey-core:1.19.4
and
+- org.apache.knox:webhdfs-test:2.1.0
  +- org.apache.hadoop:hadoop-common:3.3.4
    +- com.sun.jersey:jersey-core:1.19

类似的冲突还出现在：

• jersey-servlet
• jersey-server
• jersey-json

最终 Maven 给出的结论是：

Rule 0: org.apache.maven.plugins.enforcer.DependencyConvergence failed

构建结果：

[INFO] --------------------< org.apache.knox:webhdfs-test >--------------------
[INFO] Building webhdfs-test 2.1.0                                        [2/5]
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- buildnumber-maven-plugin:1.4:create (default) @ webhdfs-test ---
[INFO] Executing: /bin/sh -c cd '/opt/modules/bigtop/dl/knox-2.1.0-RC2/gateway-test-release/webhdfs-test' && 'git' 'rev-parse' '--verify' 'HEAD'
[INFO] Working directory: /opt/modules/bigtop/dl/knox-2.1.0-RC2/gateway-test-release/webhdfs-test
[INFO] Storing buildNumber: 13021fcabafff320dfed6d0b8abed3ca630432b7 at timestamp: 1765449153438
[WARNING] Cannot get the branch information from the git repository:
Detecting the current branch failed: fatal: ref HEAD is not a symbolic ref

[INFO] Executing: /bin/sh -c cd '/opt/modules/bigtop/dl/knox-2.1.0-RC2/gateway-test-release/webhdfs-test' && 'git' 'rev-parse' '--verify' 'HEAD'
[INFO] Working directory: /opt/modules/bigtop/dl/knox-2.1.0-RC2/gateway-test-release/webhdfs-test
[INFO] Storing buildScmBranch: UNKNOWN
[INFO]
[INFO] --- maven-enforcer-plugin:3.0.0-M3:enforce (enforce-maven-version) @ webhdfs-test ---
[INFO]
[INFO] --- maven-enforcer-plugin:3.0.0-M3:enforce (enforce-maven) @ webhdfs-test ---
[INFO]
[INFO] --- maven-enforcer-plugin:3.0.0-M3:enforce (enforce-dependencies) @ webhdfs-test ---
[WARNING]
Dependency convergence error for com.sun.jersey:jersey-core:1.19.4 paths to dependency are:
+-org.apache.knox:webhdfs-test:2.1.0
  +-com.sun.jersey:jersey-server:1.19.4
    +-com.sun.jersey:jersey-core:1.19.4
and
+-org.apache.knox:webhdfs-test:2.1.0
  +-org.apache.hadoop:hadoop-common:3.3.4
    +-com.sun.jersey:jersey-core:1.19
and
+-org.apache.knox:webhdfs-test:2.1.0
  +-org.apache.hadoop:hadoop-common:3.3.4
    +-com.sun.jersey:jersey-json:1.19
      +-com.sun.jersey:jersey-core:1.19
and
+-org.apache.knox:webhdfs-test:2.1.0
  +-org.apache.hadoop:hadoop-hdfs:3.3.4
    +-com.sun.jersey:jersey-core:1.19
and
+-org.apache.knox:webhdfs-test:2.1.0
  +-org.apache.hadoop:hadoop-hdfs:3.3.4
    +-com.sun.jersey:jersey-core:1.19

[WARNING]
Dependency convergence error for com.sun.jersey:jersey-servlet:1.19.4 paths to dependency are:
+-org.apache.knox:webhdfs-test:2.1.0
  +-com.sun.jersey:jersey-servlet:1.19.4
and
+-org.apache.knox:webhdfs-test:2.1.0
  +-org.apache.hadoop:hadoop-common:3.3.4
    +-com.sun.jersey:jersey-servlet:1.19

[WARNING]
Dependency convergence error for com.sun.jersey:jersey-server:1.19.4 paths to dependency are:
+-org.apache.knox:webhdfs-test:2.1.0
  +-com.sun.jersey:jersey-server:1.19.4
and
+-org.apache.knox:webhdfs-test:2.1.0
  +-com.sun.jersey:jersey-servlet:1.19.4
    +-com.sun.jersey:jersey-server:1.19.4
and
+-org.apache.knox:webhdfs-test:2.1.0
  +-org.apache.hadoop:hadoop-common:3.3.4
    +-com.sun.jersey:jersey-server:1.19
and
+-org.apache.knox:webhdfs-test:2.1.0
  +-org.apache.hadoop:hadoop-hdfs:3.3.4
    +-com.sun.jersey:jersey-server:1.19
and
+-org.apache.knox:webhdfs-test:2.1.0
  +-org.apache.hadoop:hadoop-hdfs:3.3.4
    +-com.sun.jersey:jersey-server:1.19

[WARNING] Rule 0: org.apache.maven.plugins.enforcer.DependencyConvergence failed with message:
Failed while enforcing releasability. See above detailed error message.
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for webhdfs-kerb-test 2.1.0:
[INFO]
[INFO] webhdfs-kerb-test .................................. SUCCESS [01:33 min]
[INFO] webhdfs-test ....................................... FAILURE [ 19.826 s]
[INFO] gateway-shell-release .............................. SKIPPED
[INFO] gateway-docker ..................................... SKIPPED
[INFO] gateway-release-common ............................. SKIPPED
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:57 min
[INFO] Finished at: 2025-12-11T10:32:52Z
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-enforcer-plugin:3.0.0-M3:enforce (enforce-dependencies) on project webhdfs-test: Some Enforcer rules have failed. Look above for specific messages explaining why the rule failed. -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException
[ERROR]
[ERROR] After correcting the problems, you can resume the build with the command
[ERROR]   mvn <args> -rf :webhdfs-test

三、问题根因分析

1. Knox 自身依赖 Jersey 1.19.4

Knox 2.1.0 的部分测试模块，显式或间接依赖：

com.sun.jersey:*:1.19.4

这属于 Knox 侧主动升级的 Jersey 版本。

2. Hadoop 3.3.4 仍停留在 Jersey 1.19

而 Bigtop 中引入的 Hadoop 版本为：

org.apache.hadoop:hadoop-common:3.3.4

其依赖链中仍然使用：

com.sun.jersey:*:1.19

3. Enforcer 不允许「同 GAV 多版本并存」

maven-enforcer-plugin 的 DependencyConvergence 规则非常严格：

同一个 artifactId，在依赖树中只能存在一个版本

因此当 1.19 与 1.19.4 同时出现时，即使功能兼容，也会直接 fail。

注意

这是一个构建策略问题，不是运行期问题。 如果关闭 enforcer，构建是可以继续的，但并不推荐。

四、解决方案

思路说明

目标不是“消灭某条依赖路径”，而是：

让 Knox 与 Hadoop 在 Jersey 版本上达成一致

在当前 Knox + Hadoop 组合下，回退到 Hadoop 使用的 1.19 版本是风险最低、改动最小的方案。

方案：统一 Jersey 版本（推荐）

1. 修改 pom.xml

编辑文件：

gateway-test-release/webhdfs-test/pom.xml

在 <properties> 节点中加入：

<properties>
    <hadoop-jersey.version>1.19</hadoop-jersey.version>
</properties>

该 property 会被 Knox 构建体系中的依赖管理引用，从而统一 Jersey 版本。

提示

这种方式 不需要 exclude， 也不会影响 Hadoop 依赖路径， 属于「向下对齐」的稳妥修复。

2. 恢复构建

mvn compile -rf :webhdfs-test

正常情况下，webhdfs-test 将顺利通过，后续模块继续执行。