1. 项目概述与核心价值最近在帮一个朋友的公司做技术架构升级他们之前用的是单体版的RuoYi随着业务量上来单服务扛不住决定迁移到微服务架构的RuoYi-Cloud。我负责整个生产环境的部署落地选型就是最经典的Linux MySQL Nginx组合。这个组合听起来老生常谈但真要在生产环境里把它调顺了从零开始走一遍里头的门道可不少。网上教程很多但要么是纯命令罗列要么就是跳过了关键配置照着做十有八九会卡在某个环节比如最经典的“服务注册不上Nacos”或者“前端请求404”。这篇文章我就把我这次从服务器准备到服务上线的完整过程结合踩过的坑和优化点从头到尾捋一遍。目标是让你看完之后能拿着一台干净的Linux服务器独立完成一套高可用的RuoYi-Cloud生产级部署并且理解每一个步骤背后的“为什么”。RuoYi-Cloud是一个基于Spring Cloud Alibaba的企业级微服务快速开发平台它包含了用户管理、角色权限、菜单管理等后台系统的核心功能模块。部署它不仅仅是执行几条安装命令更涉及到微服务各组件的协同、网络规划、资源配置和后期维护的考量。这次我们部署的版本后端服务会注册到Nacos通过Gateway统一网关暴露前端静态资源由Nginx托管并反向代理到网关持久化数据则交给MySQL。这套架构清晰、职责分离是很多中小型项目的首选。2. 部署环境规划与前期准备部署不是上来就敲命令前期的规划直接决定了后续的顺利程度和维护成本。这次我们假设你有一台全新的CentOS 7.x或Ubuntu 20.04 LTS的服务器拥有root或sudo权限。2.1 服务器资源规划对于RuoYi-Cloud的基础版所有核心服务我建议的最低配置是2核4G。如果资源紧张1核2G也能跑起来但可能会比较卡顿尤其是在启动多个Java服务时。内存是关键因为Nacos、Seata、Sentinel这些中间件本身以及多个Spring Boot应用都是“内存大户”。我的配置清单CPU:2核内存:4GB系统盘:50GB (建议SSD)操作系统:CentOS 7.9 Minimal网络:开启80HTTP、443HTTPS、8848Nacos、3306MySQL建议内网访问、6379Redis等端口。注意生产环境务必在防火墙或安全组中严格限制端口访问。例如3306MySQL、6379Redis、8848Nacos控制台这些端口不应该对公网开放只允许内部网络或特定IP访问。我们这里为了演示可能会先放开但你要清楚其中的风险。2.2 软件版本选型与考量版本兼容性是微服务部署的第一道坎。Spring Cloud、Spring Boot、Spring Cloud Alibaba组件之间有着严格的版本对应关系。RuoYi-Cloud的官方文档或代码pom.xml会指明推荐的版本。以下是我这次部署采用的版本这是一个经过验证的稳定组合JDK:1.8 (RuoYi-Cloud通常基于Java 8开发兼容性最好)MySQL:5.7.x (兼容性好社区资源丰富。8.0也可以但需要注意密码加密插件等差异)Redis:5.x 或 6.x (作为缓存和Session存储版本要求相对宽松)Nacos:1.4.x 或 2.0.x (作为服务注册与配置中心。1.x和2.x在架构上有差异RuoYi-Cloud通常适配1.x若用2.x需注意客户端兼容性)Nginx:1.18 (作为Web服务器和反向代理版本较新即可)为什么选择这些版本核心原则是“与项目基准保持一致”。RuoYi-Cloud是一个集成的解决方案其父POM已经定义了整套依赖的版本管理。擅自升级某个核心组件比如把Spring Cloud从Hoxton换成2021.x极有可能引发一系列不可预知的兼容性问题。因此除非有明确的需求和测试否则建议严格按照项目推荐的版本来。2.3 项目源码与数据库准备部署前你需要准备好两样东西编译好的后端Jar包或War包和前端的静态资源文件以及初始化好的数据库。获取项目代码从Gitee或GitHub克隆RuoYi-Cloud的最新稳定版代码。git clone https://gitee.com/y_project/RuoYi-Cloud.git本地编译在本地开发环境如IDEA或一个专门的构建服务器上使用Maven进行编译打包。确保你的Maven配置了阿里云等国内镜像以加速下载。cd RuoYi-Cloud mvn clean package -Dmaven.test.skiptrue编译成功后你会在各子模块的target目录下找到对应的jar文件例如ruoyi-auth/target/ruoyi-auth.jar。将所有这些jar包通常包括ruoyi-gateway,ruoyi-auth,ruoyi-system,ruoyi-file等上传到服务器的某个目录例如/opt/ruoyi-cloud/jar/。前端资源构建进入ruoyi-ui通常是Vue项目目录安装依赖并构建生产环境包。npm install --registryhttps://registry.npmmirror.com # 使用淘宝镜像 npm run build:prod构建完成后会生成一个dist文件夹。将其整个上传到服务器例如/opt/ruoyi-cloud/web/。数据库初始化在服务器的MySQL中创建数据库例如ry-cloud然后执行项目SQL脚本。脚本通常位于sql目录下可能有多个文件注意执行顺序一般是先quartz.sql再ry_xxxx.sql最后ry_config_xxxx.sql。CREATE DATABASE IF NOT EXISTS ry-cloud DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; USE ry-cloud; SOURCE /path/to/your/quartz.sql; SOURCE /path/to/your/ry_2023xxxx.sql;3. 基础服务安装与配置详解基础服务是支撑平台的基石它们的稳定性和配置正确性至关重要。3.1 MySQL安装与安全加固在Linux上安装MySQL我倾向于使用官方仓库或系统包管理器这样便于后续升级和管理。对于CentOS 7:# 1. 下载并安装MySQL官方的Yum仓库 wget https://dev.mysql.com/get/mysql80-community-release-el7-7.noarch.rpm sudo rpm -ivh mysql80-community-release-el7-7.noarch.rpm # 2. 默认启用的是8.0我们需要启用5.7仓库并禁用8.0 sudo yum-config-manager --disable mysql80-community sudo yum-config-manager --enable mysql57-community # 3. 安装MySQL 5.7 sudo yum install -y mysql-community-server # 4. 启动并设置开机自启 sudo systemctl start mysqld sudo systemctl enable mysqld安装完成后MySQL 5.7会为root用户生成一个临时密码位于日志文件中sudo grep temporary password /var/log/mysqld.log使用该密码登录后必须立即修改密码并执行一些基本的安全设置ALTER USER rootlocalhost IDENTIFIED BY YourNewStrongPassword!123; -- 移除匿名用户 DELETE FROM mysql.user WHERE User; -- 禁止root远程登录生产环境建议 DELETE FROM mysql.user WHERE Userroot AND Host NOT IN (localhost, 127.0.0.1, ::1); -- 创建RuoYi专用数据库和用户 CREATE DATABASE ry-cloud DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER ruoyi% IDENTIFIED BY RuoyiPassword123!; GRANT ALL PRIVILEGES ON ry-cloud.* TO ruoyi%; FLUSH PRIVILEGES;实操心得密码策略问题。MySQL 5.7默认启用了validate_password插件要求密码包含大小写字母、数字和特殊字符且长度至少8位。如果你想设置简单密码仅用于测试可以临时降低策略等级但生产环境绝对不推荐。SET GLOBAL validate_password_policyLOW; SET GLOBAL validate_password_length4;3.2 Nginx安装与核心配置Nginx我们将用它做两件事托管前端静态文件dist目录以及作为反向代理将API请求转发到后端的Gateway。安装Nginx (CentOS 7):sudo yum install -y epel-release sudo yum install -y nginx sudo systemctl start nginx sudo systemctl enable nginx安装后默认的网站根目录是/usr/share/nginx/html。我们把之前上传的前端dist文件夹内容放到这里或者放到其他自定义目录。我更喜欢自定义目录便于管理。放置前端文件sudo mkdir -p /opt/ruoyi-cloud/web # 假设你的dist文件夹内容已上传到服务器临时目录 sudo cp -r /tmp/dist/* /opt/ruoyi-cloud/web/ sudo chown -R nginx:nginx /opt/ruoyi-cloud/web # 修改属主让Nginx有读取权限配置Nginx站点编辑Nginx配置文件通常主配置在/etc/nginx/nginx.conf但最佳实践是在/etc/nginx/conf.d/下为每个站点创建独立的.conf文件。sudo vim /etc/nginx/conf.d/ruoyi-cloud.conf写入以下配置server { listen 80; server_name your-domain.com; # 你的域名或服务器IP # 前端静态资源 location / { root /opt/ruoyi-cloud/web; index index.html index.htm; try_files $uri $uri/ /index.html; # 支持Vue Router的history模式 } # 后端API反向代理 location /prod-api/ { # 注意RuoYi前端默认请求前缀是/prod-api/ proxy_pass http://127.0.0.1:8080/; # 转发到Gateway的端口 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_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } # 可选静态资源缓存优化 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control public, immutable; } }这个配置是关键。location /prod-api/意味着所有以/prod-api/开头的请求即前端发起的API调用都会被Nginx转发到本机8080端口Gateway服务。而try_files $uri $uri/ /index.html;这行是Vue等单页面应用SPA在history路由模式下的必备配置它保证了直接访问子路由或刷新页面时不会返回404。测试并重载配置sudo nginx -t # 测试配置文件语法 sudo systemctl reload nginx # 平滑重载配置现在访问你的服务器IP或域名应该能看到RuoYi的前端登录页面了但所有API请求都会失败因为后端服务还没启动。3.3 Redis快速安装Redis作为缓存和Session存储安装相对简单。# CentOS 7 sudo yum install -y redis sudo systemctl start redis sudo systemctl enable redis安装后默认配置基本可用监听127.0.0.1端口6379。如果需要远程访问或修改密码需要编辑/etc/redis.conf找到bind 127.0.0.1和# requirepass foobared进行修改并重启Redis服务。生产环境务必设置强密码并限制访问IP。4. 微服务组件部署与联调这是部署的核心环节微服务组件之间的网络连通性和配置正确性决定了系统能否正常运行。4.1 Nacos部署与数据库模式配置Nacos是服务注册和配置中心。我们将其以单机模式运行但使用外置的MySQL数据库而不是默认的内嵌数据库这样数据更持久也方便管理。下载与解压cd /opt wget https://github.com/alibaba/nacos/releases/download/1.4.3/nacos-server-1.4.3.tar.gz tar -zxvf nacos-server-1.4.3.tar.gz mv nacos /opt/初始化数据库在之前创建的ry-cloud数据库中执行Nacos的初始化SQL脚本。脚本位于/opt/nacos/conf/nacos-mysql.sql。mysql -u root -p ry-cloud /opt/nacos/conf/nacos-mysql.sql配置数据库连接编辑Nacos的配置文件。vim /opt/nacos/conf/application.properties找到数据库配置部分修改为你的MySQL信息# 启用数据库 spring.datasource.platformmysql # 数据库实例数量 db.num1 db.url.0jdbc:mysql://127.0.0.1:3306/ry-cloud?characterEncodingutf8connectTimeout1000socketTimeout3000autoReconnecttrueuseUnicodetrueuseSSLfalseserverTimezoneUTC db.user.0ruoyi db.password.0RuoyiPassword123!注意这里连接的是我们为RuoYi创建的ry-cloud数据库因为我们将Nacos的表也放在了同一个库中方便管理。你也可以为Nacos创建单独的数据库。启动Nacoscd /opt/nacos/bin sh startup.sh -m standalone # 单机模式启动启动后访问http://你的服务器IP:8848/nacos默认账号密码是nacos/nacos。登录后你应该能在“配置管理”和“服务管理”菜单中看到RuoYi-Cloud相关的一些默认配置如果导入了配置的话和即将注册的服务。4.2 后端微服务启动与配置现在开始启动各个业务微服务。每个服务都是一个独立的Spring Boot应用。准备启动脚本在存放jar包的目录如/opt/ruoyi-cloud/jar/下为每个服务编写简单的启动脚本start-xxx.sh方便管理和维护。以ruoyi-gateway为例#!/bin/bash APP_NAMEruoyi-gateway.jar # 使用项目配置文件优先级最高 CONFIG_LOCATIONfile:/opt/ruoyi-cloud/config/ # JVM参数根据服务器内存调整 JVM_OPTS-Xms512m -Xmx512m -XX:MetaspaceSize128m -XX:MaxMetaspaceSize256m nohup java $JVM_OPTS -Dspring.config.additional-location$CONFIG_LOCATION -jar $APP_NAME ./gateway.log 21 echo $APP_NAME 启动中日志输出到 gateway.log关键参数-Dspring.config.additional-location指定了外部配置文件的位置。我们将所有服务的公共配置如Nacos地址、Redis地址提取到/opt/ruoyi-cloud/config/目录下实现配置与代码分离。创建公共配置文件在/opt/ruoyi-cloud/config/目录下创建bootstrap.yml或bootstrap.properties这是Spring Cloud应用的引导配置文件优先级很高。# /opt/ruoyi-cloud/config/bootstrap.yml spring: application: name: 服务名各服务脚本中通过-D参数传入或使用各自配置 cloud: nacos: discovery: server-addr: 127.0.0.1:8848 # Nacos服务地址 config: server-addr: 127.0.0.1:8848 file-extension: yaml group: DEFAULT_GROUP namespace: # 默认public命名空间可不填 # Redis配置如果各服务共用 redis: host: 127.0.0.1 port: 6379 password: # 如果Redis设置了密码 database: 0同时你需要在Nacos控制台创建或导入各个服务对应的配置文件例如ruoyi-gateway.yaml内容包含该服务特有的配置如端口号、数据库连接等。RuoYi-Cloud项目通常提供了示例配置文件。启动顺序与依赖微服务启动有依赖顺序。通常先启动基础设施服务再启动业务服务。第一步确保Nacos、MySQL、Redis已正常运行。第二步启动认证中心ruoyi-auth。因为Gateway和其他业务服务可能需要调用它进行鉴权。第三步启动网关ruoyi-gateway。第四步启动其他业务服务如ruoyi-system,ruoyi-file等。 执行你写好的启动脚本cd /opt/ruoyi-cloud/jar chmod x *.sh ./start-auth.sh ./start-gateway.sh ./start-system.sh # ... 启动其他服务检查服务状态启动后立即查看日志确认没有报错。tail -f /opt/ruoyi-cloud/jar/gateway.log同时刷新Nacos控制台的服务列表你应该能看到ruoyi-gateway、ruoyi-auth、ruoyi-system等服务已经成功注册。4.3 前端与后端联调测试当所有后端服务启动并注册到Nacos后我们就可以进行联调测试了。验证网关路由首先直接测试Gateway是否工作。Gateway的默认端口可能是8080具体看ruoyi-gateway的配置。curl http://127.0.0.1:8080/如果Gateway正常运行可能会返回一个默认的响应或404这没关系。关键是测试一个已知的路由比如获取验证码的接口如果RuoYi-Cloud有提供curl http://127.0.0.1:8080/auth/captchaImage你应该能收到一个JSON响应。验证Nginx反向代理这是最关键的一步。通过浏览器访问你的服务器IP或域名前端页面。打开浏览器的开发者工具F12切换到“网络”(Network)选项卡。尝试登录操作。观察请求你会发现前端发起的API请求其URL前缀是/prod-api/例如http://your-domain.com/prod-api/auth/login。请求流程这个请求被Nginx接收监听80端口根据我们之前的配置/prod-api/路径的请求被转发到了http://127.0.0.1:8080/。Nginx会将/prod-api/auth/login转发给GatewayGateway收到的是/auth/login因为Nginx配置的proxy_pass末尾带/会去除匹配的路径前缀/prod-api。Gateway再根据自身的路由规则将这个请求路由到ruoyi-auth服务真正的/auth/login端点。成功标志如果登录成功并且能正常跳转到后台首页获取菜单、用户信息等后续接口都返回200状态码说明整个链路浏览器 - Nginx - Gateway - 微服务已经完全打通。5. 部署过程常见问题与深度排查在实际部署中几乎一定会遇到问题。这里我总结几个最典型的问题和排查思路。5.1 服务无法注册到Nacos这是最常见的问题。现象服务启动日志没有报错但在Nacos控制台看不到服务实例。排查步骤检查网络连通性在运行微服务的服务器上执行telnet 127.0.0.1 8848或curl http://127.0.0.1:8848/nacos/确保能访问Nacos。如果Nacos在其他机器请检查防火墙和安全组规则。检查Nacos配置确认服务的bootstrap.yml或application.yml中spring.cloud.nacos.discovery.server-addr的地址和端口完全正确。特别注意YAML格式的缩进。检查服务配置确认服务的spring.application.name是否设置且Nacos上存在对应名称的配置文件如果需要动态配置。RuoYi-Cloud的服务名通常是ruoyi-auth、ruoyi-gateway这种格式。查看服务启动日志仔细查看服务启动日志的前几十行搜索“Nacos”关键词。常见的错误有连接拒绝Connection refused。说明地址端口不对或Nacos没启动。命名空间不存在namespace not exist。检查spring.cloud.nacos.discovery.namespace配置。权限问题如果Nacos开启了认证需要在配置中添加用户名和密码。检查客户端版本确保项目中spring-cloud-alibaba-dependencies的版本与Nacos服务端版本兼容。这是一个深坑版本不匹配可能导致注册行为异常。5.2 前端访问API返回404或502404 Not Found检查Nginx配置确认location /prod-api/的proxy_pass地址是否正确Gateway的IP和端口。检查Gateway路由登录Nacos查看ruoyi-gateway服务的路由配置通常是一个叫gateway-router.json的配置项。确认路由规则是否将请求正确转发到了后端服务如ruoyi-auth。检查后端服务确认对应的后端服务如ruoyi-auth已经健康地注册在Nacos中并且其提供的API路径与Gateway路由配置的路径匹配。502 Bad Gateway这通常意味着Nginx能够接收请求但无法连接到上游服务器Gateway。检查Gateway进程使用ps -ef | grep ruoyi-gateway和netstat -tlnp | grep :8080假设端口8080确认Gateway进程存活且正在监听端口。检查防火墙确认服务器本地的防火墙如firewalld没有阻止Nginx运行在用户空间访问本地的8080端口。有时需要将端口加入信任列表或直接关闭防火墙仅测试环境。检查Gateway日志查看Gateway的日志文件看是否有启动失败或运行时异常。5.3 数据库连接失败服务启动时报错Communications link failure或Access denied for user。确认数据库服务systemctl status mysqld确保MySQL正在运行。验证连接信息在服务器上直接用命令行工具测试连接。mysql -h 127.0.0.1 -P 3306 -u ruoyi -p输入密码看能否成功连接并访问ry-cloud数据库。检查用户权限确认你为RuoYi创建的用户如ruoyi具有从应用服务器IP或%访问ry-cloud数据库的所有权限。检查MySQL绑定地址如果MySQL和微服务不在同一台机器需要检查MySQL的bind-address配置在my.cnf中默认是127.0.0.1只允许本地连接需要改为0.0.0.0或特定IP并重启MySQL。注意生产环境这样做需要配合严格的防火墙规则。检查时区问题如果连接成功但启动时出现时区错误需要在JDBC连接URL中添加serverTimezoneAsia/Shanghai参数。5.4 配置文件优先级与外部化配置Spring Boot支持多种配置源优先级从高到低。在我们的部署中命令行参数如-Dspring.config.additional-locationSPRING_APPLICATION_JSON环境变量spring.config.additional-location指定的外部配置文件我们用的方式application-{profile}.yml打包在jar内的配置文件application.yml打包在jar内的配置文件为什么我们要用-Dspring.config.additional-location这样做的好处是当需要修改配置比如切换数据库地址、调整Redis连接池大小时我们不需要重新打包和上传整个jar文件只需要修改服务器上/opt/ruoyi-cloud/config/目录下的配置文件然后重启服务即可。这极大地提升了运维效率。一个常见陷阱如果你在外部配置文件和jar包内的配置文件都定义了同一个属性外部配置文件的优先级更高。这可能导致你修改了外部配置却不生效的错觉实际上可能是因为内部配置覆盖了它。务必理清配置的加载顺序。6. 生产环境优化与维护建议基础部署完成只是第一步要让服务稳定运行还需要一些优化措施。6.1 使用systemd管理服务用nohup和脚本启动服务不够规范不利于监控和自动重启。建议为每个微服务创建systemd服务单元文件。以ruoyi-gateway为例创建文件/etc/systemd/system/ruoyi-gateway.service[Unit] DescriptionRuoYi Cloud Gateway Service Afternetwork.target mysqld.service redis.service nacos.service Wantsnetwork.target [Service] Typesimple Userroot WorkingDirectory/opt/ruoyi-cloud/jar ExecStart/usr/bin/java -Xms512m -Xmx512m -Dspring.config.additional-locationfile:/opt/ruoyi-cloud/config/ -jar ruoyi-gateway.jar ExecStop/bin/kill -15 $MAINPID Restartalways RestartSec10 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.target然后就可以用标准的systemctl命令来管理了sudo systemctl daemon-reload sudo systemctl start ruoyi-gateway sudo systemctl enable ruoyi-gateway sudo systemctl status ruoyi-gateway这样做的好处是服务崩溃自动重启Restartalways、集中日志查看journalctl -u ruoyi-gateway、定义服务依赖关系After、方便设置开机自启。6.2 日志收集与监控默认日志输出到各自的.log文件分散且不易分析。日志聚合考虑使用ELKElasticsearch, Logstash, Kibana或轻量级的Loki Grafana来收集所有服务的日志进行集中存储、搜索和可视化。基础监控至少监控服务器的CPU、内存、磁盘IO和网络流量。可以使用node_exporter Prometheus Grafana这套经典组合。对于JVM可以开启JMX或使用Micrometer将指标暴露给Prometheus。健康检查Spring Boot Actuator提供了/actuator/health端点。确保在Nginx或Gateway层配置健康检查自动剔除不健康的服务实例。6.3 备份与升级策略数据库备份定期如每天对ry-cloud数据库进行全量备份可以使用mysqldump命令并结合cron定时任务。mysqldump -u root -p ry-cloud /backup/ry-cloud-$(date %Y%m%d).sql配置文件备份将/opt/ruoyi-cloud/config/目录和各个服务的systemd单元文件纳入版本控制如Git或定期备份。升级流程1) 备份数据库和当前运行的服务包。2) 在测试环境验证新版本。3) 生产环境采用蓝绿部署或滚动更新先部署新版本服务到少数节点通过网关权重配置将少量流量导入新版本验证无误后再逐步替换所有旧节点。利用Nacos的服务发现可以做到无缝切换。部署一套完整的微服务系统就像搭积木每一块都必须严丝合缝。从Linux基础环境准备到MySQL、Nginx、Redis等中间件的安装配置再到Nacos的部署与微服务的启动联调每一步都需要耐心和细心。这次部署RuoYi-Cloud的经历让我再次深刻体会到“配置大于编码”的道理尤其是在微服务领域。很多问题不是代码bug而是环境、网络、配置文件的细微差别导致的。希望这篇超过五千字的详细记录能帮你避开我踩过的那些坑顺利搭建起属于自己的微服务平台。记住部署完成后用systemctl管理服务、规划好日志和监控、建立备份习惯才是长期稳定运行的开始。
RuoYi-Cloud微服务生产环境部署实战：从Linux到Nginx全链路配置
1. 项目概述与核心价值最近在帮一个朋友的公司做技术架构升级他们之前用的是单体版的RuoYi随着业务量上来单服务扛不住决定迁移到微服务架构的RuoYi-Cloud。我负责整个生产环境的部署落地选型就是最经典的Linux MySQL Nginx组合。这个组合听起来老生常谈但真要在生产环境里把它调顺了从零开始走一遍里头的门道可不少。网上教程很多但要么是纯命令罗列要么就是跳过了关键配置照着做十有八九会卡在某个环节比如最经典的“服务注册不上Nacos”或者“前端请求404”。这篇文章我就把我这次从服务器准备到服务上线的完整过程结合踩过的坑和优化点从头到尾捋一遍。目标是让你看完之后能拿着一台干净的Linux服务器独立完成一套高可用的RuoYi-Cloud生产级部署并且理解每一个步骤背后的“为什么”。RuoYi-Cloud是一个基于Spring Cloud Alibaba的企业级微服务快速开发平台它包含了用户管理、角色权限、菜单管理等后台系统的核心功能模块。部署它不仅仅是执行几条安装命令更涉及到微服务各组件的协同、网络规划、资源配置和后期维护的考量。这次我们部署的版本后端服务会注册到Nacos通过Gateway统一网关暴露前端静态资源由Nginx托管并反向代理到网关持久化数据则交给MySQL。这套架构清晰、职责分离是很多中小型项目的首选。2. 部署环境规划与前期准备部署不是上来就敲命令前期的规划直接决定了后续的顺利程度和维护成本。这次我们假设你有一台全新的CentOS 7.x或Ubuntu 20.04 LTS的服务器拥有root或sudo权限。2.1 服务器资源规划对于RuoYi-Cloud的基础版所有核心服务我建议的最低配置是2核4G。如果资源紧张1核2G也能跑起来但可能会比较卡顿尤其是在启动多个Java服务时。内存是关键因为Nacos、Seata、Sentinel这些中间件本身以及多个Spring Boot应用都是“内存大户”。我的配置清单CPU:2核内存:4GB系统盘:50GB (建议SSD)操作系统:CentOS 7.9 Minimal网络:开启80HTTP、443HTTPS、8848Nacos、3306MySQL建议内网访问、6379Redis等端口。注意生产环境务必在防火墙或安全组中严格限制端口访问。例如3306MySQL、6379Redis、8848Nacos控制台这些端口不应该对公网开放只允许内部网络或特定IP访问。我们这里为了演示可能会先放开但你要清楚其中的风险。2.2 软件版本选型与考量版本兼容性是微服务部署的第一道坎。Spring Cloud、Spring Boot、Spring Cloud Alibaba组件之间有着严格的版本对应关系。RuoYi-Cloud的官方文档或代码pom.xml会指明推荐的版本。以下是我这次部署采用的版本这是一个经过验证的稳定组合JDK:1.8 (RuoYi-Cloud通常基于Java 8开发兼容性最好)MySQL:5.7.x (兼容性好社区资源丰富。8.0也可以但需要注意密码加密插件等差异)Redis:5.x 或 6.x (作为缓存和Session存储版本要求相对宽松)Nacos:1.4.x 或 2.0.x (作为服务注册与配置中心。1.x和2.x在架构上有差异RuoYi-Cloud通常适配1.x若用2.x需注意客户端兼容性)Nginx:1.18 (作为Web服务器和反向代理版本较新即可)为什么选择这些版本核心原则是“与项目基准保持一致”。RuoYi-Cloud是一个集成的解决方案其父POM已经定义了整套依赖的版本管理。擅自升级某个核心组件比如把Spring Cloud从Hoxton换成2021.x极有可能引发一系列不可预知的兼容性问题。因此除非有明确的需求和测试否则建议严格按照项目推荐的版本来。2.3 项目源码与数据库准备部署前你需要准备好两样东西编译好的后端Jar包或War包和前端的静态资源文件以及初始化好的数据库。获取项目代码从Gitee或GitHub克隆RuoYi-Cloud的最新稳定版代码。git clone https://gitee.com/y_project/RuoYi-Cloud.git本地编译在本地开发环境如IDEA或一个专门的构建服务器上使用Maven进行编译打包。确保你的Maven配置了阿里云等国内镜像以加速下载。cd RuoYi-Cloud mvn clean package -Dmaven.test.skiptrue编译成功后你会在各子模块的target目录下找到对应的jar文件例如ruoyi-auth/target/ruoyi-auth.jar。将所有这些jar包通常包括ruoyi-gateway,ruoyi-auth,ruoyi-system,ruoyi-file等上传到服务器的某个目录例如/opt/ruoyi-cloud/jar/。前端资源构建进入ruoyi-ui通常是Vue项目目录安装依赖并构建生产环境包。npm install --registryhttps://registry.npmmirror.com # 使用淘宝镜像 npm run build:prod构建完成后会生成一个dist文件夹。将其整个上传到服务器例如/opt/ruoyi-cloud/web/。数据库初始化在服务器的MySQL中创建数据库例如ry-cloud然后执行项目SQL脚本。脚本通常位于sql目录下可能有多个文件注意执行顺序一般是先quartz.sql再ry_xxxx.sql最后ry_config_xxxx.sql。CREATE DATABASE IF NOT EXISTS ry-cloud DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; USE ry-cloud; SOURCE /path/to/your/quartz.sql; SOURCE /path/to/your/ry_2023xxxx.sql;3. 基础服务安装与配置详解基础服务是支撑平台的基石它们的稳定性和配置正确性至关重要。3.1 MySQL安装与安全加固在Linux上安装MySQL我倾向于使用官方仓库或系统包管理器这样便于后续升级和管理。对于CentOS 7:# 1. 下载并安装MySQL官方的Yum仓库 wget https://dev.mysql.com/get/mysql80-community-release-el7-7.noarch.rpm sudo rpm -ivh mysql80-community-release-el7-7.noarch.rpm # 2. 默认启用的是8.0我们需要启用5.7仓库并禁用8.0 sudo yum-config-manager --disable mysql80-community sudo yum-config-manager --enable mysql57-community # 3. 安装MySQL 5.7 sudo yum install -y mysql-community-server # 4. 启动并设置开机自启 sudo systemctl start mysqld sudo systemctl enable mysqld安装完成后MySQL 5.7会为root用户生成一个临时密码位于日志文件中sudo grep temporary password /var/log/mysqld.log使用该密码登录后必须立即修改密码并执行一些基本的安全设置ALTER USER rootlocalhost IDENTIFIED BY YourNewStrongPassword!123; -- 移除匿名用户 DELETE FROM mysql.user WHERE User; -- 禁止root远程登录生产环境建议 DELETE FROM mysql.user WHERE Userroot AND Host NOT IN (localhost, 127.0.0.1, ::1); -- 创建RuoYi专用数据库和用户 CREATE DATABASE ry-cloud DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER ruoyi% IDENTIFIED BY RuoyiPassword123!; GRANT ALL PRIVILEGES ON ry-cloud.* TO ruoyi%; FLUSH PRIVILEGES;实操心得密码策略问题。MySQL 5.7默认启用了validate_password插件要求密码包含大小写字母、数字和特殊字符且长度至少8位。如果你想设置简单密码仅用于测试可以临时降低策略等级但生产环境绝对不推荐。SET GLOBAL validate_password_policyLOW; SET GLOBAL validate_password_length4;3.2 Nginx安装与核心配置Nginx我们将用它做两件事托管前端静态文件dist目录以及作为反向代理将API请求转发到后端的Gateway。安装Nginx (CentOS 7):sudo yum install -y epel-release sudo yum install -y nginx sudo systemctl start nginx sudo systemctl enable nginx安装后默认的网站根目录是/usr/share/nginx/html。我们把之前上传的前端dist文件夹内容放到这里或者放到其他自定义目录。我更喜欢自定义目录便于管理。放置前端文件sudo mkdir -p /opt/ruoyi-cloud/web # 假设你的dist文件夹内容已上传到服务器临时目录 sudo cp -r /tmp/dist/* /opt/ruoyi-cloud/web/ sudo chown -R nginx:nginx /opt/ruoyi-cloud/web # 修改属主让Nginx有读取权限配置Nginx站点编辑Nginx配置文件通常主配置在/etc/nginx/nginx.conf但最佳实践是在/etc/nginx/conf.d/下为每个站点创建独立的.conf文件。sudo vim /etc/nginx/conf.d/ruoyi-cloud.conf写入以下配置server { listen 80; server_name your-domain.com; # 你的域名或服务器IP # 前端静态资源 location / { root /opt/ruoyi-cloud/web; index index.html index.htm; try_files $uri $uri/ /index.html; # 支持Vue Router的history模式 } # 后端API反向代理 location /prod-api/ { # 注意RuoYi前端默认请求前缀是/prod-api/ proxy_pass http://127.0.0.1:8080/; # 转发到Gateway的端口 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_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } # 可选静态资源缓存优化 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control public, immutable; } }这个配置是关键。location /prod-api/意味着所有以/prod-api/开头的请求即前端发起的API调用都会被Nginx转发到本机8080端口Gateway服务。而try_files $uri $uri/ /index.html;这行是Vue等单页面应用SPA在history路由模式下的必备配置它保证了直接访问子路由或刷新页面时不会返回404。测试并重载配置sudo nginx -t # 测试配置文件语法 sudo systemctl reload nginx # 平滑重载配置现在访问你的服务器IP或域名应该能看到RuoYi的前端登录页面了但所有API请求都会失败因为后端服务还没启动。3.3 Redis快速安装Redis作为缓存和Session存储安装相对简单。# CentOS 7 sudo yum install -y redis sudo systemctl start redis sudo systemctl enable redis安装后默认配置基本可用监听127.0.0.1端口6379。如果需要远程访问或修改密码需要编辑/etc/redis.conf找到bind 127.0.0.1和# requirepass foobared进行修改并重启Redis服务。生产环境务必设置强密码并限制访问IP。4. 微服务组件部署与联调这是部署的核心环节微服务组件之间的网络连通性和配置正确性决定了系统能否正常运行。4.1 Nacos部署与数据库模式配置Nacos是服务注册和配置中心。我们将其以单机模式运行但使用外置的MySQL数据库而不是默认的内嵌数据库这样数据更持久也方便管理。下载与解压cd /opt wget https://github.com/alibaba/nacos/releases/download/1.4.3/nacos-server-1.4.3.tar.gz tar -zxvf nacos-server-1.4.3.tar.gz mv nacos /opt/初始化数据库在之前创建的ry-cloud数据库中执行Nacos的初始化SQL脚本。脚本位于/opt/nacos/conf/nacos-mysql.sql。mysql -u root -p ry-cloud /opt/nacos/conf/nacos-mysql.sql配置数据库连接编辑Nacos的配置文件。vim /opt/nacos/conf/application.properties找到数据库配置部分修改为你的MySQL信息# 启用数据库 spring.datasource.platformmysql # 数据库实例数量 db.num1 db.url.0jdbc:mysql://127.0.0.1:3306/ry-cloud?characterEncodingutf8connectTimeout1000socketTimeout3000autoReconnecttrueuseUnicodetrueuseSSLfalseserverTimezoneUTC db.user.0ruoyi db.password.0RuoyiPassword123!注意这里连接的是我们为RuoYi创建的ry-cloud数据库因为我们将Nacos的表也放在了同一个库中方便管理。你也可以为Nacos创建单独的数据库。启动Nacoscd /opt/nacos/bin sh startup.sh -m standalone # 单机模式启动启动后访问http://你的服务器IP:8848/nacos默认账号密码是nacos/nacos。登录后你应该能在“配置管理”和“服务管理”菜单中看到RuoYi-Cloud相关的一些默认配置如果导入了配置的话和即将注册的服务。4.2 后端微服务启动与配置现在开始启动各个业务微服务。每个服务都是一个独立的Spring Boot应用。准备启动脚本在存放jar包的目录如/opt/ruoyi-cloud/jar/下为每个服务编写简单的启动脚本start-xxx.sh方便管理和维护。以ruoyi-gateway为例#!/bin/bash APP_NAMEruoyi-gateway.jar # 使用项目配置文件优先级最高 CONFIG_LOCATIONfile:/opt/ruoyi-cloud/config/ # JVM参数根据服务器内存调整 JVM_OPTS-Xms512m -Xmx512m -XX:MetaspaceSize128m -XX:MaxMetaspaceSize256m nohup java $JVM_OPTS -Dspring.config.additional-location$CONFIG_LOCATION -jar $APP_NAME ./gateway.log 21 echo $APP_NAME 启动中日志输出到 gateway.log关键参数-Dspring.config.additional-location指定了外部配置文件的位置。我们将所有服务的公共配置如Nacos地址、Redis地址提取到/opt/ruoyi-cloud/config/目录下实现配置与代码分离。创建公共配置文件在/opt/ruoyi-cloud/config/目录下创建bootstrap.yml或bootstrap.properties这是Spring Cloud应用的引导配置文件优先级很高。# /opt/ruoyi-cloud/config/bootstrap.yml spring: application: name: 服务名各服务脚本中通过-D参数传入或使用各自配置 cloud: nacos: discovery: server-addr: 127.0.0.1:8848 # Nacos服务地址 config: server-addr: 127.0.0.1:8848 file-extension: yaml group: DEFAULT_GROUP namespace: # 默认public命名空间可不填 # Redis配置如果各服务共用 redis: host: 127.0.0.1 port: 6379 password: # 如果Redis设置了密码 database: 0同时你需要在Nacos控制台创建或导入各个服务对应的配置文件例如ruoyi-gateway.yaml内容包含该服务特有的配置如端口号、数据库连接等。RuoYi-Cloud项目通常提供了示例配置文件。启动顺序与依赖微服务启动有依赖顺序。通常先启动基础设施服务再启动业务服务。第一步确保Nacos、MySQL、Redis已正常运行。第二步启动认证中心ruoyi-auth。因为Gateway和其他业务服务可能需要调用它进行鉴权。第三步启动网关ruoyi-gateway。第四步启动其他业务服务如ruoyi-system,ruoyi-file等。 执行你写好的启动脚本cd /opt/ruoyi-cloud/jar chmod x *.sh ./start-auth.sh ./start-gateway.sh ./start-system.sh # ... 启动其他服务检查服务状态启动后立即查看日志确认没有报错。tail -f /opt/ruoyi-cloud/jar/gateway.log同时刷新Nacos控制台的服务列表你应该能看到ruoyi-gateway、ruoyi-auth、ruoyi-system等服务已经成功注册。4.3 前端与后端联调测试当所有后端服务启动并注册到Nacos后我们就可以进行联调测试了。验证网关路由首先直接测试Gateway是否工作。Gateway的默认端口可能是8080具体看ruoyi-gateway的配置。curl http://127.0.0.1:8080/如果Gateway正常运行可能会返回一个默认的响应或404这没关系。关键是测试一个已知的路由比如获取验证码的接口如果RuoYi-Cloud有提供curl http://127.0.0.1:8080/auth/captchaImage你应该能收到一个JSON响应。验证Nginx反向代理这是最关键的一步。通过浏览器访问你的服务器IP或域名前端页面。打开浏览器的开发者工具F12切换到“网络”(Network)选项卡。尝试登录操作。观察请求你会发现前端发起的API请求其URL前缀是/prod-api/例如http://your-domain.com/prod-api/auth/login。请求流程这个请求被Nginx接收监听80端口根据我们之前的配置/prod-api/路径的请求被转发到了http://127.0.0.1:8080/。Nginx会将/prod-api/auth/login转发给GatewayGateway收到的是/auth/login因为Nginx配置的proxy_pass末尾带/会去除匹配的路径前缀/prod-api。Gateway再根据自身的路由规则将这个请求路由到ruoyi-auth服务真正的/auth/login端点。成功标志如果登录成功并且能正常跳转到后台首页获取菜单、用户信息等后续接口都返回200状态码说明整个链路浏览器 - Nginx - Gateway - 微服务已经完全打通。5. 部署过程常见问题与深度排查在实际部署中几乎一定会遇到问题。这里我总结几个最典型的问题和排查思路。5.1 服务无法注册到Nacos这是最常见的问题。现象服务启动日志没有报错但在Nacos控制台看不到服务实例。排查步骤检查网络连通性在运行微服务的服务器上执行telnet 127.0.0.1 8848或curl http://127.0.0.1:8848/nacos/确保能访问Nacos。如果Nacos在其他机器请检查防火墙和安全组规则。检查Nacos配置确认服务的bootstrap.yml或application.yml中spring.cloud.nacos.discovery.server-addr的地址和端口完全正确。特别注意YAML格式的缩进。检查服务配置确认服务的spring.application.name是否设置且Nacos上存在对应名称的配置文件如果需要动态配置。RuoYi-Cloud的服务名通常是ruoyi-auth、ruoyi-gateway这种格式。查看服务启动日志仔细查看服务启动日志的前几十行搜索“Nacos”关键词。常见的错误有连接拒绝Connection refused。说明地址端口不对或Nacos没启动。命名空间不存在namespace not exist。检查spring.cloud.nacos.discovery.namespace配置。权限问题如果Nacos开启了认证需要在配置中添加用户名和密码。检查客户端版本确保项目中spring-cloud-alibaba-dependencies的版本与Nacos服务端版本兼容。这是一个深坑版本不匹配可能导致注册行为异常。5.2 前端访问API返回404或502404 Not Found检查Nginx配置确认location /prod-api/的proxy_pass地址是否正确Gateway的IP和端口。检查Gateway路由登录Nacos查看ruoyi-gateway服务的路由配置通常是一个叫gateway-router.json的配置项。确认路由规则是否将请求正确转发到了后端服务如ruoyi-auth。检查后端服务确认对应的后端服务如ruoyi-auth已经健康地注册在Nacos中并且其提供的API路径与Gateway路由配置的路径匹配。502 Bad Gateway这通常意味着Nginx能够接收请求但无法连接到上游服务器Gateway。检查Gateway进程使用ps -ef | grep ruoyi-gateway和netstat -tlnp | grep :8080假设端口8080确认Gateway进程存活且正在监听端口。检查防火墙确认服务器本地的防火墙如firewalld没有阻止Nginx运行在用户空间访问本地的8080端口。有时需要将端口加入信任列表或直接关闭防火墙仅测试环境。检查Gateway日志查看Gateway的日志文件看是否有启动失败或运行时异常。5.3 数据库连接失败服务启动时报错Communications link failure或Access denied for user。确认数据库服务systemctl status mysqld确保MySQL正在运行。验证连接信息在服务器上直接用命令行工具测试连接。mysql -h 127.0.0.1 -P 3306 -u ruoyi -p输入密码看能否成功连接并访问ry-cloud数据库。检查用户权限确认你为RuoYi创建的用户如ruoyi具有从应用服务器IP或%访问ry-cloud数据库的所有权限。检查MySQL绑定地址如果MySQL和微服务不在同一台机器需要检查MySQL的bind-address配置在my.cnf中默认是127.0.0.1只允许本地连接需要改为0.0.0.0或特定IP并重启MySQL。注意生产环境这样做需要配合严格的防火墙规则。检查时区问题如果连接成功但启动时出现时区错误需要在JDBC连接URL中添加serverTimezoneAsia/Shanghai参数。5.4 配置文件优先级与外部化配置Spring Boot支持多种配置源优先级从高到低。在我们的部署中命令行参数如-Dspring.config.additional-locationSPRING_APPLICATION_JSON环境变量spring.config.additional-location指定的外部配置文件我们用的方式application-{profile}.yml打包在jar内的配置文件application.yml打包在jar内的配置文件为什么我们要用-Dspring.config.additional-location这样做的好处是当需要修改配置比如切换数据库地址、调整Redis连接池大小时我们不需要重新打包和上传整个jar文件只需要修改服务器上/opt/ruoyi-cloud/config/目录下的配置文件然后重启服务即可。这极大地提升了运维效率。一个常见陷阱如果你在外部配置文件和jar包内的配置文件都定义了同一个属性外部配置文件的优先级更高。这可能导致你修改了外部配置却不生效的错觉实际上可能是因为内部配置覆盖了它。务必理清配置的加载顺序。6. 生产环境优化与维护建议基础部署完成只是第一步要让服务稳定运行还需要一些优化措施。6.1 使用systemd管理服务用nohup和脚本启动服务不够规范不利于监控和自动重启。建议为每个微服务创建systemd服务单元文件。以ruoyi-gateway为例创建文件/etc/systemd/system/ruoyi-gateway.service[Unit] DescriptionRuoYi Cloud Gateway Service Afternetwork.target mysqld.service redis.service nacos.service Wantsnetwork.target [Service] Typesimple Userroot WorkingDirectory/opt/ruoyi-cloud/jar ExecStart/usr/bin/java -Xms512m -Xmx512m -Dspring.config.additional-locationfile:/opt/ruoyi-cloud/config/ -jar ruoyi-gateway.jar ExecStop/bin/kill -15 $MAINPID Restartalways RestartSec10 StandardOutputjournal StandardErrorjournal [Install] WantedBymulti-user.target然后就可以用标准的systemctl命令来管理了sudo systemctl daemon-reload sudo systemctl start ruoyi-gateway sudo systemctl enable ruoyi-gateway sudo systemctl status ruoyi-gateway这样做的好处是服务崩溃自动重启Restartalways、集中日志查看journalctl -u ruoyi-gateway、定义服务依赖关系After、方便设置开机自启。6.2 日志收集与监控默认日志输出到各自的.log文件分散且不易分析。日志聚合考虑使用ELKElasticsearch, Logstash, Kibana或轻量级的Loki Grafana来收集所有服务的日志进行集中存储、搜索和可视化。基础监控至少监控服务器的CPU、内存、磁盘IO和网络流量。可以使用node_exporter Prometheus Grafana这套经典组合。对于JVM可以开启JMX或使用Micrometer将指标暴露给Prometheus。健康检查Spring Boot Actuator提供了/actuator/health端点。确保在Nginx或Gateway层配置健康检查自动剔除不健康的服务实例。6.3 备份与升级策略数据库备份定期如每天对ry-cloud数据库进行全量备份可以使用mysqldump命令并结合cron定时任务。mysqldump -u root -p ry-cloud /backup/ry-cloud-$(date %Y%m%d).sql配置文件备份将/opt/ruoyi-cloud/config/目录和各个服务的systemd单元文件纳入版本控制如Git或定期备份。升级流程1) 备份数据库和当前运行的服务包。2) 在测试环境验证新版本。3) 生产环境采用蓝绿部署或滚动更新先部署新版本服务到少数节点通过网关权重配置将少量流量导入新版本验证无误后再逐步替换所有旧节点。利用Nacos的服务发现可以做到无缝切换。部署一套完整的微服务系统就像搭积木每一块都必须严丝合缝。从Linux基础环境准备到MySQL、Nginx、Redis等中间件的安装配置再到Nacos的部署与微服务的启动联调每一步都需要耐心和细心。这次部署RuoYi-Cloud的经历让我再次深刻体会到“配置大于编码”的道理尤其是在微服务领域。很多问题不是代码bug而是环境、网络、配置文件的细微差别导致的。希望这篇超过五千字的详细记录能帮你避开我踩过的那些坑顺利搭建起属于自己的微服务平台。记住部署完成后用systemctl管理服务、规划好日志和监控、建立备份习惯才是长期稳定运行的开始。
