若依微服務一鍵部署（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 均可（以項目實際為準）

目標

代碼、配置、鏡像、編排 全鏈路容器化，實現 clone → compose up → 訪問。
配置中心化（Nacos）：服務從 Nacos 拉取 *-dev.yml。
容器內可連宿主機（Nacos 8848、Sentinel 8718）。
可復現：鏡像已推送至我的 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.domainmapperLocations: classpath*:mapper/**/*.xml

3.2 四服務 `bootstrap.yml`（容器內訪問宿主機 Nacos）

spring:cloud:nacos:discovery:server-addr: host.docker.internal:8848config: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: redisport: 6379password:

數據源（system/robot）

spring:datasource:dynamic:datasource:master:driver-class-name: com.mysql.cj.jdbc.Driverurl: xxxxxxxxusername: rootpassword: 123456

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

spring:cloud:sentinel:eager: truetransport:dashboard: host.docker.internal:8718datasource:# robot 的服務內流控/降級規則從 Nacos 拉取flow:nacos:serverAddr: host.docker.internal:8848groupId: DEFAULT_GROUPdataId: ruoyi-robot-flow-rulesdataType: jsonruleType: flowdegrade:nacos:serverAddr: host.docker.internal:8848groupId: DEFAULT_GROUPdataId: ruoyi-robot-degrade-rulesdataType: jsonruleType: degrade

Gateway 路由（節選）

spring:cloud:gateway:routes:- id: ruoyi-authuri: lb://ruoyi-authpredicates: [ Path=/auth/** ]filters: [ StripPrefix=1, CacheRequestBody, ValidateCodeFilter ]- id: ruoyi-systemuri: lb://ruoyi-systempredicates: [ Path=/system/** ]filters: [ StripPrefix=1 ]- id: ruoyi-roboturi: lb://ruoyi-robotpredicates: [ 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;}# 后端統一入口 → Gatewaylocation /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:8848JAVA_TOOL_OPTIONS: >-Dhttps.protocols=TLSv1.2-Djdk.tls.client.protocols=TLSv1.2-Djava.net.preferIPv4Stack=truedns:- 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:8848JAVA_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