接手烂尾的 Spring Cloud 微服务项目：从零搭建 26 模块编译环境

发表于 2026-06-09 更新于 2026-06-27 分类于后端开发，南网项目

导读

接手一个停更 2 年的 Spring Cloud Alibaba 微服务项目，13 个业务服务、11 个独立数据库、26 个 Maven 模块，本地 Maven 仓库空空如也，mvn compile 一跑就是红海一片。这篇记录我从零搭建编译环境的完整过程，包括 Maven 配置重写、私有依赖安装、22 个 SNAPSHOT jar 的手工恢复，以及最终 26 模块 BUILD SUCCESS 的关键命令。

🎧 文章导读

🎵 背景音乐

前言

智慧园区云平台（smart-park-cloud），项目 GroupId cn.csg.building，主干停留在 2023-12-27，dist_sync 分支最后提交 2025-07-30。JDK 1.8 + Spring Boot 2.5.7 + Spring Cloud 2020.0.5 + Spring Cloud Alibaba 2021.1——这一套组合在 2024 年都算”老古董”了，更别说还有私有的 com.xxkj 框架、Elastic-Job 1.x、Oracle JDBC 12c 这些早已不在公共仓库里的依赖。

最初的工作预期是”拉下来就能跑”，结果 mvn compile 报 Could not find artifact com.xxkj:xxkj-framework:2.6.0-SNAPSHOT——本地仓库没有，连这个 jar 在 Maven Central 上根本搜不到。本文记录怎么从这种”四无”状态（无文档、无私服账号、无原开发、无新提交）一步步把编译跑绿。

项目模块依赖结构图
图1：26 个 Maven 模块依赖关系

项目概况

维度	值
项目名	smart-park-cloud（智慧园区云平台）
GroupId	`cn.csg.building`
技术栈	Spring Boot 2.5.7 + Spring Cloud 2020.0.5 + Spring Cloud Alibaba 2021.1
Java 版本	JDK 1.8.0_261（`E:\jdk`）
Maven	`E:\maven363\apache-maven-3.6.3`
本地仓库	`F:\LocalWarehouse`
当前分支	`dist_sync`（2025-07-30 最后提交）
主分支	`master`（停在 2023-12-27）

模块规模：13 个微服务 + 11 个独立数据库 + 9 个业务服务，共 26 个 Maven 模块。

[!warning] 看似简单的项目结构
13 个服务看着不多，但 through-service 一项就引用 7 个其他服务（admin、aided、security、smart、property、env、warning），所有跨服务调用都通过 OpenFeign 走 Nacos 服务发现。任何一环缺依赖，整链都编译不过。

编译报错场景
图2：mvn compile 报错信息

问题背景

接到项目后第一件事是 mvn clean compile，结果：

内网 Maven 私服超时：默认配置指向 10.219.23.13:8081，本机根本连不上，每次依赖解析都要等 30 秒 timeout
本地仓库空空如也：除了系统自带的 jar，项目私有的 com.xxkj 系列全部缺失
私有 jar 从 git 删了：integrate-iot 模块引用的 7 个 system scope jar 被标记为 “no jar”，git history 里也丢了
失效的依赖：com.sun.jna:examples:1.0.0 在全球公共仓库都不存在，但项目里没有任何代码用

核心内容

一、分析项目结构

先把 13 个微服务 + 11 个数据库摸清。翻了所有 bootstrap*.yml 和 Flyway 迁移脚本后，整理出服务依赖矩阵：

service-util (基础工具)
   └── service-model (POJO/DTO)
          ├── admin-api ~ env-api (10 个 API 模块)
          ├── admin-service, aided-service, bpm-service
          ├── env-service, property-service, security-service
          ├── smart-service, through-service, warning-service
          ├── integrate-d3, integrate-iot (外部集成)
   └── xxkj-framework (私有框架)
          ├── xxkj-framework-dependencies (BOM)
          └── service-gateway, service-schedule (网关与调度)

关键发现：through-service 是依赖最重的核心模块，它要调 7 个其他服务的 Feign client，单独编译它就得先编译整个依赖链。

二、Maven 环境配置

2.1 找到真正在用的 settings.xml

最初以为 Maven 配置在 C:\Users\张\.m2\settings.xml，但 IDEA 启动后报”找不到 com.xxkj:xxkj-framework”。仔细看 Maven 帮助才意识到：**IDEA 用的 Maven 是 E:\maven363**，不是 PATH 里的默认。

1
2
3

# 找到 IDEA 实际用的 settings.xml
ls -la "E:\maven363\apache-maven-3.6.3\conf\settings.xml"
# 原文件 600+ 行，里面激活了大量内网私服 profile

2.2 重写 settings.xml

原配置问题严重：

激活 5+ 个内网私服 profile
默认每次解析都先打 10.219.23.13（堡垒机）
每次依赖解析卡 30 秒超时

新配置思路：移除所有内网仓库，只保留阿里云镜像。

<settings>
  <mirrors>
    <mirror>
      <id>aliyun-public</id>
      <name>aliyun maven</name>
      <url>https://maven.aliyun.com/repository/public</url>
      <mirrorOf>central,jcenter,public</mirrorOf>
    </mirror>
    <mirror>
      <id>aliyun-spring</id>
      <name>aliyun spring</name>
      <url>https://maven.aliyun.com/repository/spring</url>
      <mirrorOf>spring-milestones,spring-snapshots</mirrorOf>
    </mirror>
  </mirrors>
</settings>

修改后依赖解析速度从 30s+/次降到 < 1s/次。

[!tip] 小技巧
备份原配置很重要——后续可能要对比 blade.yaml 在内网配置了什么。settings.xml.bak2 是个明显的标记文件。

三、私有依赖安装

3.1 从别人给的本地仓库提取

关键素材：E:\nanwang\xxkj —— 之前同事给的本地仓库目录，里面有 22 个 com.xxkj SNAPSHOT jar。

1 2	# 复制到 IDEA 真正用的本地仓库 cp -r "E:\nanwang\xxkj\*" "F:\LocalWarehouse\"

但是 Maven 报”找不到 jar”——因为手动复制文件不会生成 _remote.repositories 元数据。正确做法是用 install:install-file 安装：

mvn install:install-file \
  -Dfile=xxkj-framework-2.6.0-SNAPSHOT.jar \
  -DgroupId=com.xxkj \
  -DartifactId=xxkj-framework \
  -Dversion=2.6.0-SNAPSHOT \
  -Dpackaging=jar

22 个 jar 一个个装确实麻烦，写了个 PowerShell 循环脚本，10 分钟搞定。

3.2 从 git 恢复 7 个 system scope jar

项目里 integrate-iot 模块用 system scope 引用了 3 个目录下的 jar：

<dependency>
  <groupId>com.dataphin</groupId>
  <artifactId>dataphinlibs</artifactId>
  <version>1.0</version>
  <scope>system</scope>
  <systemPath>${project.basedir}/dataphinlibs/dataphin-api-1.0.jar</systemPath>
</dependency>

这些 jar 在 git status 里显示被删除（项目配置 “no jar”）。从 git history 里翻到 2024 年的提交，逐个 git checkout <hash> -- path/to/jar，恢复 7 个 jar。

四、缺失依赖补齐

4.1 Elastic-Job 1.x 6 个 jar

com.dangdang:elastic-job-* 在 Maven Central 上还有，但被阿里云镜像拉黑（License 问题）。手动从 Central 下载：

1
2
3

mvn dependency:get -Dartifact=com.dangdang:elastic-job-lite-core:2.1.5
mvn dependency:get -Dartifact=com.dangdang:elastic-job-lite-spring:2.1.5
# ... 共 6 个

4.2 Oracle JDBC 12c

com.oracle:ojdbc8:12.2.0.1.0 因为 Oracle License 协议问题不在 Maven Central。下载后用 install-file 安装：

mvn install:install-file \
  -Dfile=ojdbc8.jar \
  -DgroupId=com.oracle \
  -DartifactId=ojdbc8 \
  -Dversion=12.2.0.1.0 \
  -Dpackaging=jar

4.3 swift-java-sdk 与 kaptcha

项目用了一个很老的 Swift Pass SDK 和 kaptcha 验证码。这些在 Maven Central 都搜不到，但 E:\nanwang\swift-java-sdk\ 和 E:\nanwang\kaptcha\ 目录里有现成的 jar。同样用 install-file 安装。

五、无用依赖处理

service-util/pom.xml 里有两段 com.sun.jna 依赖：

<dependency>
  <groupId>com.sun.jna</groupId>
  <artifactId>examples</artifactId>
  <version>1.0.0</version>
</dependency>

com.sun.jna:examples:1.0.0 在全球公共 Maven 仓库均不存在（1.0.0 版本就没发布过 examples），而且项目代码里没有任何 import com.sun.jna.example。直接注释掉。

模块编译状态汇总
图3：26 模块编译成功状态

编译验证

最终命令：

cd "/e/nanwang/smart-park-cloud - no jar"
export JAVA_HOME=/e/jdk
export PATH=$JAVA_HOME/bin:$PATH
mvn compile -U -T 4

26 个模块全部编译通过（总耗时 1分38秒）：

模块类别	数量	状态
父 POM	1	✅ SUCCESS
基础（util/model）	2	✅ SUCCESS
业务 API 模块	10	✅ SUCCESS
业务 Service	9	✅ SUCCESS
集成模块	2	✅ SUCCESS
框架	2	✅ SUCCESS
总计	26	✅ SUCCESS

关键路径备忘

用途	路径
项目根目录	`E:\nanwang\smart-park-cloud - no jar`
JDK	`E:\jdk`
Maven	`E:\maven363\apache-maven-3.6.3`
Maven 配置	`E:\maven363\apache-maven-3.6.3\conf\settings.xml`
Maven 备份	`E:\maven363\apache-maven-3.6.3\conf\settings.xml.bak2`
本地仓库（IDEA 使用的）	`F:\LocalWarehouse`
别人给的源仓库	`E:\nanwang\xxkj`

经验总结

教训 1：IDEA 的 Maven 配置在 .m2 之外

很多人以为 Maven 配置都在 ~/.m2/settings.xml，但 **IDEA 自带 Maven 时会用自己捆绑的 maven/conf/settings.xml**。找错配置改半天无效，浪费时间。先确认 File → Settings → Build → Maven 里 IDEA 实际用的 Maven home 路径。

教训 2：直接复制 jar 不等于安装

Maven 本地仓库不只是 jar 文件，还有 _remote.repositories、_maven.repositories、*.lastUpdated 等元数据文件。手动复制 jar 后必须用 mvn install:install-file 重新安装，让 Maven 生成正确的元数据。否则 Maven 会一直报”找不到”。

教训 3：阿里云镜像不是万能的

阿里云镜像默认拉黑了一些有 License 争议的包：

com.dangdang:elastic-job-*（GPL 协议争议）
com.oracle:ojdbc8（Oracle OTN 协议）
com.sun.jna:examples（根本不存在）

这些需要从 Maven Central 单独下载，或用 install-file 安装本地 jar。

教训 4：备份原配置永远是对的

settings.xml.bak2 这一字命名虽然丑，但比覆盖原配置好得多。后续遇到”线上环境跑得好好的，本地怎么都不通”的情况，至少能 diff 出”我改了什么”。

教训 5：先编译再启动

很多同事一上来就 mvn spring-boot:run，结果依赖问题、配置问题、环境问题全混在一起。先 mvn compile 把编译跑绿，再 mvn package -DskipTests 打 jar，最后才启动。问题分层定位，效率高 3 倍。

未完成事项

本地数据库搭建（需从虚拟机导出 SQL，或用项目内 Flyway 迁移脚本初始化）
Nacos 配置中心搭建（需在 Nacos 中导入各服务的配置）
Redis / RocketMQ 本地安装
各微服务联调测试

环境编译只是万里长征第一步，真正的考验是从空数据库到第一个 HTTP 接口调通——这个下一篇讲。

结语

接手停更 2 年的微服务项目，环境搭建往往是最消耗心力的一步。耐心分析、增量修复、保留备份是核心心法。下一步就是把 11 个数据库的 214 个 Flyway 迁移脚本跑起来，让服务真的能连上 DB。