微服务部署指南

本文档适用于微服务（Cloud）模式部署。假设 MySQL、Redis、Nacos 等中间件已就绪。
微服务模式下，各业务模块独立打包为 JAR，通过 Nacos 注册发现，由 API Gateway 统一对外暴露接口。

一、架构总览

                                    ┌─────────────────────────────┐
                                    │         Nacos 注册中心       │
                                    │    服务注册 / 配置管理        │
                                    └──────────┬──────────────────┘
                                               │ 注册 & 发现
                           ┌───────────────────┼───────────────────┐
                           │                   │                   │
                  ┌────────▼───────┐  ┌────────▼───────┐  ┌───────▼────────┐
    浏览器 ──────►│  Nginx (:80)   │  │                │  │                │
                  │  /web → 前端    │  │                │  │                │
                  │  /admin-api →  │  │                │  │                │
                  │    Gateway     │  │                │  │                │
                  └───────┬────────┘  │                │  │                │
                          │           │                │  │                │
                  ┌───────▼────────┐  │                │  │                │
                  │  Gateway       │  │  system-server │  │  infra-server  │
                  │  (:48080)      │──│  (:48081)      │  │  (:48082)      │
                  │  路由 & 鉴权    │  │                │  │                │
                  └───────┬────────┘  └────────────────┘  └────────────────┘
                          │
          ┌───────┬───────┼───────┬───────┬───────┬───────┐
          │       │       │       │       │       │       │
      bpm-server  │  report-server │  pay-server   │   ...更多服务
      (:48083)    │  (:48084)      │  (:48085)     │
                  │                │               │
             oa-server        crm-server      erp-server
             (:48101)         (:48089)        (:48088)

二、服务清单与端口

服务名称	服务标识	端口	说明
API 网关	gateway-server	48080	Spring Cloud Gateway，统一入口
系统服务	system-server	48081	用户、角色、菜单、权限、租户
基础设施服务	infra-server	48082	文件、代码生成、配置、日志、WebSocket
工作流服务	bpm-server	48083	Flowable 工作流引擎
报表服务	report-server	48084	积木报表
支付服务	pay-server	48085	支付渠道、退款
公众号服务	mp-server	48086	微信公众号管理
会员服务	member-server	48087	C端会员体系
ERP 服务	erp-server	48088	采购、销售、库存、财务
CRM 服务	crm-server	48089	线索、客户、商机、合同
AI 服务	ai-server	48090	大模型对话、知识库
IoT 服务	iot-server	48091	物联网设备管理
商城-商品	product-server	48100	商品 SPU/SKU
OA 服务	oa-server	48101	协同办公
商城-交易	trade-server	48102	订单、售后
商城-统计	statistics-server	48103	数据统计
HRM 服务	hrm-server	48101	人力资源管理
资产服务	asset-server	48101	资产管理
仓储服务	wms-server	48101	仓储管理

⚠️ 部分服务默认端口相同（48101），实际部署时请根据需要修改端口避免冲突，或部署在不同服务器上。

三、构建

3.1 微服务模式构建（全量）

bash

# 在项目根目录执行，构建所有模块
mvn clean package -Dmaven.test.skip=true

默认激活 cloud profile，skip.repackage=false，每个 -server 子模块都会打出可执行的 Fat JAR。

3.2 构建指定模块

bash

# 只构建网关 + 系统服务 + 基础设施服务（最小可用集）
mvn clean package -Dmaven.test.skip=true \
    -pl yudao-gateway,yudao-module-system/yudao-module-system-server,yudao-module-infra/yudao-module-infra-server \
    -am

3.3 构建产物位置

yudao-gateway/target/yudao-gateway.jar
yudao-module-system/yudao-module-system-server/target/yudao-module-system-server.jar
yudao-module-infra/yudao-module-infra-server/target/yudao-module-infra-server.jar
yudao-module-bpm/yudao-module-bpm-server/target/yudao-module-bpm-server.jar
yudao-module-oa/yudao-module-oa-server/target/yudao-module-oa-server.jar
...（其他模块同理）

3.4 前端构建

bash

cd ruoyi-office-vben

pnpm install
pnpm -r --filter "./packages/**" --filter "./internal/**" build

cd apps/web-antd
pnpm build
# 产物：apps/web-antd/dist/

四、Nacos 配置

微服务模式依赖 Nacos 作为注册中心和配置中心。

4.1 各服务连接 Nacos

每个 -server 模块的 application-prod.yaml（或通过环境变量覆盖）需配置：

yaml

spring:
  cloud:
    nacos:
      server-addr: 你的Nacos地址:8848
      username: nacos
      password: nacos密码
      discovery:
        namespace: prod          # 生产命名空间
        group: DEFAULT_GROUP
      config:
        namespace: prod
        group: DEFAULT_GROUP

4.2 环境变量覆盖（推荐）

启动时通过环境变量传入，无需修改配置文件：

bash

java -jar xxx-server.jar \
    --spring.profiles.active=prod \
    --spring.cloud.nacos.server-addr=192.168.30.100:8848 \
    --spring.cloud.nacos.discovery.namespace=prod \
    --spring.cloud.nacos.config.namespace=prod

4.3 Nacos 中的配置文件

在 Nacos 控制台 → 配置管理中，为各服务创建对应的配置文件：

Data ID	Group	说明
`gateway-server-prod.yaml`	DEFAULT_GROUP	网关配置
`system-server-prod.yaml`	DEFAULT_GROUP	系统服务配置（数据库、Redis 等）
`infra-server-prod.yaml`	DEFAULT_GROUP	基础设施服务配置
`bpm-server-prod.yaml`	DEFAULT_GROUP	工作流服务配置
`oa-server-prod.yaml`	DEFAULT_GROUP	OA 服务配置
...其他服务同理

配置示例（system-server-prod.yaml）：

yaml

spring:
  datasource:
    dynamic:
      primary: master
      datasource:
        master:
          url: jdbc:mysql://数据库IP:3306/ruoyi-office?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true
          username: root
          password: 数据库密码
  data:
    redis:
      host: Redis地址
      port: 6379
      database: 0

五、部署后端服务

5.1 上传 JAR 到服务器

bash

# 上传到统一目录
scp yudao-gateway/target/yudao-gateway.jar                                           root@服务器IP:/data/app/gateway/
scp yudao-module-system/yudao-module-system-server/target/yudao-module-system-server.jar  root@服务器IP:/data/app/system/
scp yudao-module-infra/yudao-module-infra-server/target/yudao-module-infra-server.jar    root@服务器IP:/data/app/infra/
scp yudao-module-bpm/yudao-module-bpm-server/target/yudao-module-bpm-server.jar          root@服务器IP:/data/app/bpm/
scp yudao-module-oa/yudao-module-oa-server/target/yudao-module-oa-server.jar             root@服务器IP:/data/app/oa/
# ...其他模块同理

5.2 启动顺序

微服务间有依赖关系，必须按以下顺序启动：

1. gateway-server      （网关，依赖 Nacos）
2. system-server       （系统服务，核心基础）
3. infra-server        （基础设施，依赖 system）
4. 其他服务            （bpm / oa / crm / erp / pay / ...，依赖 system + infra）

5.3 启动命令

通用启动模板：

bash

nohup java -Xms512m -Xmx1024m \
    -jar /data/app/服务目录/xxx-server.jar \
    --spring.profiles.active=prod \
    --spring.cloud.nacos.server-addr=Nacos地址:8848 \
    --spring.cloud.nacos.discovery.namespace=prod \
    --spring.cloud.nacos.config.namespace=prod \
    > /data/app/服务目录/nohup.out 2>&1 &

完整启动示例

bash

# ① 网关
nohup java -Xms256m -Xmx512m \
    -jar /data/app/gateway/yudao-gateway.jar \
    --spring.profiles.active=prod \
    --spring.cloud.nacos.server-addr=192.168.30.100:8848 \
    --spring.cloud.nacos.discovery.namespace=prod \
    --spring.cloud.nacos.config.namespace=prod \
    > /data/app/gateway/nohup.out 2>&1 &

# ② 系统服务
nohup java -Xms512m -Xmx1024m \
    -jar /data/app/system/yudao-module-system-server.jar \
    --spring.profiles.active=prod \
    --spring.cloud.nacos.server-addr=192.168.30.100:8848 \
    --spring.cloud.nacos.discovery.namespace=prod \
    --spring.cloud.nacos.config.namespace=prod \
    > /data/app/system/nohup.out 2>&1 &

# 等待 system 启动完成（约 30s）
sleep 30

# ③ 基础设施服务
nohup java -Xms512m -Xmx1024m \
    -jar /data/app/infra/yudao-module-infra-server.jar \
    --spring.profiles.active=prod \
    --spring.cloud.nacos.server-addr=192.168.30.100:8848 \
    --spring.cloud.nacos.discovery.namespace=prod \
    --spring.cloud.nacos.config.namespace=prod \
    > /data/app/infra/nohup.out 2>&1 &

# 等待 infra 启动完成（约 30s）
sleep 30

# ④ 工作流服务
nohup java -Xms512m -Xmx1024m \
    -jar /data/app/bpm/yudao-module-bpm-server.jar \
    --spring.profiles.active=prod \
    --spring.cloud.nacos.server-addr=192.168.30.100:8848 \
    --spring.cloud.nacos.discovery.namespace=prod \
    --spring.cloud.nacos.config.namespace=prod \
    > /data/app/bpm/nohup.out 2>&1 &

# ⑤ OA 服务
nohup java -Xms512m -Xmx1024m \
    -jar /data/app/oa/yudao-module-oa-server.jar \
    --spring.profiles.active=prod \
    --spring.cloud.nacos.server-addr=192.168.30.100:8848 \
    --spring.cloud.nacos.discovery.namespace=prod \
    --spring.cloud.nacos.config.namespace=prod \
    > /data/app/oa/nohup.out 2>&1 &

# 其他服务以此类推...

5.4 验证服务注册

启动完成后，访问 Nacos 控制台 → 服务管理 → 服务列表，确认各服务已注册：

http://Nacos地址:8848/nacos

应该能看到 gateway-server、system-server、infra-server 等服务实例。

六、部署前端

6.1 确认前端环境变量

apps/web-antd/.env.production：

bash

VITE_BASE_URL=
VITE_GLOB_API_URL=/admin-api

前端通过 Nginx 代理 /admin-api → Gateway（:48080），Gateway 再根据路由规则转发到各微服务。

6.2 上传到服务器

bash

ssh root@服务器IP "rm -rf /data/nginx/html/web/*"
scp -r apps/web-antd/dist/* root@服务器IP:/data/nginx/html/web/

七、Nginx 配置

微服务模式下 Nginx 只需反代到 Gateway（而非各个微服务），由 Gateway 负责路由分发。

nginx

server {
    listen 80;
    server_name _;

    # 1. 前端静态文件
    location /web {
        alias /data/nginx/html/web;
        index index.html;
        try_files $uri $uri/ /web/index.html;
    }

    # 2. 后端 API → 全部转发到 Gateway
    location /admin-api {
        proxy_pass http://127.0.0.1:48080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # 3. WebSocket 连接
    location /infra/ws {
        proxy_pass http://127.0.0.1:48080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 4. 接口文档（Knife4j 聚合）
    location /doc.html {
        proxy_pass http://127.0.0.1:48080;
        proxy_set_header Host $host;
    }

    # 5. 根路径跳转
    location = / {
        return 302 /web;
    }
}

修改后重新加载：

bash

nginx -t && nginx -s reload

八、Gateway 路由规则

Gateway 根据 URL 前缀将请求转发到对应微服务（已内置，通常无需修改）：

URL 前缀	转发目标服务	示例
`/admin-api/system/**`	system-server	登录、用户、角色
`/admin-api/infra/**`	infra-server	文件上传、配置
`/admin-api/bpm/**`	bpm-server	流程定义、审批
`/admin-api/oa/**`	oa-server	OA 协同办公
`/admin-api/crm/**`	crm-server	客户管理
`/admin-api/erp/**`	erp-server	进销存
`/admin-api/pay/**`	pay-server	支付
`/admin-api/member/**`	member-server	会员
`/admin-api/report/**`	report-server	报表
`/admin-api/mp/**`	mp-server	公众号
`/admin-api/ai/**`	ai-server	AI 大模型
`/admin-api/iot/**`	iot-server	物联网
`/admin-api/hrm/**`	hrm-server	人力资源
`/admin-api/asset/**`	asset-server	资产管理
`/admin-api/product/**`	product-server	商品
`/admin-api/trade/**`	trade-server	交易
`/admin-api/promotion/**`	promotion-server	营销
`/admin-api/statistics/**`	statistics-server	统计

Gateway 使用 grayLb:// 协议，支持基于 Nacos 的服务发现 + 负载均衡。

九、验证

9.1 检查各服务

bash

# 检查 Gateway
curl http://127.0.0.1:48080/actuator/health

# 检查 system-server
curl http://127.0.0.1:48081/actuator/health

# 检查 infra-server
curl http://127.0.0.1:48082/actuator/health

# 通过 Gateway 访问系统接口
curl http://127.0.0.1:48080/admin-api/system/auth/get-permission-info

9.2 检查前端

浏览器访问 http://服务器IP/web，正常显示登录页，输入账号密码能登录成功。

9.3 检查接口文档

访问 http://服务器IP:48080/doc.html，Gateway 会聚合所有微服务的 Swagger 文档。

十、一键启停脚本

10.1 一键启动（start-all.sh）

bash

#!/bin/bash
# start-all.sh - 按依赖顺序启动所有微服务

NACOS_ADDR="192.168.30.100:8848"
NAMESPACE="prod"
PROFILE="prod"
BASE_DIR="/data/app"

start_service() {
    local name=$1
    local jar=$2
    local xms=${3:-512m}
    local xmx=${4:-1024m}
    local dir="$BASE_DIR/$name"

    echo "🚀 启动 $name ..."
    mkdir -p "$dir"
    nohup java -Xms$xms -Xmx$xmx \
        -jar "$dir/$jar" \
        --spring.profiles.active=$PROFILE \
        --spring.cloud.nacos.server-addr=$NACOS_ADDR \
        --spring.cloud.nacos.discovery.namespace=$NAMESPACE \
        --spring.cloud.nacos.config.namespace=$NAMESPACE \
        > "$dir/nohup.out" 2>&1 &
    echo "  PID: $!"
}

# 按顺序启动
start_service "gateway" "yudao-gateway.jar" "256m" "512m"
start_service "system"  "yudao-module-system-server.jar"
sleep 30
start_service "infra"   "yudao-module-infra-server.jar"
sleep 20

# 以下服务可并行启动
start_service "bpm"     "yudao-module-bpm-server.jar"
start_service "oa"      "yudao-module-oa-server.jar"
# 按需添加更多服务...
# start_service "crm"   "yudao-module-crm-server.jar"
# start_service "erp"   "yudao-module-erp-server.jar"
# start_service "pay"   "yudao-module-pay-server.jar"
# start_service "ai"    "yudao-module-ai-server.jar" "512m" "2048m"

echo ""
echo "✅ 所有服务启动命令已下发，请等待 1-2 分钟后检查 Nacos 服务列表"

10.2 一键停止（stop-all.sh）

bash

#!/bin/bash
# stop-all.sh - 停止所有微服务

SERVICES=(
    "yudao-gateway"
    "yudao-module-system-server"
    "yudao-module-infra-server"
    "yudao-module-bpm-server"
    "yudao-module-oa-server"
    # 按需添加...
)

for svc in "${SERVICES[@]}"; do
    PID=$(ps -ef | grep "$svc" | grep -v grep | awk '{print $2}')
    if [ -n "$PID" ]; then
        echo "⏹️  停止 $svc (PID: $PID)"
        kill $PID
    else
        echo "⏭️  $svc 未运行"
    fi
done

echo "✅ 停止命令已发送"

10.3 查看运行状态（status.sh）

bash

#!/bin/bash
# status.sh - 查看所有微服务状态

echo "========================================"
echo "  微服务运行状态"
echo "========================================"

SERVICES=(
    "yudao-gateway:48080"
    "yudao-module-system-server:48081"
    "yudao-module-infra-server:48082"
    "yudao-module-bpm-server:48083"
    "yudao-module-oa-server:48101"
)

for entry in "${SERVICES[@]}"; do
    svc="${entry%%:*}"
    port="${entry##*:}"
    PID=$(ps -ef | grep "$svc" | grep -v grep | awk '{print $2}')

    if [ -n "$PID" ]; then
        echo "✅ $svc (PID: $PID, 端口: $port)"
    else
        echo "❌ $svc 未运行"
    fi
done

十一、单体模式 vs 微服务模式对比

对比项	单体模式	微服务模式
构建命令	`mvn package -pl yudao-server -am -Dskip.repackage=true`	`mvn package`
Maven Profile	`-Pboot`（或 `-Pprod -Dskip.repackage=true`）	`-Pcloud`（默认）
产出	1 个 JAR（yudao-server.jar）	N 个 JAR（每个模块一个）
注册中心	不需要	需要 Nacos
API 入口	直接访问 :48080	Gateway :48080 → 各服务
Nginx 反代	`/admin-api → :48080`	`/admin-api → Gateway :48080`
服务器要求	4GB+ 内存	8GB+ 内存（推荐 16GB）
适用场景	中小团队、快速上线	大团队、高并发、独立扩缩容

十二、常见问题

Q1: 服务启动后在 Nacos 看不到

bash

# 检查 Nacos 连接
curl http://Nacos地址:8848/nacos/v1/ns/instance/list?serviceName=system-server

# 检查启动日志
tail -100 /data/app/system/nohup.out | grep -i nacos

# 常见原因：
# 1. Nacos 地址配错
# 2. namespace 不匹配
# 3. 网络不通（telnet Nacos地址 8848）

Q2: Gateway 报 503 Service Unavailable

bash

# 目标服务尚未启动或注册，等待 30s 重试
# 检查目标服务是否在 Nacos 注册
curl http://Nacos地址:8848/nacos/v1/ns/instance/list?serviceName=system-server

Q3: 服务间调用超时

bash

# 检查调用链路，确认目标服务正常
curl http://127.0.0.1:目标端口/actuator/health

# 适当调大 Feign 超时
# 在 Nacos 配置中添加：
# spring.cloud.openfeign.client.config.default.connect-timeout=10000
# spring.cloud.openfeign.client.config.default.read-timeout=30000

Q4: 内存不够，想只启动部分服务

最小可用集（管理后台基本功能）：

gateway-server + system-server + infra-server

加上 OA 和工作流：

gateway-server + system-server + infra-server + bpm-server + oa-server

内存估算：每个服务约 512MB ~ 1GB，Gateway 约 256MB。

Q5: 如何切换到单体模式

bash

# 单体模式只需一个 JAR，无需 Nacos
mvn clean package -Dmaven.test.skip=true -Dskip.repackage=true -pl yudao-server -am -Pprod

java -jar yudao-server/target/yudao-server.jar --spring.profiles.active=prod

详见快速部署指南。

微服务部署指南 ​

一、架构总览 ​

二、服务清单与端口 ​

三、构建 ​

3.1 微服务模式构建（全量） ​

3.2 构建指定模块 ​

3.3 构建产物位置 ​

3.4 前端构建 ​

四、Nacos 配置 ​

4.1 各服务连接 Nacos ​

4.2 环境变量覆盖（推荐） ​

4.3 Nacos 中的配置文件 ​

五、部署后端服务 ​

5.1 上传 JAR 到服务器 ​

5.2 启动顺序 ​

5.3 启动命令 ​

完整启动示例 ​

5.4 验证服务注册 ​

六、部署前端 ​

6.1 确认前端环境变量 ​

6.2 上传到服务器 ​

七、Nginx 配置 ​

八、Gateway 路由规则 ​

九、验证 ​

9.1 检查各服务 ​

9.2 检查前端 ​

9.3 检查接口文档 ​

十、一键启停脚本 ​

10.1 一键启动（start-all.sh） ​

10.2 一键停止（stop-all.sh） ​

10.3 查看运行状态（status.sh） ​

十一、单体模式 vs 微服务模式对比 ​

十二、常见问题 ​

Q1: 服务启动后在 Nacos 看不到 ​

Q2: Gateway 报 503 Service Unavailable ​

Q3: 服务间调用超时 ​

Q4: 内存不够，想只启动部分服务 ​

Q5: 如何切换到单体模式 ​

微服务部署指南

一、架构总览

二、服务清单与端口

三、构建

3.1 微服务模式构建（全量）

3.2 构建指定模块

3.3 构建产物位置

3.4 前端构建

四、Nacos 配置

4.1 各服务连接 Nacos

4.2 环境变量覆盖（推荐）

4.3 Nacos 中的配置文件

五、部署后端服务

5.1 上传 JAR 到服务器

5.2 启动顺序

5.3 启动命令

完整启动示例

5.4 验证服务注册

六、部署前端

6.1 确认前端环境变量

6.2 上传到服务器

七、Nginx 配置

八、Gateway 路由规则

九、验证

9.1 检查各服务

9.2 检查前端

9.3 检查接口文档

十、一键启停脚本

10.1 一键启动（start-all.sh）

10.2 一键停止（stop-all.sh）

10.3 查看运行状态（status.sh）

十一、单体模式 vs 微服务模式对比

十二、常见问题

Q1: 服务启动后在 Nacos 看不到

Q2: Gateway 报 503 Service Unavailable

Q3: 服务间调用超时

Q4: 内存不够，想只启动部分服务

Q5: 如何切换到单体模式