信创实战：openEuler24.03+JeecgBoot 3.8.3 后端部署全流程总结

🗒️ 本文档记录在 openEuler 24.03 环境下从零部署 JeecgBoot 3.8.3 后端服务的完整过程，包括所有遇到的错误、解决思路、具体命令及最终验证。已将yml配置成模板，可根据需要自行下载，下载地址已放置在文章末尾。（内容包括：yml模板，赋值脚本，更新脚本，README）

---

一、硬件与软件环境

项目	版本
操作系统	openEuler 24.03 (LTS-SP4)
内核	6.6.0-159.4.3.154.oe2403sp4.x86_64
CPU	Intel Xeon Gold 6210U
内存	建议 ≥ 4GB（实际测试使用 96GB）
JDK	17.0.11 (BiSheng)
Maven	3.6.3
PostgreSQL	15.6
Redis	7.2.5（宿主机或容器）
Docker	26.1.3（可选，未使用）
项目版本	JeecgBoot 3.8.3

---

二、源码准备与编译

2.1 获取源码

项目源码从 Gitee 镜像下载（因 GitHub 访问缓慢）：

bash

cd /tmp
wget https://gitee.com/jeecg/JeecgBoot/repository/archive/v3.8.3.zip
unzip v3.8.3.zip -d /tmp/jeecg-src
# 解压后目录结构为 /tmp/jeecg-src/JeecgBoot-v3.8.3/

2.2 首次编译失败 – 接口不兼容

❌ 错误：

text

[ERROR] /.../SysBaseApiImpl.java:[12,35] 找不到符号
  符号:   类 ISysBaseApi
  位置: 程序包 org.jeecg.common.system.api

📢 原因：

JeecgBoot 3.8.3 将通用接口移至 jeecg-boot-base-core 中的 CommonAPI，而 SysBaseApiImpl 仍实现旧的 ISysBaseApi。

✅解决办法：

修改 SysBaseApiImpl.java，实现 CommonAPI 接口：

bash

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

2.3 编译通过

从项目根目录执行完整构建：

bash

cd /data/JeecgBoot/jeecg-boot
mvn clean install -DskipTests

---

三、配置文件调整（application-dev.yml）

3.1 配置文件修改原则

在 JeecgBoot 部署过程中，application-dev.yml 的格式要求极为严格（缩进、空格、键值顺序）。强烈建议使用 yq 工具进行所有 YAML 修改，避免使用 sed 或 perl 直接替换文本，以免破坏 YAML 结构（如重复键、缩进错误、引号丢失等）。

❌ 错误示例（使用 sed 替换）

bash

# 容易导致 YAML 格式错误
sed -i 's/username: root/username: postgres/' application-dev.yml

❗ 问题：
如果原文件中有多个 username 或注释中包含相同字符串，可能误修改，且无法正确处理嵌套结构。

✅ 正确示例（使用 yq）

bash

yq eval '.spring.datasource.dynamic.datasource.master.username = "postgres"' -i application-dev.yml

⭐ 优势：

• 精确操作指定路径的键值，不误伤其他位置。
• 自动处理缩进和引号，保证 YAML 语法正确。
• 支持删除、添加、合并等复杂操作。

---

常用 yq 命令速查

操作	命令
修改字符串值	yq eval '.path.to.key = "new value"' -i file.yml
添加新键	yq eval '.path.to.newkey = "value"' -i file.yml
删除键	yq eval 'del(.path.to.key)' -i file.yml
合并两个 YAML 文件	yq eval-all 'select(fi==0) * select(fi==1)' file1.yml file2.yml
查看特定键值	yq eval '.path.to.key' file.yml

---

实际应用中典型修改示例

bash

# 1. 修改数据库连接
yq eval '.spring.datasource.dynamic.datasource.master.url = "jdbc:postgresql://127.0.0.1:5432/jeecg_boot?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai"' -i application-dev.yml
yq eval '.spring.datasource.dynamic.datasource.master.username = "postgres"' -i application-dev.yml
yq eval '.spring.datasource.dynamic.datasource.master.password = "postgres123"' -i application-dev.yml
yq eval '.spring.datasource.dynamic.datasource.master.driver-class-name = "org.postgresql.Driver"' -i application-dev.yml

# 2. 添加 primary 数据源
yq eval '.spring.datasource.dynamic.primary = "master"' -i application-dev.yml

# 3. 设置 Quartz 内存模式（删除 JDBC 相关配置）
yq eval '.spring.quartz.job-store-type = "memory"' -i application-dev.yml
yq eval 'del(.spring.quartz.jdbc)' -i application-dev.yml
yq eval 'del(.spring.quartz.properties)' -i application-dev.yml

# 4. 配置 Liteflow
yq eval '.liteflow.rule-source = "com.yomahub.liteflow.parser.sql.SQLXmlELParser"' -i application-dev.yml
yq eval '.liteflow.rule-source-ext-data = "{\"dataSourceName\":\"master\",\"applicationName\":\"jeecg-boot\",\"chainTableName\":\"airag_flow\"}"' -i application-dev.yml
yq eval '.liteflow.enable = true' -i application-dev.yml

---

💡 为什么 sed/perl 容易出错？

• YAML 对缩进敏感：sed 无法感知层级，可能破坏缩进。
• 特殊字符需要转义：如 &、*、: 等，手工替换容易遗漏。
• 多行字符串和注释：sed 行匹配可能误修改注释或非目标内容。
• 重复键问题：若文件中已有同名键，sed 替换可能产生重复，导致 YAML 解析失败（DuplicateKeyException）。

因此，在修改 YAML 文件时，始终优先使用 yq，它是专门为 YAML 设计的轻量级处理工具，能安全、精确地完成修改。

3.2 数据库切换（MySQL → PostgreSQL）

原始配置（默认 MySQL）：

yaml

spring:
  datasource:
    dynamic:
      datasource:
        master:
          url: jdbc:mysql://127.0.0.1:3306/jeecg-boot?...
          username: root
          password: root
          driver-class-name: com.mysql.cj.jdbc.Driver

修改后（PostgreSQL）：

yaml

spring:
  datasource:
    dynamic:
      primary: master
      datasource:
        master:
          url: jdbc:postgresql://127.0.0.1:5432/jeecg_boot?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
          username: postgres
          password: postgres123
          driver-class-name: org.postgresql.Driver

3.3 添加 primary: master（解决动态数据源找不到主数据源）

bash

yq eval '.spring.datasource.dynamic.primary = "master"' -i application-dev.yml

3.4 Quartz 配置 – 改为内存模式（避免建表）

原配置（JDBC 存储）：

yaml

spring:
  quartz:
    job-store-type: jdbc
    jdbc:
      initialize-schema: embedded
    properties:
      org.quartz.jobStore.class: org.springframework.scheduling.quartz.LocalDataSourceJobStore
      # ...

修改后（内存存储）：

yaml

spring:
  quartz:
    job-store-type: memory
    auto-startup: false

使用 yq 命令精确修改：

bash

yq eval '.spring.quartz.job-store-type = "memory"' -i application-dev.yml
yq eval 'del(.spring.quartz.jdbc)' -i application-dev.yml
yq eval 'del(.spring.quartz.properties)' -i application-dev.yml
yq eval '.spring.quartz.auto-startup = false' -i application-dev.yml

3.5 Liteflow 配置（AI 流程引擎）

因 AI 模块强依赖 Liteflow，需正确配置 SQL 解析器：

yaml

liteflow:
  enable: true
  rule-source: com.yomahub.liteflow.parser.sql.SQLXmlELParser
  rule-source-ext-data: '{"dataSourceName":"master","applicationName":"jeecg-boot","chainTableName":"airag_flow"}'

⚠️ 注意:
applicationName 和 chainTableName 必须定义。

---

四、数据库初始化

4.1 创建数据库及 AI 模块表

bash

sudo -u postgres psql -c "CREATE DATABASE jeecg_boot;"

创建 airag_flow 表（Liteflow 所需）：

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');

4.2 Quartz 表（可选，因使用内存模式未建表）

若采用 JDBC 存储，需执行 Quartz 提供的 tables_postgres.sql，但本方案使用内存模式，无需建表。

---

五、启动报错与解决

5.1 YAML 格式错误 – 重复键、缩进问题

❌ 错误：
DuplicateKeyException 或 ScannerException: mapping values are not allowed here

📢 原因：
多次手动追加配置导致 YAML 结构损坏。

✅ 解决：
使用 yq 工具精确修改，避免人为缩进错误。常用命令：

bash

yq eval 'del(.jeecg)' -i application-dev.yml   # 删除重复块
yq eval '.jeecg.file-view-domain = "http://localhost"' -i application-dev.yml

5.2 Liteflow – 缺少 chainTableName 或 applicationName

❌ 错误:
You did not define the applicationName property 或 You did not define the chainTableName property

✅ 解决：
在 rule-source-ext-data JSON 中补齐：

bash

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

5.3 Liteflow – 找不到数据源 dataSource

❌ 错误：
can not found liteflow config in dataSourceName [dataSource]

📢 原因：
Liteflow 默认查找 dataSource Bean，而动态数据源主数据源名为 master。

✅ 解决：
明确指定 dataSourceName: master（已包含在上述 JSON 中）。

5.4 Quartz – No local DataSource found

❌ 错误：
No local DataSource found for configuration - 'dataSource' property must be set on SchedulerFactoryBean

📢 原因：
即使设置 job-store-type: memory，Spring Boot 的 Quartz 自动配置仍尝试初始化 JDBC 存储，因为配置中残留了 jdbc 或 properties 块。

✅ 解决：
彻底删除 spring.quartz.jdbc 和 spring.quartz.properties 块，并添加命令行参数覆盖：

bash

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

5.5 动态数据源找不到主数据源

❌ 错误：
dynamic-datasource can not find primary datasource

✅ 解决：
添加 spring.datasource.dynamic.primary: master。

---

六、最终稳定运行配置

6.1 启动命令（后台运行）

bash

nohup java -jar jeecg-system-start-3.8.3.jar \
  --spring.profiles.active=dev \
  --spring.config.location=file:./application-dev.yml \
  --spring.quartz.job-store-type=memory \
  --spring.quartz.properties.org.quartz.jobStore.class=org.quartz.simpl.RAMJobStore \
  --spring.quartz.properties.org.quartz.threadPool.class=org.quartz.simpl.SimpleThreadPool \
  --spring.quartz.properties.org.quartz.threadPool.threadCount=10 \
  --spring.quartz.auto-startup=false \
  > startup.log 2>&1 &

6.2 验证输出

bash

# 进程与端口
ps aux | grep jeecg-system-start | grep -v grep
ss -tlnp | grep 8080
# 启动日志
grep "Started JeecgSystemApplication" startup.log
# 接口测试
curl -X POST http://localhost:8080/jeecg-boot/sys/login -H "Content-Type: application/json" -d '{"username":"admin","password":"123456"}'
curl -X GET http://localhost:8080/jeecg-boot/sys/randomImage/123456

预期输出：

• 进程存在，端口 LISTEN。
• 日志显示 Started JeecgSystemApplication in X seconds。
• 登录返回 {"success":false,"message":"验证码无效"...}（证明接口正常）。
• 验证码接口返回 base64 图片数据。

---

七、关键命令速查

用途	命令
编译项目	mvn clean install -DskipTests
修改 YAML	yq eval '.key = "value"' -i application-dev.yml
启动服务	java -jar ...（参数见上）
查看日志	tail -f startup.log
测试接口	curl -X POST ...

---

八、总结

通过上述步骤，成功在 openEuler 24.03 上部署了 JeecgBoot 3.8.3 后端，解决了模块依赖、YAML 格式、动态数据源、Quartz 和 Liteflow 配置等系列问题，最终服务稳定运行并可通过接口验证。

关键词：openEuler、JeecgBoot、PostgreSQL、Liteflow、Quartz、yq、内存模式、AI 模块。

🟢 成功运行：进程正常，端口监听正常，登录验证正常

yml模板下载地址：https://gitee.com/dboru/jeecg-config
内容包括：yml模板，赋值脚本，更新脚本，README。
（具体使用说明详见README.md）