主题
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-boot | tio-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-boot | 2.1.7 | 404 | 必须源码构建 |
nexus.io:tio-boot-admin-web | 2.1.6 | 404 | 必须源码构建 |
nexus.io:api-table | 1.6.1 | 404 | 必须源码构建 |
nexus.io:java-openai | 1.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 时服务端按依赖深度排序去重,网页项目详情页会直接写出顺序。最终一次执行的流水线:
| 顺序 | 项目 | 类型 | 结果 | 耗时 |
|---|---|---|---|---|
| 1 | tio-boot | 构建 | success | 12.9s |
| 2 | tio-boot-admin | 构建 | success | 5.4s |
| 3 | api-table | 构建 | success | 3.1s |
| 4 | java-openai | 构建 | success | 8.0s |
| 5 | java-mosskb-business | 构建 | success | 5.4s |
| 6 | mosskb-web | 应用 | success | 16.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_PSWD | PostgreSQL 密码 | 是 |
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 并全用绝对路径 |
| 服务器连不上开发机 5432 | pg_hba.conf 与 Windows 防火墙都只放行了旧网段,追加 192.168.31.0/24 |
my.txt 配置不生效 | 按进程工作目录加载,WorkingDirectory 必须等于发布目录 |
回滚 = 把项目 Git 指到上一个可用提交再执行(发布目录每次覆盖 jar,配置由命令生成)。需要保留历史产物时在发布命令里加一步带时间戳的 cp。多项目、公网暴露的更复杂场景见案例 03。