作为常年跟若依打交道的人我第一套微服务版部署就折腾了差不多两天倒不是项目本身多复杂而是它不像单体版那样“启动一个 jar、配一个前台”就完事。Nacos、Gateway、认证中心、各业务模块之间一环扣一环任何一个环节没对齐登录页都刷不出来。这篇不是把官方 README 抄一遍而是把我实际部署这套若依微服务版本时踩过的坑、验证过的顺序、调整过的配置全部梳理清楚给正准备动手部署的朋友一条能直接走通的路径。1. 部署若依微服务前先搞懂这四类角色很多人在部署前习惯直接搜“若依微服务部署”然后照着一条命令一条命令敲。我不建议这么干因为微服务版和单体版最大的差别是部署运维的复杂度从“一个进程”变成了“一群进程”如果不先理解这群进程里谁负责什么、谁依赖谁出问题的时候会完全无从下手。1.1 微服务版和单体版的核心差异若依有单体版本和微服务版本两者在业务代码上确实有很多相似之处但在运行形态上几乎不是同一个东西。单体版通常是一个 Spring Boot 应用加上一个前端静态资源目录部署时只需要一个可执行 jar 包最多再加 Nginx 做反向代理。微服务版则把系统功能拆成了多个独立进程网关负责统一入口认证服务负责登录和令牌签发系统服务负责用户、角色、菜单等基础数据文件服务管上传下载定时任务单独跑。每个进程都可以独立扩缩容但代价是部署的初始复杂度明显上升。如果只是公司内部小项目、用户量不大我不太建议一上来就上微服务版但如果你就是想学微服务架构或者说项目本身就规划了多个团队并行开发那若依微服务版确实是个很好的脚手架。它把 Spring Cloud Alibaba 生态里最常见的组件都串起来了部署一遍等于把 Nacos、Gateway、Sentinel 这些组件在真实项目里过了一遍。1.2 整体部署架构与组件职责我从部署视角把若依微服务版本涉及的角色分成四类先列个总表后面所有步骤都围绕这个表展开角色对应模块/组件部署职责基础设施MySQL、Redis数据存储与缓存业务服务的强依赖注册配置中心Nacos服务注册发现 配置统一管理后端微服务Gateway、Auth、System、File、Job业务能力提供方通过 Nacos 互相发现前端应用ruoyi-uiVue 项目发起请求统一走网关地址这里面最容易忽略的是 Nacos 的双重身份。它既是服务注册中心又是配置中心。服务启动时先从 Nacos 拉配置然后向 Nacos 注册自己。所以部署顺序上Nacos 必须先起来而且 Nacos 自己还需要依赖 MySQL 做配置持久化。这个依赖链不搞清楚会出现“明明服务起来了但 Nacos 控制台里看不到服务”的经典问题。1.3 版本选型和资源规划若依微服务版本推荐 JDK 1.8、Maven 3.6、MySQL 5.7 或 8.0、Redis 3.2Nacos 官方推荐 2.x 系列。我这里使用 JDK 1.8 和 Nacos 2.2.3搭配 Spring Cloud Alibaba 2021 版本体系兼容性经过很多项目验证比较稳妥。资源规划上如果你用一台 2G 内存的机器部署基本会卡在内存不够用。建议最低 4G最好 8G 及以上。因为 Nacos 默认 JVM 参数就给了 512M 到 1GGateway、Auth、System 三个服务加起来轻松超过 1.5G再算上 MySQL 和 Redis2G 机器根本转不开。我自己的测试环境是 4G 内存部署时还手动调小了 Nacos 的堆内存才勉强跑顺畅。2. 基础设施安装Nacos、MySQL、Redis 才是重头戏微服务版的数据库脚本分得很细不像单体版就导入一个 SQL 文件。这一步很多人会漏漏了之后服务能启动但登录时各种表不存在、字段缺失的报错会接踵而来。2.1 Nacos 安装与 MySQL 配置持久化Nacos 从 1.x 到 2.x 的安装方式基本一致下载压缩包、解压、改配置文件、启动。生产环境必须把 Nacos 的配置持久化到 MySQL否则每次重启 Nacos 都会丢失所有配置文件那就得重新导一遍非常痛苦。我以 Linux 服务器为例步骤大致如下# 下载并解压 Nacos这里以 2.2.3 为例 wget https://github.com/alibaba/nacos/releases/download/2.2.3/nacos-server-2.2.3.tar.gz tar -xzf nacos-server-2.2.3.tar.gz cd nacos/conf # 复制官方提供的 MySQL 初始化脚本 cp mysql-schema.sql /tmp/nacos-mysql-schema.sql然后手动在 MySQL 里创建nacos_config数据库并导入/tmp/nacos-mysql-schema.sql。导入之后需要修改 Nacos 的application.propertiesspring.datasource.platformmysql db.num1 db.url.0jdbc:mysql://127.0.0.1:3306/nacos_config?characterEncodingutf8connectTimeout1000socketTimeout3000autoReconnecttrueuseUnicodetrueuseSSLfalseserverTimezoneAsia/Shanghai db.user.0root db.password.0你的数据库密码这里坑点主要在时区和 SSL 参数。MySQL 8.0 默认时区可能与本地不一致serverTimezoneAsia/Shanghai一定要带上否则 Nacos 启动时数据源初始化可能报错。修改完配置文件后进入 Nacos 的 bin 目录启动sh startup.sh -m standalone启动后访问http://服务器IP:8848/nacos默认账号密码都是nacos能看到控制台说明 Nacos 起来了。注意 2.x 版本默认还会占用 9848 端口这是 gRPC 通信用的防火墙如果只开了 8848服务注册大概率失败这个细节我在后面章节会专门说。2.2 导入若依的 SQL 脚本别漏了配置库若依微服务版源码里有一个sql/目录里面通常包含多个 SQL 文件。至少会有一个业务系统库脚本和一个 Nacos 配置库脚本。我拿到的版本里业务库脚本名类似ry_2024xxxx.sql配置库脚本名类似ry_config_2024xxxx.sql。导入顺序建议先业务库后配置库mysql -uroot -p -e CREATE DATABASE IF NOT EXISTS ry-cloud DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; mysql -uroot -p ry-cloud sql/ry_2024xxxx.sql mysql -uroot -p -e CREATE DATABASE IF NOT EXISTS ry-config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; mysql -uroot -p ry-config sql/ry_config_2024xxxx.sqlry_2024xxxx.sql维护的是若依系统运行时的业务数据用户表、角色表、菜单表都在里面。ry_config_2024xxxx.sql则是 Nacos 配置中心要用的数据导入之后Nacos 才能根据 dataId 找到对应的服务配置。如果只看部署教程不看数据库脚本说明很容易把ry_config这个库漏掉结果 Services 启动时一直报“找不到配置”。2.3 Redis 的安装和最小化配置Redis 在若依微服务版中主要用于缓存验证码、登录令牌和部分热点数据。部署方式没什么特殊要求yum 安装或编译安装都行生产环境建议设置密码并关闭保护模式。我这里用最小化方式演示yum install -y redis systemctl start redis redis-cli ping确保返回PONG即可。如果 Redis 设置了密码需要同步修改 Nacos 配置中心里各服务spring.redis.password配置项。这里我特别提醒一句若依微服务的 Redis 配置统一放在 Nacos 里不放在本地 application.yml 中。所以改完 Redis 密码以后别去源码里翻配置文件直接改 Nacos 才是正确路径。3. 源码编译与 Nacos 配置中心初始化基础设施就绪之后才轮到编译若依源码。这一步的关键不是mvn package本身而是理解各个模块之间的关系以及配置如何从本地迁移到 Nacos。3.1 下载源码并理清 maven 模块关系从若依官方仓库下载微服务版源码解压之后你会看到这些目录ruoyi-gateway统一网关服务ruoyi-auth认证授权服务ruoyi-modules业务模块目录里面包含 system、file、job 等ruoyi-visual监控与可视化模块通常包含 monitorruoyi-ui前端 Vue 项目sql数据库脚本第一次接触时不要急着打包先看每个模块的pom.xml。若依微服务版是典型的多模块 Maven 工程父 pom 管理所有依赖版本子模块之间也有依赖关系。比如 Auth 服务会依赖 system APIGateway 会依赖 common 核心包。所以打包时必须在根目录执行命令让 Maven 按依赖顺序构建而不是单独进某个子模块打包。3.2 本地打包命令与常见报错处理在根目录执行mvn clean package -DskipTests这里有几个容易踩的小问题。第一个是 Maven 源的问题国内网络环境拉取 Spring Cloud Alibaba 依赖可能很慢建议在 Maven 的settings.xml里配置阿里云镜像。第二个是 JDK 版本必须严格使用 1.8高版本 JDK 在编译旧版 Spring Cloud 时经常报Unsupported class file major version。第三个是如果只想打包后端、不打包前端那就不要进ruoyi-ui目录执行命令前端单独用npm install和npm run build处理。打包完成后在ruoyi-gateway/target/、ruoyi-auth/target/、ruoyi-modules/ruoyi-system/target/等目录下会生成可执行 jar 包。每个服务的 jar 包名可能包含版本号建议复制到统一目录并重命名比如mkdir -p /app/ruoyi cp ruoyi-gateway/target/ruoyi-gateway.jar /app/ruoyi/ cp ruoyi-auth/target/ruoyi-auth.jar /app/ruoyi/ cp ruoyi-modules/ruoyi-system/target/ruoyi-system.jar /app/ruoyi/ cp ruoyi-modules/ruoyi-file/target/ruoyi-file.jar /app/ruoyi/ cp ruoyi-modules/ruoyi-job/target/ruoyi-job.jar /app/ruoyi/这样后面启动命令会清爽很多排查问题时也容易分辨日志属于哪个服务。3.3 把配置推进 Nacos 并核对关键配置项若依微服务版的配置管理方式很有意思每个服务在本地只有一个bootstrap.yml里面主要配置 Nacos 的地址、命名空间、分组以及自身的应用名真正的数据源、Redis、JWT 密钥等配置全部存放在 Nacos 配置中心。刚才导入的ry_config库就是 Nacos 配置的持久化存储。启动 Nacos 后进入控制台在“配置管理-配置列表”里可以看到若依预先导入的配置。你需要逐个核对以下几项各服务spring.datasource.url里的数据库连接地址、账号密码是否与本地一致各服务spring.redis.host/port/password是否与本地 Redis 一致spring.cloud.nacos.discovery.server-addr和spring.cloud.nacos.config.server-addr是否指向正确的 Nacos 地址网关配置里的spring.redis和 JWT 相关配置是否正确。我遇到过一种很隐蔽的情况配置库名称导入正确Nacos 也确实显示出了配置但服务启动后还是读取不到。原因是我在 Nacos 控制台上手动修改过配置而改完之后没有发布界面上的“编辑”状态不生效。Nacos 配置修改后必须点击“发布”服务端才会真正刷新。4. 服务启动顺序、健康检查与前端联调部署若依微服务版本时服务启动顺序直接决定第一次启动的成功率。虽说 Nacos 有服务发现机制服务之间可以通过注册中心自动找到对方但如果依赖方先启动而提供方还没注册上部分初始化逻辑就会因为空连接而报错。4.1 按依赖关系启动的六步顺序我的启动顺序如下基本遵循“基础设施 注册中心 网关 认证 业务模块 前端”的路径启动 MySQL确认业务库和配置库都已导入启动 Redis确认客户端能正常连接启动 Nacos确认控制台可访问并且配置列表能拉到若依配置启动ruoyi-gateway启动ruoyi-auth启动ruoyi-modules/ruoyi-system以及可选的ruoyi-file、ruoyi-job。文件服务和定时任务服务不启动系统核心功能也能跑但如果业务中要传头像、导出文件文件服务必须在线。每个服务的启动命令大致相同nohup java -jar /app/ruoyi/ruoyi-gateway.jar /app/logs/gateway.log 21 nohup java -jar /app/ruoyi/ruoyi-auth.jar /app/logs/auth.log 21 nohup java -jar /app/ruoyi/ruoyi-system.jar /app/logs/system.log 21 在测试环境想快速看日志可以直接前台启动但建议加上nohup和日志文件重定向方便后面排查问题。生产环境则建议用systemd或 Docker 管理进程不然 SSH 断开后服务容易跟着退出。4.2 通过日志和 API 验证服务是否就绪很多朋友喜欢用“控制台有没有打印启动成功”来判断服务状态这在微服务环境里不够充分。我建议每启动完一个服务就做一次实际验证。Nacos 启动成功的标志是控制台能登录且“服务列表”页签里能看到当前注册上来的服务。Gateway 服务注册成功后Nacos 服务列表会出现ruoyi-gateway这个名字。这一步验证非常重要因为 Gateway 是前端请求的唯一入口它没注册上后面所有功能都访问不了。Auth 服务启动后可以检查它的日志通常会输出与 Nacos 心跳相关的信息也可以通过下面命令确认端口监听netstat -tlnp | grep javaSystem 服务启动成功后可以通过网关做一次真实请求验证。比如直接访问curl http://127.0.0.1:8080/code如果能返回验证码相关的 JSON 数据说明 Gateway 已经能通过 Nacos 找到 Auth 或 System 服务整个内部的注册发现链路是通的。不过有些版本验证码接口路径略有差异具体以你拉取的源码为准。4.3 前端启动与网关地址的配置后端服务全部起来后前端反而成了最容易卡住的地方。若依的前端是标准 Vue 项目先安装依赖再启动cd ruoyi-ui npm install npm run dev本地开发时前端默认通过.env.development里的VITE_APP_BASE_API配置来拼接接口地址。默认可能是/dev-api同时vue.config.js里配置了代理转发。如果你是在局域网服务器上部署需要把代理目标指向 Gateway 的地址proxy: { /dev-api: { target: http://127.0.0.1:8080, changeOrigin: true, pathRewrite: { ^/dev-api: } } }这里最容易出的问题是 target 地址写错。如果 Gateway 监听在 8080 端口target 就写http://127.0.0.1:8080如果你在浏览器里访问的是另外一台服务器地址但要区分“服务器本机地址”和“浏览器访问地址”。代理是在 Node.js 进程里转发所以 target 填服务器本机能访问到 Gateway 的地址即可不能填 localhost 指向开发者自己的电脑。5. 最容易踩的六个部署坑以及我当时的排查过程这一节是全文的重头戏。若依微服务版部署不像单体版那么“一次成功”我每次帮同事排障最后定位到的问题基本都集中在 Nacos 通信、JWT 配置、数据库时区这几类。我在下面把排查链路完整写出来供大家参照。5.1 服务注册不上Nacos 命名空间与分组不一致有段时间我启动 system 服务日志显示注册成功但 Nacos 服务列表里迟迟不出现。我当时的排查链路是这样的先看 Nacos 控制台的“命名空间”发现有一个非 public 的命名空间再看服务日志里打印的nacos.namespace参数发现是空的最后检查bootstrap.yml发现配置了namespace: 某个ID但该命名空间在 Nacos 中并不存在。服务注册时如果指定了一个不存在的命名空间Nacos 不会报错只是会把服务注册到空气里控制台默认的 public 命名空间自然看不到。解决方法是进入 Nacos 控制台把命名空间 ID 和名称创建出来确保和配置完全一致。更省事的方式是把命名空间留空所有服务都注册在 public 下测试环境不需要做环境隔离。5.2 启动报错“无法连接配置中心”bootstrap.yml 与 Nacos 地址另一个高频问题是服务启动时提示连接 Config 超时或者直接报NacosException。我排查时第一反应是去看bootstrap.yml里的 Nacos 地址。若依微服务版每个服务的bootstrap.yml都有如下结构spring: application: name: ruoyi-gateway cloud: nacos: config: server-addr: 127.0.0.1:8848 file-extension: yml namespace: xxx如果你把服务 jar 包拷贝到另一台服务器而bootstrap.yml里仍然是127.0.0.1:8848它在本地找不到 Nacos自然拉不到配置。所以部署到远程环境时务必检查所有服务 jar 包内的bootstrap.yml或者通过外部配置覆盖。最简单的方式是打包前就改成服务器实际 IP不要用 localhost。5.3 登录后网关 401JWT 密钥和忽略白名单若依微服务的登录流程是前端请求网关网关把/auth/login放行到认证服务认证服务签发 JWT后续请求都携带 Token。如果登录本身成功但后续请求全部 401问题多半出在网关的 JWT 密钥与服务端不一致。网关配置里有一项jwt.secret等同于认证服务的签名密钥。如果两个服务的 secret 不一致网关解析 Token 时就会失败。修改方法是在 Nacos 配置中心同时修改ruoyi-auth和ruoyi-gateway的配置保证密钥完全一致然后逐个重启。另一个相似的问题是网关的ignore.whites配置也就是无需认证的白名单路径。你如果把某些需要登录的路径误加进白名单服务本身不会报错但接口会绕过鉴权这点在安全检查时要特别注意。5.4 内存占用过高调低 Nacos 默认堆内存如果你像我一样用一台 4G 内存的机器做演示环境部署完整套后会发现内存直接爆掉。排查之后发现 Nacos 默认启动脚本里JAVA_OPT设置了很大的堆内存在nacos/bin/startup.sh里可以看到类似-Xms512m -Xmx512m这样的参数。多服务叠加后4G 内存根本不够。我当时的处理方式是把 Nacos 的堆内存调低export JAVA_OPT${JAVA_OPT} -Xms256m -Xmx256m同时启动各业务 jar 时也手动限制堆大小java -Xms256m -Xmx256m -jar /app/ruoyi/ruoyi-gateway.jar调整之后整个若依微服务版本勉强能在 4G 内存机器上运行但生产环境不建议如此激进。生产至少给 Nacos 1G 堆内存业务服务单实例 512M 到 1G 起步。5.5 服务端口与防火墙导致的外部访问失败如果你在本地部署一切正常但换到云服务器后接口访问不通先别急着怀疑程序。我用curl http://127.0.0.1:8080验证时是通的说明服务本身没问题但外部浏览器访问就是超时。最终定位到是云服务器安全组没有放行 8080 和 8848 端口。Nacos 2.x 还有一个容易被忽略的端口9848。这是 Nacos 客户端与服务端进行 gRPC 通信的端口必须在防火墙和安全组中一并放行。只开放 8848 会导致服务注册时偶发失败表现形式很随机有时候重启一下就好但过几分钟又掉线。加上 9848 以后问题彻底消失。5.6 MySQL 时区问题引发的日期异常若依的某些接口会返回时间字段如果数据库连接串里没有设置serverTimezoneAsia/Shanghai系统可能多出 8 小时或者直接报错。这个坑常见于 MySQL 8.0。我在 Nacos 配置中心里把每个业务模块的数据源连接串都加上了时区参数保存发布后重启服务才恢复。这里我特别提醒不要只改一个服务的数据源。若依微服务版中每个模块都可能拥有独立数据源配置比如 Auth、System、Job 在 Nacos 配置中心里各自有一份配置。排查时要全局搜索jdbc:mysql把所有连接串统一加时区否则治标不治本。6. 从“能跑”到“好跑”生产化部署的几点升级经验当你在本地把这套若依微服务版完整跑起来后剩下的工作就是考虑怎么让它稳定地跑在生产环境。下面这几条经验是我在项目落地过程中逐步加上的每一条都是被现实问题逼出来的。6.1 Docker Compose 化部署手动启动五六个 jar 包在服务器重启后要一个个敲命令非常容易漏。我后来把所有服务改成了 Docker Compose 编排每个服务一个容器网络共享同一个 Docker 网络Nacos 地址统一填服务名而不是 IP。这样不仅启动顺序明确日志管理也更方便services: mysql: image: mysql:8.0 restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: yourpassword volumes: - ./mysql-data:/var/lib/mysql ports: - 3306:3306 redis: image: redis:7 restart: unless-stopped ports: - 6379:6379 nacos: image: nacos/nacos-server:v2.2.3 restart: unless-stopped environment: MODE: standalone SPRING_DATASOURCE_PLATFORM: mysql MYSQL_SERVICE_HOST: mysql MYSQL_SERVICE_DB_NAME: nacos_config MYSQL_SERVICE_PORT: 3306 MYSQL_SERVICE_USER: root MYSQL_SERVICE_PASSWORD: yourpassword ports: - 8848:8848 - 9848:9848 depends_on: - mysql用 Compose 部署后服务之间的依赖关系通过depends_on控制MySQL 和 Nacos 启动顺序就有了保障。不过depends_on只保证容器启动顺序不保证 MySQL 已经就绪所以严谨一点还得给等待 MySQL 就绪的检查脚本否则 Nacos 启动时连接数据库还是会失败。6.2 区分环境配置别把测试配置带到生产我在测试环境用 root 账号、无密码 Redis 都是常态但生产环境必须区分开。若依微服务版支持在 Nacos 上按环境维护多套配置本质上是通过不同命名空间或者配置后缀来区分。我建议至少划分 dev、test、prod 三个命名空间每个命名空间导一份对应的配置库这样切换环境只需要改bootstrap.yml里的 namespace不需要动源码重新打包。生产环境数据库账号建议单独创建最小权限账号Redis 必须设置密码并开启requirepass。Gateway 的 CORS 配置也要收紧不要使用allowedOriginPatterns: *而是配置具体的域名或端口避免接口被跨域滥用。6.3 日志收集与监控建议微服务部署最头疼的问题之一就是日志分散在各个服务中。如果每个服务都输出到各自文件排查一个请求链路可能要来回切换多个文件。我后来接入了 Loki 加 Promtail 做日志集中收集也会用若依自带的 ruoyi-visual 模块看看服务健康状态。如果不想额外引入组件至少要做到每个服务的日志文件按天分割并且把日志文件目录统一规划比如/app/logs/gateway.log、/app/logs/auth.log方便用grep串起来排查。配合简单的定时脚本对超过 7 天的日志进行压缩归档能有效防止磁盘被日志塞满。在监控层面Spring Boot Admin 在若依微服务版中可以作为基础监控面板能大致看到各服务的内存、线程、健康状态。查看服务是否异常我习惯在 Nacos 控制台先看服务列表里的实例健康状态再用curl请求网关接口做业务级健康检查两层都确认没问题才算部署成功。最后再分享一个个人体会若依微服务版部署这件事难度不在命令而在理解组件间的依赖关系。你只要把“配置从哪来、服务注册到哪、请求经过谁”这三条链路理清楚整套系统跑起来只是时间问题。我踩过的坑大概率你也会遇到建议把第 5 节的六类问题收藏下来部署时逐项对照能省下不少排查时间。