Skip to content

mosskb-web:含依赖构建的多模块应用 ​

案例概览 ​

MossKB 后端(tio-boot,JDK 21,Maven 多模块)部署到 192.168.31.97:10060,数据库留在开发机 PostgreSQL。难点不在应用本身,而在它依赖的一批 nexus.io:* 库没有全部发布到中央仓库:服务器上直接 mvn package 必然失败,必须先把这些库拆成构建项目在服务器上源码构建。

项值
应用仓库https://gitee.com/ppnt/java-mosskb.git @ main(多模块,取 mosskb-web)
目标服务器192.168.31.97(Ubuntu,原本只有 JDK 8,需补 JDK 21)
数据库开发机 192.168.31.225:5432/moss_kb(PostgreSQL,已有数据)
发布目录/srv/apps/mosskb-web,systemd 托管,端口 10060
最终流水线5 个构建项目 + 1 个应用项目全部 success,缓存热后整链约 51 秒

lib 与 app 的划分 ​

平台把项目分为构建项目(lib,产物 install 进服务器本地 Maven 仓库)与应用项目(app,打包并发布运行)。本案例共六个项目,依赖关系决定执行顺序:

项目 Key类型依赖产物
tio-boot构建—t-io 全家桶 2.1.7
tio-boot-admin构建tio-boottio-boot-admin 2.1.6
api-table构建—api-table 1.6.1
java-openai构建—java-openai 1.3.7(含 MossKB 补丁)
java-mosskb-business构建上面四个mosskb-business 1.0.4
mosskb-web应用java-mosskb-business发布到 /srv/apps/mosskb-web 并运行

两个设计要点:

  • 同一个仓库可以出现在两个项目里:java-mosskb 既做 business 构建项目又做 web 应用项目,各有独立的 /srv/deploy/workspaces/<key> 工作区,互不干扰。
  • 底层库必须选「构建项目」类型,否则上层项目的「依赖的构建项目」下拉里看不到它。

划分方式与依赖配置详见依赖构建。

依赖分析:哪些必须源码构建 ​

判定方法:查中央仓库(或镜像)有没有该版本的 pom,再看本机仓库里它是下载来的还是本地 install 的(_remote.repositories 里仓库号为空即本地安装):

bash
curl -sS -o /dev/null -w '%{http_code}\n' \
  https://maven.aliyun.com/repository/public/nexus/io/api-table/1.6.1/api-table-1.6.1.pom
依赖版本中央仓库结论
nexus.io:tio-boot2.1.7404必须源码构建
nexus.io:tio-boot-admin-web2.1.6404必须源码构建
nexus.io:api-table1.6.1404必须源码构建
nexus.io:java-openai1.3.7有,但缺 MossKB 需要的方法必须用打过补丁的源码构建
nexus.io:java-db / jfinal-aop—200直接下载即可

构建命令要点 ​

幂等安装 JDK 21 ​

服务器只有 JDK 8 且不在服务进程 PATH 里。把「装 JDK」写成构建项目的第一条命令(幂等),并统一用绝对路径,不依赖 PATH:

bash
set -e
JDK=/usr/java/jdk-21.0.2
if [ ! -x "$JDK/bin/java" ]; then
  mkdir -p /usr/java
  curl -fL --retry 3 -o /tmp/jdk21.tar.gz \
    https://repo.huaweicloud.com/openjdk/21.0.2/openjdk-21.0.2_linux-x64_bin.tar.gz
  tar -xzf /tmp/jdk21.tar.gz -C /usr/java && rm -f /tmp/jdk21.tar.gz
fi
"$JDK/bin/java" -version

统一 Maven 参数与本地仓库一致性 ​

所有构建项目统一 mvn -B clean install -DskipTests -Dgpg.skip=true -Dmaven.javadoc.skip=true:这些库的 pom 配了 GPG 签名与 javadoc 插件,服务器上没有签名密钥,不 skip 会在 install 阶段失败。产物全部进同一个 /root/.m2/repository,上层项目才能解析到。

版本对齐用属性覆盖而不是再建一个项目:tio-boot-admin 引用的 tio-boot 2.1.6 也不在中央仓库,构建时加 -Dtio-boot.version=2.1.7,与 java-mosskb 父 pom 的版本压平结果一致。

补丁随仓库走 ​

java-openai 缺的两个方法只在 java-mosskb 仓库里以补丁形式保存。构建项目里「下载补丁 → git apply → install」,补丁与应用永远同版本:

bash
curl -fsSL --retry 3 -o /tmp/java-openai.patch \
  https://gitee.com/ppnt/java-mosskb/raw/main/docs/customizations/2026-10-03/java-openai.patch
git apply /tmp/java-openai.patch

平台的 Git 准备每次都把工作区 reset 回 origin/main,所以补丁必须每次重新 apply;反过来这保证了「提交号 + 补丁」就是可复现的输入。

应用侧 -pl 不带 -am ​

bash
# business 由依赖项目先 install 到本地仓库,web 只编自己,
# 保证嵌入的必定是本次构建出来的 business jar。
mvn -B -pl mosskb-web package -Pproduction -DskipTests -Dgpg.skip=true -Dmaven.javadoc.skip=true

含依赖执行与失败阻断 ​

bash
deploy run mosskb-web --with-dependencies --wait --json

带 --with-dependencies 时服务端按依赖深度排序去重,网页项目详情页会直接写出顺序。最终一次执行的流水线:

顺序项目类型结果耗时
1tio-boot构建success12.9s
2tio-boot-admin构建success5.4s
3api-table构建success3.1s
4java-openai构建success8.0s
5java-mosskb-business构建success5.4s
6mosskb-web应用success16.4s

两条重要经验:

  • 依赖失败会阻断主项目:首次失败时平台报 dependency build java-mosskb-business failed; the main project was not executed,真正的编译错误在依赖那条 run 的日志里。排错要往上游 run 找,见运行生命周期与故障排查。
  • 首次构建慢是正常的:依赖要下载,tio-boot-admin 首跑 136.5s、二跑 5.4s。平台不做增量缓存,依赖项目每次重建,换来「不会拿到旧包」的确定性。

只想重跑上层时用 deploy run mosskb-web(不带 --with-dependencies),依赖的 jar 还在服务器本地仓库里。

发布与运行配置 ​

应用项目通过环境变量注入敏感配置,勾选 Secret 的变量在日志里被平台自动打码(实测回显为 jdbc.pswd=***):

变量用途Secret
DB_HOST开发机数据库地址 192.168.31.225否
DB_PSWDPostgreSQL 密码是
GITEE_API_KEY模型平台 Key是

发布命令把 jar 拷到 /srv/apps/mosskb-web,用环境变量生成 my.txt(JDBC 连接、端口等)与 secrets.txt,并 chmod 600。关键前提:tio-boot 的 EnvUtils 按进程工作目录加载 my.txt / secrets.txt,所以发布目录、配置目录、systemd WorkingDirectory 必须是同一个目录,否则配置像「没生效」。

健康检查轮询 http://127.0.0.1:10060/api/display/info 直到 200,失败时打印 systemd 状态与启动日志并 exit 1;另有一条运维命令供「单独执行」巡检(用法同案例 01,先 project get 再 --command-id)。

验证清单 ​

四项验证都不是「平台说成功」:

bash
# 1) 服务可达
curl -sS --compressed http://192.168.31.97:10060/api/display/info

# 2) 走数据库的登录链路(返回 JWT 说明库连接、表结构、种子数据都对)
curl -sS -X POST http://192.168.31.97:10060/api/user/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<管理员密码>"}'
sql
-- 3) 在开发机确认真的有来自服务器的连接
select client_addr, count(*) from pg_stat_activity
where datname = 'moss_kb' group by 1;
-- 192.168.31.97 | 10(JDBC 空闲连接)

第 4 项在平台上单独执行运维命令:systemd active、*:10060 监听、发布目录里 jar 与两个 0600 配置文件齐全。注意 /api/user/login 是方法名映射出来的路径,写成 /api/auth/login 得到的 401 来自拦截器,别误判成数据库不通。

经验与坑 ​

现象根因与修法
保存项目报「请填写工作目录」工作目录必填且不会按 Key 推导,显式填 /srv/deploy/workspaces/<key>
api-table POM missing未发布到中央仓库,建构建项目 mvn install
setThinking / streamOpenAi 找不到符号改动只存在于补丁,构建时下载并 git apply
tio-boot 2.1.6 解析失败属性覆盖 -Dtio-boot.version=2.1.7
doctor 说没有 java,历史上却构建成功过JDK 在 /usr/java 下但不在服务 PATH;装 JDK 21 并全用绝对路径
服务器连不上开发机 5432pg_hba.conf 与 Windows 防火墙都只放行了旧网段,追加 192.168.31.0/24
my.txt 配置不生效按进程工作目录加载,WorkingDirectory 必须等于发布目录

回滚 = 把项目 Git 指到上一个可用提交再执行(发布目录每次覆盖 jar,配置由命令生成)。需要保留历史产物时在发布命令里加一步带时间戳的 cp。多项目、公网暴露的更复杂场景见案例 03。