从零构建Ruoyi-Cloud微服务：Nacos配置与前后端分离实战指南

1. 环境准备搭建Ruoyi-Cloud的基石第一次接触Ruoyi-Cloud时我花了整整两天时间才把环境搭好。不是因为它复杂而是有些细节没注意。现在我把这些经验总结出来帮你省下这个时间。必须安装的组件清单JDK 1.8千万别用更高版本我试过JDK 17各种兼容性问题MySQL 5.78.0版本会有字符集问题Redis 6.x用Docker安装最方便Maven 3.6注意配置阿里云镜像Node.js 14.x前端开发需要Nacos 2.0.4Ruoyi-Cloud 3.x版本专用重要提示所有组件建议安装在本地开发环境不要用远程服务器。我第一次用云服务器部署被网络问题折磨到崩溃。安装MySQL时有个坑要注意必须手动创建ry-cloud和ry-config两个数据库。官方文档没说清楚这两个库缺一不可。建好后按顺序导入ry_2021xxxx.sql主业务数据quartz.sql定时任务可选ry_config_2021xxxx.sqlNacos配置数据Nacos配置最容易被忽略的是端口。除了默认的8848还要开放9848和9849端口。我有次防火墙没配置服务死活注册不上Nacos。2. Nacos配置实战比官方文档更细的指南Nacos是Ruoyi-Cloud的核心但官方文档对配置中心的说明太简略。下面是我整理的完整流程2.1 持久化配置找到Nacos的conf/application.properties加入MySQL配置spring.datasource.platformmysql db.num1 db.url.0jdbc:mysql://localhost:3306/ry-config?useUnicodetruecharacterEncodingUTF-8 db.userroot db.passwordyour_password这里有个隐藏坑点MySQL必须用5.7版本。我用MySQL 8.0时Nacos启动报错原因是驱动不兼容。2.2 服务注册验证启动Nacos后访问http://localhost:8848/nacos应该看到这样的界面左侧菜单有配置管理和服务管理服务列表包含ruoyi-gateway等默认服务如果看不到按这个顺序排查检查MySQL的ry-config库是否导入成功查看Nacos日志是否有数据库连接错误确认端口8848/9848/9849全部开放3. 前后端协同开发避坑指南3.1 后端启动顺序虽然官方说模块启动没有顺序但实测这个顺序最稳定RuoYiGatewayApplication网关RuoYiAuthApplication认证RuoYiSystemApplication系统模块其他可选模块启动时注意控制台日志看到Started RuoYiGatewayApplication in xx seconds才算成功出现Connection refused多半是Nacos没连上3.2 前端运行技巧进入ruoyi-ui目录后别直接用npm installnpm config set registry https://registry.npmmirror.com npm install --legacy-peer-deps npm run dev踩坑记录用cnpm会导致热更新失效用官方源又慢到怀疑人生。阿里云镜像是最佳选择。浏览器访问http://localhost:80时如果白屏请检查查看控制台是否有404错误确认后端网关是否正常运行检查vue.config.js中的proxy配置4. 扩展微服务模块手把手教学以新建ruoyi-order模块为例演示完整流程4.1 创建模块结构在ruoyi-modules下新建ruoyi-order复制ruoyi-system的pom.xml修改artifactIdruoyi-order/artifactId description订单服务模块/description4.2 关键配置bootstrap.yml示例server: port: 9080 # 避免与其他模块冲突 spring: application: name: ruoyi-order profiles: active: dev cloud: nacos: discovery: server-addr: 127.0.0.1:8848 config: server-addr: 127.0.0.1:8848 file-extension: yml4.3 Nacos配置新增在ry-config.config_info表插入新记录INSERT INTO config_info VALUES (11, ruoyi-order-dev.yml, DEFAULT_GROUP, spring: redis: host: localhost port: 6379 datasource: druid: master: url: jdbc:mysql://localhost:3306/ry-order?useSSLfalse username: root password: 123456 mybatis: typeAliasesPackage: com.ruoyi.order mapperLocations: classpath:mapper/**/*.xml , xxxxxx, now(), now(), nacos, 127.0.0.1, , , 订单服务配置);4.4 接口开发技巧模仿SysUserController写订单接口时注意RestController注解方法上要加PreAuthorize权限控制返回结果统一用AjaxResult测试时先用Postman调用/auth/login获取token再在Header中添加Authorization: Bearer xxxx-token-xxxx5. 常见问题解决方案问题1Nacos服务列表为空检查bootstrap.yml的Nacos地址查看网关日志是否有注册异常确认Nacos的namespace是否匹配问题2前端访问接口404确认网关路由配置检查Nacos中的服务名是否正确查看请求路径是否包含/dev-api前缀问题3数据库连接失败检查Nacos中的数据库配置确认MySQL用户有远程连接权限查看Druid连接池配置实际项目中我遇到最棘手的问题是Redis连接超时。后来发现是Nacos配置的Redis地址用了内网IP而微服务用的是Docker虚拟网络。解决方案是在Nacos中配置宿主机的host.docker.internal。Ruoyi-Cloud的权限体系也容易踩坑。新增模块后需要在sys_menu表添加菜单项在sys_role_menu配置角色权限前端src/store/modules/permission.js添加路由这些经验都是在真实项目中踩坑后总结的。建议开发时保持Nacos控制台和IDEA的Run/Debug窗口并列显示随时观察服务状态。遇到问题先看日志90%的错误信息都会直接显示在控制台。