微服务部署

四节点私有化部署手册（一屏通读，用右侧「本页目录」跳转）。推荐 OS：Ubuntu 22.04/24.04 LTS 或 Rocky Linux 9（交付包脚本按 Rocky/RHEL 系编写，Ubuntu 需将 dnf/firewalld 步骤改为 apt/ufw，或沿用交付包时优先 Rocky 9）。主路径对齐 ruoyi-office-ms-deploy。完成后看上线文档。

00 部署方案

适用场景

需要按模块独立发布 / 扩缩，具备 ≥4 台主机。不适合单机快速上线（用单体部署）。

节点职责

节点	职责
ro-db	MySQL 8
ro-mid	Nacos、Redis；可选 XXL-Job / RocketMQ / IoT（TDengine、EMQX）
ro-app	Nginx、gateway、各 `*-server`
ro-ci	Jenkins（可选）

资源基线

节点	最低	全量参考
ro-db / ro-mid	4C8G	4C8G
ro-app	8C16G（裁剪）	10C28G+
ro-ci	4C8G	6C12G

前置检查单

[ ] 4 台 Ubuntu 22.04/24.04 或 Rocky Linux 9（交付包默认 Rocky/RHEL 9 命令；Ubuntu 自行对应包管理器/防火墙）；规格不低于上文资源基线
[ ] 四机私网互通；已规划静态 IP：<RO_DB_IP> <RO_MID_IP> <RO_APP_IP> <RO_CI_IP>
[ ] 已填写 inventory（从交付包 inventory.example.md 复制）
[ ] 可访问 ruoyi-office-db/dump/latest 或已拿到 sql/ready/*.sql
[ ] 运维机可 SSH；已装 rsync/scp
[ ] 禁止在 VMware/Hyper-V 宿主机再开 Docker Desktop（业务 Docker 只装在 Linux 节点内）

密钥与 inventory

bash

cd /path/to/ruoyi-office-ms-deploy
cp .env.example .secrets.env
cp inventory.example.md inventory.md

.secrets.env 是各节点 /data/compose/.env 的唯一真相源。

同步交付包

bash

PACK=/path/to/ruoyi-office-ms-deploy
for h in <RO_DB_IP> <RO_MID_IP> <RO_APP_IP> <RO_CI_IP>; do
  rsync -az --delete --exclude '.git' "$PACK/" "<SSH_USER>@${h}:/tmp/ruoyi-office-ms-deploy/"
done

各节点安装（角色不同）：

bash

sudo bash /tmp/ruoyi-office-ms-deploy/scripts/install-pack-to-node.sh \
  /tmp/ruoyi-office-ms-deploy db
sudo cp /tmp/ruoyi-office-ms-deploy/.secrets.env /data/compose/.env

mid / app / ci 同理更换角色参数。

Bootstrap（Docker + 防火墙）

bash

sudo bash /data/deploy/ruoyi-office-ms-deploy/scripts/bootstrap.sh db   # on ro-db
sudo bash /data/deploy/ruoyi-office-ms-deploy/scripts/bootstrap.sh mid
sudo bash /data/deploy/ruoyi-office-ms-deploy/scripts/bootstrap.sh app
sudo bash /data/deploy/ruoyi-office-ms-deploy/scripts/bootstrap.sh ci

检查：docker --version、docker compose version、firewall-cmd --list-all（应含 PRIVATE_CIDR rich rules）。

节点目录约定

路径	用途
`/data/deploy/ruoyi-office-ms-deploy`	交付包
`/data/compose`	当前角色 compose + `.env`
`/data/mysql`	MySQL 数据
`/data/redis` `/data/nacos`	中间件数据
`/data/nginx`	站点与证书
`/data/app/jars`	回滚用 jar

准备 SQL

bash

cd /path/to/ruoyi-office-ms-deploy
bash scripts/prepare-sql.sh /path/to/ruoyi-office-db/dump/latest
ls -lh sql/ready/schema.sql sql/ready/static_data.sql

将 sql/ready 同步到 ro-db 上的交付包路径。Nacos 不需要导入 MySQL schema（本方案 standalone）。

启动 MySQL 并导库（ro-db）

bash

cd /data/compose
sudo docker compose --env-file .env up -d
sudo docker exec mysql mysqladmin ping -uroot -p"$MYSQL_ROOT_PASSWORD"

sudo bash /data/deploy/ruoyi-office-ms-deploy/scripts/import-db.sh \
  /data/deploy/ruoyi-office-ms-deploy/sql/ready/schema.sql \
  /data/deploy/ruoyi-office-ms-deploy/sql/ready/static_data.sql

出口：打印表数量 ≥ 600（以当次 dump 为准）。

启动 Redis + Nacos（ro-mid）

bash

cd /data/compose
sudo bash /data/deploy/ruoyi-office-ms-deploy/scripts/render-redis-conf.sh
sudo docker compose --env-file .env up -d
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8848/nacos/

预期：Nacos 控制台可访问（HTTP 200 或跳转页）。

渲染并发布 Nacos（必做）

避免演示 IP/密码残留：

bash

cd /data/deploy/ruoyi-office-ms-deploy
sudo bash scripts/render-nacos-from-env.sh
sudo bash scripts/publish-nacos.sh

出口：namespace prod 存在 system-server-prod.yaml 等配置。

生产必核配置

项	要求
BPM 通知	`bpm-server-prod.yaml` → `yudao.bpm.notification.default-type: mq`（禁止微服务用 `local`）
JDBC / Redis	IP 为现场 `<RO_DB_IP>` / `<RO_MID_IP>`
演示开关	交付前按合同开启 captcha / api-encrypt；`yudao.demo: false`（见上线文档）

可选中间件扩展（非必须）

主路径只需 MySQL + Redis + Nacos。下列按合同与模块启用，缺省不阻塞登录验收。

XXL-Job（定时任务）

与单体相同原则：独立库 xxl_job + Admin（建议挂 ro-mid 或 ro-ci，端口 127.0.0.1:9090）+ 各业务服务 / infra 的 xxl.job.admin.addresses 指向可达地址。

bash

# 在可连业务 MySQL 的机器上
mysql -h <RO_DB_IP> -uroot -p < xxl_job_schema.sql
mysql -h <RO_DB_IP> -uroot -p < xxl_job_init_all.sql   # 或 xxl_job_init_oa.sql

Nacos 中多数 *-server-prod.yaml 已有：

yaml

xxl:
  job:
    admin:
      addresses: http://<XXL_JOB_HOST>:9090/xxl-job-admin

现场把 127.0.0.1 改成 XXL-Job 所在节点 IP（或 render 脚本覆盖），并设 xxl.job.enabled: true（若配置项存在）。Admin 勿对公网；改默认 admin/123456。详步骤：Docker 部署 XXL-Job。

RocketMQ（消息队列）

用途：部分模块事件总线、与 MQ 相关的异步能力。
BPM 跨服务状态回写本方案主路径用 Redis Stream（notification.default-type: mq），不强制先装 RocketMQ 才能跑通审批。
若合同要求 RocketMQ：单独规划 broker/NameServer（常放 ro-mid），并在 Nacos 中填写 127.0.0.1:9876 一类地址为现场 IP；资源另计。

IoT：TDengine + EMQX

仅启用 IoT 模块时：

bash

# 在 ro-mid
cd /data/compose
sudo docker compose -f docker-compose.yml -f docker-compose.iot.yml --env-file .env up -d

再启动 iot-server（full profile）。时序库初始化脚本按现场 IoT 方案另行提供。端口仅私网。

对象存储 / OnlyOffice / Jenkins

组件	说明
OSS / MinIO / 本地盘	管理端「文件配置」；见上线文档 · 存储
OnlyOffice	可选；反代须含 `/onlyoffice/`、`/cache/`、`/coauthoring/`
Jenkins	可选 CI；见 Jenkins 流水线
监控（SkyWalking / Boot Admin 等）	合同单列；不在本手册主路径

资源提示

启用 XXL-Job + IoT + OO + Jenkins 同机时，为 ro-mid / 单机额外预留内存与磁盘；优先保证 MySQL / Redis / Nacos / 业务 JVM，再叠加可选组件。

准备应用镜像（二选一）

路径 A：离线 jar

将云构建产物放到 ro-app：

text

/data/app/jars/*.jar

bash

sudo bash /data/deploy/ruoyi-office-ms-deploy/scripts/build-images-from-jars.sh

构建后端时使用 -P cloud。镜像名需与 compose 一致，例如 yudao-gateway:latest、yudao-module-system-server:latest。

路径 B：Jenkins

ro-ci：cd /data/compose && sudo docker compose --env-file .env up -d
按交付包 jenkins/README.md 或文档站 Jenkins 流水线配置 Job
构建后 scripts/sync-images.sh 同步到 ro-app

部署前端（ro-app）

将 web-antd 生产构建放到：

text

/data/nginx/html/web/

确认存在 index.html。按需改 Nginx server_name。客户构建务必关闭演示开关（上线文档）。

启动应用栈（建议先 P0/P1）

bash

cd /data/compose
sudo docker compose --profile p1 --env-file .env up -d system
sudo docker compose --profile p1 --env-file .env up -d infra bpm oa gateway nginx

全量（合同要求时）：

bash

sudo docker compose --profile p1 --profile full --env-file .env up -d

注意 ro-app 内存基线；全量稳态约 15–20GB Java 堆外占用，建议 ≥28GB。

关键环境变量（阻断项）

项	说明
`SPRING_CLOUD_NACOS_DISCOVERY_IP`	设为 `<RO_APP_IP>`，端口勿只绑 `127.0.0.1`
Gateway	不要剥离 `/admin-api` 前缀
健康检查	业务服务多为 `/admin/actuator/health`；gateway 为 `/actuator/health`

冒烟

bash

curl -s http://127.0.0.1:48080/actuator/health
curl -s -X POST "http://127.0.0.1/admin-api/system/auth/login" \
  -H "Content-Type: application/json" -H "tenant-id: 1" \
  -d '{"username":"admin","password":"admin123"}'

期望：code 为 0，返回 accessToken。浏览器打开 http://<RO_APP_IP>/web/。

Nginx 要点

交付包安装时已将 conf 复制到 /data/nginx/conf/conf.d/。核心：

/web/ → 静态目录 /data/nginx/html/web
/admin-api/ → gateway:48080（或本机映射端口），保留 /admin-api 前缀
对外仅 80/443

bash

sudo docker exec nginx nginx -t
sudo docker exec nginx nginx -s reload

验收勾选（摘要）

基础设施

[ ] 四机 Docker / firewalld 正常
[ ] 仅 ro-app 80/443 对用户可达；3306/6379/8848/8080 等仅私网

数据与中间件

[ ] 表数量达标并已记录
[ ] Nacos prod 配置已 render + publish；抽查 JDBC IP
[ ] BPM notification.default-type: mq
[ ] （若合同有）XXL-Job Admin 可达、执行器在线、独立库 xxl_job 已初始化

应用

[ ] gateway / system 等目标 profile 健康
[ ] http://<RO_APP_IP>/web/ 可登录，code=0
[ ] 经 Nginx 的 /admin-api/.../login 成功

上线后必做

修改 admin 密码
按上线文档关闭演示项、配置验证码与品牌
backup.sh cron
归档 inventory.md + 密封 .secrets.env

完整勾选可参考交付包 docs/04-验收清单.md 与文档站上线验收清单。

来自交付包实操手册 §10 与内部演示环境「关键修复」归档。

现象	处理
登录提示 `No static resource admin-api/...`	Gateway 镜像/路由异常；用已知良好 gateway jar 重建并 `compose up -d gateway`；确认未错误剥离 `/admin-api`
502 Bad Gateway	等 gateway healthy；`docker logs gateway-server`
服务注册了但调不通	端口勿只绑 `127.0.0.1`；检查 `DISCOVERY_IP=<RO_APP_IP>`
连不上库 / Redis	Nacos YAML 是否已 render；firewalld `PRIVATE_CIDR`
健康检查失败	业务：`/admin/actuator/health`；gateway：`/actuator/health`
流程结束但业务单仍「审批中」	BPM 仍为 `local` → 改为 `mq` 并确认 Redis Stream
Gateway 503	Nacos 中下游实例是否 UP；超时与负载均衡
ro-app OOM	裁剪 profile 或升配 ≥28GB；可暂停 ro-ci 腾内存
宿主机 Docker Desktop 异常	生产路径只在 Linux 业务节点内跑 Docker；关掉宿主机 Docker Desktop
Jenkins 子 Job 死锁	独立 Job + executors ≥ 2；见 Jenkins 手册

运维速查

bash

sudo bash /data/deploy/ruoyi-office-ms-deploy/scripts/health.sh
cd /data/compose && sudo docker compose --env-file .env ps

无 ruoyi-office-ms-deploy 交付包、自行用多 JAR + Nacos 部署时参考。主路径仍推荐 Compose 交付包。

构建

bash

cd ~/workspace/ruoyi-office
mvn clean package "-Dmaven.test.skip=true" "-Dskip.repackage=true" -Pcloud

Nacos

各服务通过配置中心连接 MySQL/Redis；公共配置保持一致。环境变量可覆盖：

bash

export SPRING_CLOUD_NACOS_SERVER_ADDR=<RO_MID_IP>:8848
export SPRING_CLOUD_NACOS_DISCOVERY_IP=<本机可达IP>

启动顺序（经验）

Nacos、Redis、MySQL 已就绪
gateway
system-server、infra-server
bpm-server 及其他业务
前端 + Nginx 将 /admin-api 反代到 gateway

BPM 通知（强制）

yaml

yudao:
  bpm:
    notification:
      default-type: mq   # 微服务禁止 local

Nginx

proxy_pass 指向 gateway；不要改写掉 /admin-api 前缀。验证与故障见 04、05。

更细的端口表与启停脚本示例见历史页（已 stub）：原《微服务部署指南》内容已收敛到本手册主路径；需要脚本模板时可从客户交付包复制。

微服务部署 ​

00 部署方案 ​

适用场景 ​

节点职责 ​

资源基线 ​

前置检查单 ​

密钥与 inventory ​

同步交付包 ​

Bootstrap（Docker + 防火墙） ​

节点目录约定 ​

准备 SQL ​

启动 MySQL 并导库（ro-db） ​

启动 Redis + Nacos（ro-mid） ​

渲染并发布 Nacos（必做） ​

生产必核配置 ​

可选中间件扩展（非必须） ​

XXL-Job（定时任务） ​

RocketMQ（消息队列） ​

IoT：TDengine + EMQX ​

对象存储 / OnlyOffice / Jenkins ​

资源提示 ​

准备应用镜像（二选一） ​

路径 A：离线 jar ​

路径 B：Jenkins ​

部署前端（ro-app） ​

启动应用栈（建议先 P0/P1） ​

关键环境变量（阻断项） ​

冒烟 ​

Nginx 要点 ​

验收勾选（摘要） ​

基础设施 ​

数据与中间件 ​

应用 ​

上线后必做 ​

运维速查 ​

构建 ​

Nacos ​

启动顺序（经验） ​

BPM 通知（强制） ​

Nginx ​

微服务部署

00 部署方案

适用场景

节点职责

资源基线

前置检查单

密钥与 inventory

同步交付包

Bootstrap（Docker + 防火墙）

节点目录约定

准备 SQL

启动 MySQL 并导库（ro-db）

启动 Redis + Nacos（ro-mid）

渲染并发布 Nacos（必做）

生产必核配置

可选中间件扩展（非必须）

XXL-Job（定时任务）

RocketMQ（消息队列）

IoT：TDengine + EMQX

对象存储 / OnlyOffice / Jenkins

资源提示

准备应用镜像（二选一）

路径 A：离线 jar

路径 B：Jenkins

部署前端（ro-app）

启动应用栈（建议先 P0/P1）

关键环境变量（阻断项）

冒烟

Nginx 要点

验收勾选（摘要）

基础设施

数据与中间件

应用

上线后必做

运维速查

构建

Nacos

启动顺序（经验）

BPM 通知（强制）

Nginx