若依微服务一键部署（RuoYi-Cloud）：Nacos/Redis/MySQL + Gateway + Robot 接入（踩坑与修复全记录）

本文记录我把 高仙（Gaussian）机器人对接项目 从"本机能跑"迁到 Docker 一键部署 的全过程：

包含 四个后端服务（gateway/auth/system/robot） 、前端 Nginx 、MySQL/Redis 、Nacos 配置中心 、Sentinel 控制台 的改造要点、核心配置与疑难问题修复。

所有敏感密钥均已脱敏，请在私有环境中替换为真实值。

---

0. 环境与目标

环境版本

• Docker Desktop / Docker Compose

• MySQL 8、Redis 7

• Nacos 2.2.3（宿主机）

• Sentinel Dashboard 1.8.8（宿主机） （账号/密码：sentinel/sentinel）

• JDK 8/11/17 均可（以项目实际为准）

目标

1. 代码、配置、镜像、编排 全链路容器化 ，实现 clone → compose up → 访问。

2. 配置中心化 （Nacos）：服务从 Nacos 拉取 *-dev.yml。

3. 容器内可连宿主机（Nacos 8848、Sentinel 8718）。

4. 可复现：镜像已推送至我的 DockerHub，仓库含 README、初始化 SQL、Compose、Nginx 配置。

---

1. 仓库结构（精简示意）

.
├─ ruoyi-gateway/      # 网关服务（Dockerfile, bootstrap.yml）
├─ ruoyi-auth/         # 认证服务（Dockerfile, bootstrap.yml）
├─ ruoyi-modules/
│  └─ ruoyi-system/    # 系统服务（Dockerfile, bootstrap.yml, mapper/*.xml 改造）
│  └─ ruoyi-robot/     # 机器人服务（Dockerfile, bootstrap.yml）
├─ nginx/
│  ├─ dockerfile
│  └─ conf/nginx.conf  # 反代 /prod-api/** → gateway:8080；静态资源 root 指向 dist
├─ mysql-init/
│  ├─ 00-init.sh       # 创建库并导入 SQL（ry-cloud / ry-config / nacos_config）
│  ├─ 10-ry-cloud.sql
│  └─ 20-ry-config.sql
├─ docker-compose.micro.yml
└─ README.md

2. 关键改造（一图流）

A. system 模块 Mapper 修复 → 统一 com.ruoyi.system.domain.*
B. 四服务 bootstrap.yml → Nacos 改为 host.docker.internal:8848
C. Nacos *-dev.yml → Redis 指向 redis:6379、数据源指向 mysql8:3306；Sentinel 改宿主机地址
D. Nginx → dist/ 静态托管 + /prod-api/** 反代到 gateway:8080
E. MySQL → 00-init.sh 一键建库建表
F. Compose → extra_hosts + DNS + JAVA_TOOL_OPTIONS 确保容器内网络/协议通畅

---

3. 改造细节与配置片段

3.1 system：Mapper 与 MyBatis（部署关键点）

问题 ：微服务化后，部分 XML 仍引用 com.ruoyi.system.api.domain.*，导致运行时 找不到 mapper。

统一修复

• 把 ruoyi-modules/ruoyi-system/mapper/*.xml 中的
  parameterType / resultMap 全部改为 com.ruoyi.system.domain.*。

# mybatis配置（这段不能错）
mybatis:
  typeAliasesPackage: com.ruoyi.system.domain
  mapperLocations: classpath*:mapper/**/*.xml

3.2 四服务 bootstrap.yml（容器内访问宿主机 Nacos）

spring:
  cloud:
    nacos:
      discovery:
        server-addr: host.docker.internal:8848
      config:
        server-addr: host.docker.internal:8848

说明：容器内的 localhost 只指向容器本身，必须使用 host.docker.internal 才能连到宿主机（Windows/Mac 默认可用；Linux 见 3.5 的 extra_hosts）。

3.3 Nacos 中的 *-dev.yml（统一 Redis/MySQL/Sentinel）

通用 Redis（四服务一致）

spring:
  redis:
    host: redis
    port: 6379
    password:

数据源（system/robot）

spring:
  datasource:
    dynamic:
      datasource:
        master:
          driver-class-name: com.mysql.cj.jdbc.Driver
          url: xxxxxxxx
          username: root
          password: 123456

Sentinel（robot 已改，gateway 建议同步）

spring:
  cloud:
    sentinel:
      eager: true
      transport:
        dashboard: host.docker.internal:8718
      datasource:
        # robot 的服务内流控/降级规则从 Nacos 拉取
        flow:
          nacos:
            serverAddr: host.docker.internal:8848
            groupId: DEFAULT_GROUP
            dataId: ruoyi-robot-flow-rules
            dataType: json
            ruleType: flow
        degrade:
          nacos:
            serverAddr: host.docker.internal:8848
            groupId: DEFAULT_GROUP
            dataId: ruoyi-robot-degrade-rules
            dataType: json
            ruleType: degrade

Gateway 路由（节选）

spring:
  cloud:
    gateway:
      routes:
        - id: ruoyi-auth
          uri: lb://ruoyi-auth
          predicates: [ Path=/auth/** ]
          filters: [ StripPrefix=1, CacheRequestBody, ValidateCodeFilter ]

        - id: ruoyi-system
          uri: lb://ruoyi-system
          predicates: [ Path=/system/** ]
          filters: [ StripPrefix=1 ]

        - id: ruoyi-robot
          uri: lb://ruoyi-robot
          predicates: [ Path=/external/gs/** ]
          # filters: [ StripPrefix=1 ]  # 如需

3.4 Nginx：静态资源与反向代理

server {
  listen 80;
  server_name localhost;

  # 前端 dist 静态资源
  location / {
    root /home/ruoyi/projects/ruoyi-ui;
    try_files $uri $uri/ /index.html;
    index index.html index.htm;
  }

  # 后端统一入口 → Gateway
  location /prod-api/ {
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://ruoyi-gateway:8080/;
  }

  # 避免暴露健康端点
  if ($uri ~ "/actuator") { return 403; }
}

3.5 Compose：容器网络增强（Robot 无数据的关键修复）

services:
  ruoyi-robot:
    # ...
    extra_hosts:
      - "host.docker.internal:host-gateway"   # Linux 环境映射宿主机
    environment:
      NACOS_SERVER_ADDR: host.docker.internal:8848
      JAVA_TOOL_OPTIONS: >
        -Dhttps.protocols=TLSv1.2
        -Djdk.tls.client.protocols=TLSv1.2
        -Djava.net.preferIPv4Stack=true
    dns:
      - 223.5.5.5
      - 119.29.29.29

实测：加上 extra_hosts + DNS + TLS 后，高仙 OpenAPI 访问/域名解析更稳定，UI「Robot 无数据」问题消失。

3.6 MySQL：一键建库建表脚本

mysql-init/00-init.sh（节选）

mysql -uroot -p"$MYSQL_ROOT_PASSWORD" -e "
  CREATE DATABASE IF NOT EXISTS \`ry-cloud\`  DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_general_ci;
  CREATE DATABASE IF NOT EXISTS \`ry-config\` DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_general_ci;
  CREATE DATABASE IF NOT EXISTS \`nacos_config\` DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_general_ci;
"
mysql -uroot -p"$MYSQL_ROOT_PASSWORD" --database='ry-cloud'  < /docker-entrypoint-initdb.d/10-ry-cloud.sql
mysql -uroot -p"$MYSQL_ROOT_PASSWORD" --database='ry-config' < /docker-entrypoint-initdb.d/20-ry-config.sql
# 可选：
# mysql -uroot -p"$MYSQL_ROOT_PASSWORD" --database='nacos_config' < /docker-entrypoint-initdb.d/30-nacos-mysql.sql

4. 一键启动

# 1) 先在宿主机启动 Nacos（8848）、Sentinel Dashboard（8718）
java -Dserver.port=8718 \
     -Dcsp.sentinel.dashboard.server=localhost:8718 \
     -Dproject.name=sentinel-dashboard \
     -Dcsp.sentinel.api.port=8719 \
     -jar sentinel-dashboard-1.8.8.jar

# 2) docker compose
docker compose -f docker-compose.micro.yml up -d

# 3) 访问
# 前端：  http://localhost
# Nacos：  http://localhost:8848/nacos  （nacos/nacos）
# Sentinel： http://localhost:8718

镜像已推送可直接拉取；如需本地构建：

mvn -DskipTests -pl ruoyi-system -am clean package
docker build -f ruoyi-system/Dockerfile -t xxxxx/ruoyi-system:1.0.0 ruoyi-system
docker push xxxxxx/ruoyi-system:1.0.0
# 其他服务同理

5. 验证（Smoke Test）

• 服务注册 ：Nacos → ruoyi-gateway/auth/system/robot 均为 UP

• 路由连通

curl -i http://localhost/prod-api/system/notice/list
curl -i "http://localhost/prod-api/external/gs/status/{SerialNumber}"

• 前端刷新不 404 （try_files 生效）

• Redis/MySQL 无 connection refused、Communications link failure

• Sentinel 能看到 ruoyi-robot、ruoyi-gateway 实例与已加载的限流/降级规则

6. 重点问题解决（Hotfix 摘要）

6.1 system 容器启动报「找不到 mapper」

• 现象 ：Invalid bound statement (not found)

• 根因 ：XML 仍指向 api.domain 包

• 修复 ：统一改为 com.ruoyi.system.domain.*；Nacos 中 mybatis.typeAliasesPackage/mapperLocations 与之匹配

6.2 前端进入页面后「Robot 无数据」

• 根因：容器内无法稳定连接宿主机 Nacos/Sentinel，或外网解析/TLS 兼容问题

• 修复（Compose 关键项）：

  extra_hosts:
    - "host.docker.internal:host-gateway"
  environment:
    NACOS_SERVER_ADDR: host.docker.internal:8848
    JAVA_TOOL_OPTIONS: >
      -Dhttps.protocols=TLSv1.2
      -Djdk.tls.client.protocols=TLSv1.2
      -Djava.net.preferIPv4Stack=true
  dns:
    - 223.5.5.5
    - 119.29.29.29

7. 常见坑位 · 原因 · 修复

问题	典型日志	根因	修复
Nacos 连接 STARTING	Client not connected, status: STARTING	容器内连 localhost:8848	bootstrap.yml 全改 host.docker.internal:8848
找不到 Mapper	Invalid bound statement	XML 包路径与实体不匹配	XML → com.ruoyi.system.domain.*，并同步 MyBatis 配置
Redis 连接失败	connection refused	spring.redis.host 用了 127.0.0.1	改为 redis（容器名）
MySQL 连接失败	Communications link failure	URL 用了 localhost	改为 mysql8:3306（容器名）
Gateway 路由 404	404	服务未注册/路由 ID 或 name 不一致	对齐 spring.application.name 与 lb://{name}
前端刷新 404	404	Nginx 未 try_files	try_files $uri $uri/ /index.html;
Sentinel 无实例/无规则	空白	Dashboard/规则源仍是 localhost	全改 host.docker.internal:8718/8848

8. 收尾与建议

• 把 host.docker.internal 抽成 环境变量 （Compose x-environment 统一注入），Linux 统一用 extra_hosts 兼容。

• Compose 为关键容器加 healthcheck 与 restart: always，增强自愈。

• Nacos 规则按环境（dev/prod）分组隔离 ；对网关/机器人输出统一的 限流/降级 策略模板。

• 预留 K8s 部署（YAML 清单 & Helm），后续上云平滑迁移。

9. 附：实用命令集

# 查看容器日志
docker compose logs -f ruoyi-gateway
docker compose logs -f ruoyi-system

# 排查容器内网络
docker exec -it ruoyi-robot sh
curl -I host.docker.internal:8848/nacos
nslookup openapi.gs-robot.com

# 重建单服务
docker compose up -d --no-deps --force-recreate ruoyi-system