DolphinScheduler离线安装依赖包缺失如何解决？

Question

在离线环境中部署DolphinScheduler时，常因无法连接中央仓库导致Maven依赖包缺失，尤其在构建前端资源或自定义插件时尤为明显。如何在无网络环境下完整获取并配置所需JAR包与Node模块，成为离线安装的关键难题。需预先在联网环境下载全部依赖并搭建本地私服或离线仓库，但易出现依赖版本不匹配、传递性依赖遗漏等问题，影响编译与服务启动。

Answer 1

1. 问题背景与核心挑战

在离线环境中部署 DolphinScheduler 时，由于无法访问 Maven 中央仓库（repo1.maven.org）或 NPM 公共源（registry.npmjs.org），导致构建过程频繁失败。尤其是在执行 mvn clean package 或前端资源编译（如使用 Webpack 构建 UI 模块）阶段，Maven 和 Node.js 会尝试下载依赖包，而离线环境缺乏这些基础组件。

常见报错包括：

• Could not find artifact org.apache.dolphinscheduler:dolphinscheduler-api:jar:3.1.0
• npm ERR! network request failed, unable to reach registry
• Dependency resolution failed due to missing transitive dependencies

这些问题的根源在于：未提前捕获完整的依赖树，尤其是传递性依赖（transitive dependencies），以及未建立本地可替代的私有仓库体系。

2. 常见技术误区分析

误区	表现形式	后果
仅拷贝主模块 JAR 包	手动复制 dolphinscheduler-core.jar 等核心包	缺少 Spring、MyBatis、Netty 等底层依赖，运行时报 ClassNotFoundException
忽略前端 node_modules	直接打包 dist 目录跳过 npm install	自定义插件无法编译，UI 打包失败
依赖版本不一致	混合使用不同版本的 Guava 或 Jackson	引发 NoSuchMethodError 或序列化异常
未处理 SNAPSHOT 版本	私服未缓存开发分支的快照依赖	CI/CD 流程中断，构建失败

3. 解决方案设计原则

为确保离线部署成功，必须遵循以下四项基本原则：

1. 完整性：获取所有直接与间接依赖，覆盖 compile、runtime、test、provided 等 scope。
2. 一致性：保证各模块使用的依赖版本统一，避免冲突。
3. 可复现性：构建流程应在任意离线节点上重复执行而不失败。
4. 自动化：通过脚本或 CI 工具自动导出依赖清单与归档文件。

为此，推荐采用“双仓库”架构：本地 Nexus 私服用于托管 Java 依赖，Nexus 或 Verdaccio 托管 NPM 模块。

4. 实施步骤详解

以下是完整的离线依赖准备流程：

# 步骤一：在联网机器上克隆并初始化项目
git clone https://github.com/apache/dolphinscheduler.git
cd dolphinscheduler
git checkout v3.1.0

# 步骤二：强制解析并下载所有 Maven 依赖
mvn dependency:go-offline -DskipTests

# 步骤三：导出依赖树以供审计
mvn dependency:tree > dependency-tree.log

# 步骤四：将本地 ~/.m2/repository 打包
tar -czf m2-repo.tar.gz ~/.m2/repository

# 步骤五：处理前端依赖
cd dolphinscheduler-ui
npm config set registry https://registry.npmmirror.com
npm install
npm pack --pack-destination ../offline-npm-packages/

# 可选：使用 verdaccio 缓存全部所需模块
verdaccio &
npm config set registry http://localhost:4873
npm install # 自动缓存到本地 registry

5. 本地私服搭建示例（Nexus）

使用 Sonatype Nexus Repository Manager 可集中管理 Maven 和 NPM 资源。

graph TD A[开发者机器] -->|推送| B[Nexus 私服] C[DolphinScheduler 构建机] -->|拉取| B D[NPM 客户端] -->|从 Verdaccio/Nexus 下载| E{Node Modules} B --> F[Maven Proxy: central] B --> G[NPM Proxy: registry.npmjs.org] H[镜像站] -->|同步| F

配置 settings.xml 指向本地 Nexus：

<mirrors>
  <mirror>
    <id>nexus-offline</id>
    <url>http://nexus.internal/repository/maven-all/</url>
    <mirrorOf>central</mirrorOf>
  </mirror>
</mirrors>

<profiles>
  <profile>
    <id>nexus</id>
    <repositories>
      <repository>
        <id>central</id>
        <url>http://nexus.internal/repository/maven-all/</url>
        <releases><enabled>true</enabled></releases>
        <snapshots><enabled>true</enabled></snapshots>
      </repository>
    </repositories>
  </profile>
</profiles>

6. 验证与持续集成策略

为保障长期可维护性，建议引入如下机制：

• 定期在 CI 环境中运行 mvn dependency:analyze 检查无用或缺失依赖。
• 使用 npm ls --parseable 输出依赖列表进行哈希比对。
• 构建 Docker 镜像时嵌入离线仓库数据卷，实现“一次打包，处处运行”。
• 对关键版本（如生产发布版）固化依赖快照，并签名归档。

例如，在 Jenkins Pipeline 中添加：

stage('Offline Validation') {
  steps {
    sh 'mvn dependency:go-offline -Dmaven.repo.local=./offline-repo'
    archiveArtifacts artifacts: 'dependency-tree.log, offline-repo/**'
  }
}