跳至主要內容

应用构建

千桐科技2026/11/1大约 4 分钟安装部署

本页在构建机器执行，使用环境安装准备的 Java 17、Maven 3.9.x 和 Node.js 22.x。构建机器与运行服务器可以分开；已取得同版本 JAR 和前端产物时，直接进入 qOntology 服务部署。

一、获取同一版本源码

# 获取源码并进入项目目录
git clone https://gitee.com/qiantongtech/qOntology.git
cd qOntology

# 切换到实际发布版本，记录本次构建的提交号
git checkout '<发布标签或提交>'
git rev-parse HEAD

<发布标签或提交> 必须替换成实际发布版本。记录提交号，初始化 SQL、外置配置参考文件、后端和前端均从该版本取得。已有源码目录时进入该目录并核对版本，不必再次克隆。

# 为当前终端指定 Java 17 和构建工具路径
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH="$JAVA_HOME/bin:/opt/maven/bin:/opt/node22/bin:$PATH"

# 核对 Java、Maven、Node.js 和 npm 版本
java -version
mvn -version
node -v
npm -v

预期 Java 17、Maven 3.9.x、Node.js 22.x。前端依赖需要访问 npm 仓库，后端需要访问 POM 定义的 Maven 仓库。

二、构建后端

2.1、执行打包

在包含顶层 pom.xml 的 qOntology 源码根目录执行：

# 构建后端及其依赖模块，跳过 Docker 命令打印、镜像构建和推送
mvn clean package -pl qontology-server -am \
  -Ddocker.print.skip=true \
  -Ddocker.build.skip=true \
  -Ddocker.push.skip=true

-am 同时构建依赖模块。项目 POM 含镜像命令相关任务，因此原生部署显式跳过命令打印、镜像构建及推送；无需安装或登录 Docker。

如发布流程明确允许跳过测试执行，可使用以下命令；该结果只能说明打包成功，不代表测试通过：

# 仅在允许跳过测试执行时使用；仍跳过所有 Docker 相关任务
mvn clean package -pl qontology-server -am -DskipTests \
  -Ddocker.print.skip=true \
  -Ddocker.build.skip=true \
  -Ddocker.push.skip=true

遇到依赖下载或编译错误时先检查错误日志和发布版本，不直接改动依赖版本来绕过。

2.2、检查后端产物

# 确认 JAR 非空，并检查其中是否包含 Spring Boot 应用内容
test -s qontology-server/target/qontology-server.jar
jar tf qontology-server/target/qontology-server.jar | grep -E 'BOOT-INF/(classes|lib)' | head

部署产物为 qontology-server/target/qontology-server.jar。不要选择 .original、源码包或某个业务模块的普通 JAR。启动配置和 8097 端口在下一页显式覆盖，不依赖源码的开发端口。

三、构建前端

3.1、检查生产配置

进入 qontology-ui，编辑 .env.production.local。该文件用于本次生产构建覆盖，不需要修改公共环境文件：

cd qontology-ui

写入以下内容，替换服务器 IP 后保存：

VITE_APP_BASE_API=/prod-api/
VITE_APP_FILE_VIEW=/kkfileview
VITE_APP_AUTH_TYPE=local
VITE_APP_THIS_APP_URL=http://<服务器IP>:8897

本系列使用本地登录。当前前端仅在 VITE_APP_AUTH_TYPE=sso 时走单点登录；VITE_APP_SERVER_URL 和 VITE_APP_CLIENTID 属于 SSO 配置，不应把示例认证服务器地址当作 API 地址。需要 SSO 时另行配置真实认证服务和回调地址。

VITE_APP_FILE_VIEW=/kkfileview 使用浏览器当前站点的同源预览代理。前端环境变量在构建时写入产物，服务器地址或认证模式改变后需要重新构建；不在 VITE_* 变量中保存服务端密钥。

3.2、安装依赖与构建

当前核对的源码没有前端锁文件，使用：

# 安装项目依赖并构建生产环境前端
npm install
npm run build:prod

# 检查构建生成的前端入口文件
test -s dist/index.html

保留本次生成的锁文件及构建记录，方便复现。后续发布版本若提供有效 package-lock.json，可按该版本流程改用 npm ci。不要在无锁文件时直接执行 npm ci，也不需要全局安装 Vite。

产物为 qontology-ui/dist/，应整体交付。生产服务器用 Nginx 提供这些静态文件，不使用 npm run dev 或 Vite preview 作为正式入口。

四、整理部署文件

源文件或目录服务器位置说明
qontology-server/target/qontology-server.jar/opt/qontology/server/qontology-server.jar可执行后端 JAR
qontology-ui/dist/ 内全部文件/opt/qontology/web/index.html 直接位于 web 下
同版本初始化 SQL首次初始化使用的暂存目录不放入 Web 根目录
下一页编写的 deploy.yml/opt/qontology/config/deploy.yml原生部署覆盖配置

将 JAR 上传至服务器 ~/qontology-release/qontology-server.jar，将 dist 内部的文件上传至 ~/qontology-release/web/。下一页从这个暂存目录安装。

交付时记录发布提交、构建工具版本、是否执行测试以及文件校验值。在源码根目录可生成后端和前端入口校验值：

sha256sum qontology-server/target/qontology-server.jar qontology-ui/dist/index.html

不要直接执行仓库中的一键发布脚本来代替本页流程，它们可能包含镜像构建或推送动作。

下一步：qOntology 服务部署。

最近更新：