JeecgBoot3.8.3信创环境深度部署实战

本文档承接上一阶段总结，聚焦于 2026年8月16日至8月18日 的第二轮深度部署过程，涵盖从源码编译失败到最终稳定运行、配置模板化、备份与迁移、测试机验证的全链路实践。所有内容基于真实对话记录整理，保留原始问题、解决思路、具体命令及最终效果。由于工作原因导致疏忽，仅保存草稿未发表，现补发致歉，后续会根据工作情况逐步调整更新节奏和内容，敬请谅解！

---

一、实战目标

1.1 核心目标

在 openEuler 24.03 服务器上完成 JeecgBoot 3.8.3 后端的稳定部署，并实现：

• ✅ 启用 AI 模块（Liteflow + AI 聊天）

• ✅ 使用 PostgreSQL 替代 MySQL

• ✅ 配置文件脱敏并模板化，便于多环境复用

• ✅ 构建可一键部署的备份包（含所有依赖、JAR、配置、脚本）

• ✅ 在另一台测试机上验证部署包的可移植性

---

二、部署环境

项目	生产服务器（源）	测试服务器（目标）
操作系统	openEuler 24.03 LTS SP4	openEuler 24.03 LTS SP4（全新安装）
CPU	Intel Xeon	同左（x86_64）
内存	128GB	8GB（测试机）
内核	6.6.0-159.4.3.154.oe2403sp4.x86_64	同左
JDK	17.0.11 (BiSheng)	17.0.11（通过备份包安装）
PostgreSQL	15.6	15.6（RPM 安装）
Redis	7.2.5	7.2.5
Docker	26.1.3（未使用）	未安装
备份包版本	jeecg-full-20260818.tar.gz	同左

---

三、核心问题与解决路径

3.1 编译与依赖问题（延续上一阶段）

问题1：找不到 ISysBaseApi、SysUserDepartVO 等核心类

• 现象：jeecg-system-biz 模块编译时大量报错，提示程序包 org.jeecg.common.system.api 不存在。

• 原因分析：

  • JeecgBoot 3.8.3 已将通用接口移至 jeecg-boot-base-core 模块中的 CommonAPI。

  • pom.xml 中缺少对 jeecg-system-local-api 的正确依赖，且 javax.annotation-api 未引入（JDK 17 移除）。

• 解决思路：

  • 修改 SysBaseApiImpl.java，将 implements ISysBaseApi 改为 implements CommonAPI。

  • 在 pom.xml 中添加 javax.annotation-api 和 jeecg-system-local-api 依赖。

• 具体操作：

  bash

  # 修改 Java 文件
  perl -i -pe 's/implements ISysBaseApi/implements CommonAPI/g' SysBaseApiImpl.java
  perl -i -pe 's/import org\.jeecg\.common\.system\.api\.ISysBaseApi;/import org.jeecg.common.api.CommonAPI;/g' SysBaseApiImpl.java

  xml

  <!-- pom.xml 添加 -->
  <dependency>
      <groupId>javax.annotation</groupId>
      <artifactId>javax.annotation-api</artifactId>
      <version>1.3.2</version>
  </dependency>
  <dependency>
      <groupId>org.jeecgframework.boot3</groupId>
      <artifactId>jeecg-system-local-api</artifactId>
  </dependency>

• 预期效果：编译不再报错。

• 实际结果：编译通过，后续启动正常。

---

3.2 YAML 配置文件格式问题

问题2：多次手动修改导致 YAML 格式损坏

• 现象：启动时抛出 ScannerException: mapping values are not allowed here 或 DuplicateKeyException。

• 原因：使用 sed 直接替换文本，破坏了缩进和键值结构。

• 解决思路：放弃 sed，改用专用 YAML 工具 yq 进行所有修改。

• 具体操作：

  bash

  # 安装 yq
  wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
  chmod +x /usr/local/bin/yq
  
  # 修改数据库密码
  yq eval '.spring.datasource.dynamic.datasource.master.password = "postgres123"' -i application-dev.yml
  
  # 添加 primary 数据源
  yq eval '.spring.datasource.dynamic.primary = "master"' -i application-dev.yml
  
  # 删除 Quartz JDBC 配置
  yq eval 'del(.spring.quartz.jdbc)' -i application-dev.yml

• 预期效果：YAML 格式始终正确。

• 实际结果：后续所有 YAML 操作均使用 yq，再无格式错误。

---

3.3 Quartz 定时任务配置

问题3：Quartz 报错 No local DataSource found

• 现象：启动失败，提示 SchedulerConfigException: No local DataSource found for configuration - 'dataSource' property must be set。

• 原因：Quartz 默认使用 JDBC 存储，需要数据库表，但配置不完整或表不存在。

• 解决思路：改为内存模式（RAMJobStore），避免数据库依赖。

• 具体操作：

  • 在 application-dev.yml 中设置 spring.quartz.job-store-type: memory。

  • 删除 spring.quartz.jdbc 和 spring.quartz.properties 块。

  • 启动时添加参数：

    bash

    --spring.quartz.job-store-type=memory \
    --spring.quartz.properties.org.quartz.jobStore.class=org.quartz.simpl.RAMJobStore \
    --spring.quartz.auto-startup=false

• 预期效果：Quartz 使用内存存储，无需建表。

• 实际结果：Quartz 成功初始化，应用正常启动。

---

3.4 Liteflow（AI 模块）配置

问题4：Liteflow 报错 You did not define the applicationName property

• 现象：启动时 Liteflow 抛出 ELSQLException，提示缺少 applicationName 和 chainTableName。

• 原因：Liteflow 的 rule-source-ext-data 中未指定这两个必要字段。

• 解决思路：在 JSON 扩展数据中补齐 applicationName 和 chainTableName，并确保 airag_flow 表存在且包含示例数据。

• 具体操作：

  bash

  yq eval '.liteflow.rule-source-ext-data = "{\"dataSourceName\":\"master\",\"applicationName\":\"jeecg-boot\",\"chainTableName\":\"airag_flow\"}"' -i application-dev.yml

  sql

  CREATE TABLE airag_flow (
      id VARCHAR(36) PRIMARY KEY,
      application_name VARCHAR(255),
      chain_name VARCHAR(255),
      el_data TEXT,
      status VARCHAR(20) DEFAULT 'enable',
      create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  );
  INSERT INTO airag_flow (id, application_name, chain_name, el_data, status)
  VALUES ('1', 'jeecg-boot', 'default', 'THEN(start, end)', 'enable');

• 预期效果：Liteflow 成功加载流程定义。

• 实际结果：AI 模块正常启用，流程相关接口可用。

---

3.5 配置文件脱敏与模板化

问题5：配置文件包含明文密码，不适合公开分享

• 解决思路：只替换密码和用户名，保留所有 IP、端口、邮箱等默认值不变。使用 {{VAR}} 占位符，配合 envsubst 生成最终配置。

• 具体操作：

  • 从原始配置复制模板：

    bash

    cp application-dev.yml.original application-dev-template.yml
    sed -i 's/password: postgres123/password: {{DB_PASSWORD}}/g' application-dev-template.yml
    sed -i 's/password: jeecg1314/password: {{JM_PASSWORD}}/g' application-dev-template.yml
    sed -i 's/username: postgres/username: {{DB_USER}}/g' application-dev-template.yml
    sed -i 's/username: jeecg/username: {{JM_USER}}/g' application-dev-template.yml
    # AI-RAG 部分单独处理
    sed -i '/ai-rag:/,/^[^ ]/ s/user: postgres/user: {{AI_DB_USER}}/' application-dev-template.yml
    sed -i '/ai-rag:/,/^[^ ]/ s/password: postgres/password: {{AI_DB_PASSWORD}}/' application-dev-template.yml

  • 创建 env.sh 存放默认值：

    bash

    export DB_PASSWORD="postgres123"
    export JM_PASSWORD="jeecg1314"
    export DB_USER="postgres"
    export JM_USER="jeecg"
    export AI_DB_USER="postgres"
    export AI_DB_PASSWORD="postgres"

  • 创建 generate-config.sh：

    bash

    cat application-dev-template.yml | sed -E 's/\{\{([A-Z_]+)\}\}/\$\1/g' | envsubst > application-dev.yml

• 预期效果：敏感信息被占位符替代，可安全上传至 Gitee。

• 实际结果：模板与原始配置 diff 无差异，脱敏成功。

---

3.6 备份包制作与传输

问题6：如何制作可离线部署的完整备份？

• 解决思路：

  • 收集所有系统依赖 RPM 包（JDK17、PostgreSQL、Redis、Nginx、Maven、Git 等）。

  • 备份 JAR 包、配置模板、部署脚本、Nginx 配置文件。

  • 编写一键安装/恢复脚本（含 JDK 切换、数据库初始化、建表、启动服务）。

  • 打包为 jeecg-full-$(date +%Y%m%d).tar.gz。

• 具体操作（生产服务器）：

  bash

  mkdir -p /data/backup/rpms
  dnf download $(dnf repoquery --installed | grep -E "java-17|postgresql|redis|nginx|git|maven") --destdir=/data/backup/rpms/
  cp /usr/local/bin/yq /data/backup/rpms/
  cp /data/jeecg-boot-3.8.3-stable-20260817/jeecg-system-start-3.8.3.jar /data/backup/
  cp /etc/nginx/conf.d/jeecg.conf /data/backup/nginx-jeecg.conf
  # 创建 01-06 分步脚本（见下文）
  cd /data
  tar -czf jeecg-full-20260818.tar.gz backup/

• 分步脚本摘要：

  • 01-install-deps.sh：从本地 RPM 或在线源安装依赖。

  • 02-setup-java.sh：切换默认 Java 为 17。

  • 03-init-db.sh：初始化 PostgreSQL，创建数据库和 airag_flow 表。

  • 04-start-redis.sh：启动并启用 Redis。

  • 05-deploy-app.sh：复制 JAR、生成配置、启动后端。

  • 06-setup-nginx.sh：恢复 Nginx 反向代理配置。

• 传输到本地 F 盘（Windows PowerShell）：

  powershell

  scp root@IP:/data/jeecg-full-20260818.tar.gz F:\

• 预期效果：新服务器解压后执行脚本即可完成完整部署。

• 实际结果：在测试机成功恢复环境并启动服务。

---

3.8 测试机一键部署验证

问题8：测试机原系统存在 PagePlug 干扰

• 现象：访问 8080 端口显示 PagePlug 页面而非 JeecgBoot。

• 原因：测试机之前运行过 PagePlug Docker 容器，占用了端口或代理。

• 解决：清理 Docker 容器和镜像，停止旧服务。

  bash

  docker stop $(docker ps -aq) 2>/dev/null
  docker rm $(docker ps -aq) 2>/dev/null
  docker rmi $(docker images -q) 2>/dev/null
  systemctl stop nginx
  pkill -f jeecg-system-start

• 预期效果：8080 端口仅由 JeecgBoot 使用。

• 实际结果：清理后 JeecgBoot 正常响应。

---

四、我的观点与策略

阶段	观点	依据
初始	使用最新版 3.8.3，启用 AI 模块	功能完整，符合未来需求
遇到编译困难	不轻易降级，死磕依赖问题	AI 模块是核心亮点，放弃可惜
配置管理	坚持配置外置、模板化、变量化	便于多环境部署和版本控制
备份策略	制作全量离线备份包	应对内网环境，实现“解压即用”
文档记录	每一步都记录命令和结果	为后续复盘和分享做准备

---

五、最终状态总结

项目	状态	说明
生产服务器后端	✅ 稳定运行	进程持续运行，Swagger 可访问
AI 模块	✅ 已启用	Liteflow 成功加载，airag_flow 表存在
配置模板	✅ 已脱敏并上传 Gitee	含 MIT 许可证，可公开
备份包	✅ 已制作并下载本地	包含所有依赖和脚本，测试机恢复成功
测试机部署	✅ 成功	通过备份包一键部署，服务正常启动
文章准备	✅ 完成 CSDN 和知乎版本	分别面向技术实操和观点分享

---

六、关键命令速查

bash

# 查看后端进程
ps aux | grep jeecg-system-start | grep -v grep

# 检查端口监听
ss -tlnp | grep 8080

# 测试接口
curl -I http://localhost:8080/jeecg-boot/doc.html

# 修改 YAML（推荐 yq）
yq eval '.path.to.key = "value"' -i file.yml

# 生成配置（模板化）
cat template.yml | sed -E 's/\{\{([A-Z_]+)\}\}/\$\1/g' | envsubst > config.yml

# 打包备份
tar -czf jeecg-full-$(date +%Y%m%d).tar.gz backup/

# 传输备份
scp jeecg-full-*.tar.gz root@目标IP:/root/

---

七、经验与教训

1. 工具选型至关重要：yq 替代 sed 处理 YAML，避免了 90% 的格式错误。

2. 环境隔离：使用 envsubst 实现配置模板化，环境差异只需修改 env.sh。

3. 备份包策略：将系统依赖、JAR、脚本、配置统一打包，新服务器部署时间从 2 天缩短至 20 分钟。

4. 渐进式验证：先在宿主机编译运行，再制作备份包，最后在测试机验证，确保每一步可控。

5. 文档驱动：记录每一条命令和报错，后续复盘和写作时极大节省时间。

---

八、后续建议

• 若需要前端部署，可参考官方 Vue3 构建方案，同样使用 Nginx 代理。

• 建议将备份包存放在内网仓库，供后续服务器批量部署。

• 若 AI 模块后续升级，可只更新 JAR 包和 airag_flow 表结构，无需重新部署环境。