RuoYi-Cloud-Plus 微服务部署避坑指南：用 Docker Compose 一键搞定 Nacos + Sentinel + Seata

RuoYi-Cloud-Plus 微服务容器化实战从零构建生产级环境在个人开发机或测试服务器上搭建完整的微服务学习环境往往需要面对组件繁杂、配置琐碎的问题。RuoYi-Cloud-Plus作为基于Spring Cloud Alibaba的企业级开发框架整合了Nacos、Sentinel、Seata等核心组件本文将带你用Docker Compose快速搭建全栈环境避开那些新手常踩的坑。1. 环境准备与基础架构设计在开始部署之前我们需要明确几个关键点首先是硬件资源分配建议开发环境至少预留4核CPU和8GB内存其次是网络规划微服务组件间的通信端口需要提前梳理最后是存储方案特别是需要持久化的组件如Nacos和Seata。1.1 Docker与Docker Compose安装确保系统已安装Docker引擎版本20.10.0和Docker Compose插件。对于Linux系统推荐使用官方安装脚本# Docker引擎安装 curl -fsSL https://get.docker.com | sh # Docker Compose插件安装 sudo apt-get install docker-compose-plugin验证安装是否成功docker --version docker compose version注意生产环境建议配置docker守护进程的日志轮转和存储驱动避免容器日志占满磁盘空间。1.2 目录结构规划合理的目录结构能大幅降低后期维护成本推荐采用以下组织方式ruoyi-cloud-plus/ ├── compose/ # Docker Compose文件 │ ├── nacos/ # Nacos相关配置 │ ├── sentinel/ # Sentinel相关配置 │ └── seata/ # Seata相关配置 ├── data/ # 持久化数据 │ ├── mysql/ # 数据库数据 │ ├── nacos/ # Nacos数据 │ └── seata/ # Seata数据 └── config/ # 应用配置文件 ├── ruoyi-auth/ # 认证服务配置 ├── ruoyi-gateway/ # 网关配置 └── ... # 其他服务配置2. 核心组件部署与配置2.1 Nacos集群部署Nacos作为服务发现和配置中心在生产环境中应当以集群方式运行。以下是docker-compose-nacos.yml的关键配置version: 3.8 services: nacos1: image: nacos/nacos-server:v2.2.0 container_name: nacos1 environment: - MODEcluster - NACOS_SERVERSnacos1:8848 nacos2:8848 nacos3:8848 - SPRING_DATASOURCE_PLATFORMmysql - MYSQL_SERVICE_HOSTmysql - MYSQL_SERVICE_DB_NAMEnacos_config - MYSQL_SERVICE_USERnacos - MYSQL_SERVICE_PASSWORDnacos123 volumes: - ./data/nacos/logs1:/home/nacos/logs ports: - 8848:8848 - 9848:9848 nacos2: image: nacos/nacos-server:v2.2.0 # 类似配置... mysql: image: mysql:5.7 # 数据库配置...常见问题解决方案端口冲突确保8848HTTP、9848gRPC端口未被占用数据库连接失败检查MySQL用户权限和字符集设置建议utf8mb4集群节点无法发现验证NACOS_SERVERS环境变量格式是否正确2.2 Sentinel控制台集成Sentinel的部署相对简单但需要注意控制台的访问安全sentinel: image: bladex/sentinel-dashboard:1.8.6 container_name: sentinel environment: - AUTH_USERNAMEsentinel - AUTH_PASSWORDsentinel123 ports: - 8080:8080在RuoYi-Cloud-Plus项目中配置Sentinel:# application.yml spring: cloud: sentinel: transport: dashboard: sentinel:8080 port: 8719 eager: true重要生产环境务必修改默认账号密码并考虑通过Nginx添加HTTPS和基础认证2.3 Seata Server部署与模式选择Seata支持AT、TCC等多种事务模式部署时需要根据业务需求选择seata: image: seataio/seata-server:1.6.1 container_name: seata environment: - SEATA_IPseata - STORE_MODEdb - DB_HOSTmysql - DB_PORT3306 - DB_USERseata - DB_PASSWORDseata123 volumes: - ./config/seata/registry.conf:/seata-server/resources/registry.conf ports: - 8091:8091事务模式对比模式适用场景优点缺点AT大部分业务场景无侵入、使用简单全局锁可能影响性能TCC需要精确控制的事务高性能、无锁需要业务改造Saga长事务场景支持补偿机制实现复杂度高3. RuoYi-Cloud-Plus项目对接3.1 服务注册与配置管理修改项目的bootstrap.yml指向我们部署的Nacos集群spring: cloud: nacos: discovery: server-addr: nacos1:8848,nacos2:8848,nacos3:8848 config: server-addr: ${spring.cloud.nacos.discovery.server-addr} file-extension: yaml shared-configs: ->Configuration public class SeataConfig { Bean public GlobalTransactionScanner globalTransactionScanner() { return new GlobalTransactionScanner(your-app-name, my_test_tx_group); } }常见问题排查事务不生效检查GlobalTransactional注解是否添加正确无法连接Seata Server验证registry.conf中的注册中心配置AT模式表缺失确保业务库中存在undo_log表3.3 网关与权限整合RuoYi-Gateway的Docker化部署需要注意FROM openjdk:17-jdk COPY target/ruoyi-gateway.jar /app.jar ENTRYPOINT [java,-jar,/app.jar]网关的关键配置项# 路由配置示例 spring: cloud: gateway: routes: - id: auth uri: lb://ruoyi-auth predicates: - Path/auth/** filters: - StripPrefix14. 生产环境优化建议4.1 监控与告警方案推荐部署PrometheusGrafana监控体系prometheus: image: prom/prometheus volumes: - ./config/prometheus.yml:/etc/prometheus/prometheus.yml ports: - 9090:9090 grafana: image: grafana/grafana ports: - 3000:3000关键监控指标Nacos服务实例数、配置变更频率SentinelQPS、拒绝请求数、异常比例Seata全局事务提交/回滚率、事务耗时4.2 高可用架构设计对于生产环境建议采用以下架构Nacos集群3节点及以上配合SLB数据库主从复制或集群方案Sentinel多节点部署配置持久化到NacosSeataServer集群DB存储模式4.3 性能调优经验根据实际压测经验给出以下参数建议# JVM参数优化 JAVA_OPTS-Xms2g -Xmx2g -XX:UseG1GC -XX:MaxGCPauseMillis200 # Seata性能相关配置 server: undo: log-save-days: 7 service: disable-global-transaction: false store: mode: db db: max-wait: 5000网络配置优化项调整Docker的MTU值匹配网络环境为容器网络设置合理的CPU和内存限制考虑使用host网络模式减少NAT开销5. 常见问题速查手册5.1 启动顺序问题微服务组件间存在依赖关系推荐启动顺序基础设施MySQL、Redis等Nacos集群Seata ServerSentinel控制台业务服务网关→认证→其他可以使用depends_on和健康检查控制启动顺序services: ruoyi-gateway: depends_on: nacos: condition: service_healthy healthcheck: test: [CMD, curl, -f, http://localhost:8080/actuator/health]5.2 数据持久化问题确保关键数据的持久化卷配置正确volumes: - ./data/nacos:/home/nacos/data - ./data/seata:/seata-server/sessionStore5.3 网络连接问题跨容器通信问题排查步骤检查容器是否在同一网络docker network inspect bridge验证DNS解析docker exec -it container_name ping service_name检查防火墙规则iptables -L -n5.4 版本兼容性问题组件版本匹配建议组件RuoYi-Cloud-Plus版本推荐版本Nacos4.x2.2.0Sentinel4.x1.8.6Seata4.x1.6.1Spring Cloud2022.x2022.0.36. 进阶部署方案6.1 Kubernetes部署转换将Docker Compose迁移到Kubernetes的要点使用Kompose工具转换基础配置kompose convert -f docker-compose.yml添加必要的K8s资源ConfigMap用于配置文件Secret管理敏感信息Ingress暴露服务HPA自动扩缩容6.2 多环境配置管理利用Nacos命名空间实现环境隔离spring: cloud: nacos: config: namespace: ${spring.profiles.active} discovery: namespace: ${spring.profiles.active}6.3 CI/CD流水线设计典型的GitLab CI配置示例stages: - build - test - deploy build_job: stage: build script: - mvn clean package -DskipTests artifacts: paths: - target/*.jar deploy_dev: stage: deploy environment: dev script: - docker-compose -f docker-compose-dev.yml up -d only: - dev7. 安全加固措施7.1 组件安全配置各组件的最低安全要求Nacos启用鉴权(nacos.core.auth.enabledtrue)修改默认账号密码配置IP白名单Sentinel开启登录认证限制控制台访问IP定期清理无用规则Seata加密事务分组名称启用SSL通信监控undo_log表大小7.2 网络隔离方案建议的网络分区设计管理网络Nacos、Sentinel等管理组件业务网络微服务实例数据网络数据库、Redis等存储组件使用Docker网络实现隔离docker network create --driver bridge management docker network create --driver bridge application7.3 日志与审计集中式日志收集方案filebeat: image: docker.elastic.co/beats/filebeat:8.6.2 volumes: - /var/lib/docker/containers:/var/lib/docker/containers:ro - ./config/filebeat.yml:/usr/share/filebeat/filebeat.yml关键日志路径组件日志位置重要信息Nacos/home/nacos/logs集群选举、配置变更Seata/seata-server/logs全局事务状态应用/logs业务异常、超时请求