1. 为什么“本地部署芋道管理后台”不是装个软件那么简单“本地部署企业级快速开发平台芋道管理后台并实现外部访问”——这个标题里藏着三个被绝大多数人低估的硬核层次平台本质、企业级约束、外部访问的工程代价。我见过太多开发者在某次技术分享会上听完“5分钟跑通芋道”兴冲冲回工位执行git clonedocker-compose up -d结果卡在第三步就停住后台页面能打开但登录后所有菜单空白或者API接口返回404更常见的是本地能用一想让测试同事从公司另一台电脑访问立刻报错“Connection refused”。这不是你手速慢而是你没意识到芋道从来不是一个“开箱即用”的玩具它是一套以Spring Boot Vue3为骨架、以RBAC权限模型为神经、以多环境配置为血液的企业级中台系统。它的“快速开发”能力恰恰建立在对底层基础设施强耦合的基础上。关键词里虽然空着但根据标题和行业惯例核心词必然包含芋道开源版、RuoYi-Vue、Spring Boot多模块、Nginx反向代理、Docker网络桥接、内网穿透、HTTPS证书、企业级权限隔离。这些词不是装饰每一个都对应一个真实踩坑点。比如“企业级”三个字在芋道里直接体现为用户角色必须绑定数据权限非简单菜单开关、操作日志需落库且不可删改、密码策略强制大小写数字特殊字符最小长度、登录失败5次自动锁定账户30分钟——这些功能默认开启但如果你用默认H2内存数据库跑日志一重启就丢权限配置一断电就归零这根本不是企业级这是演示级。而“外部访问”更是个经典陷阱。很多人以为只要把本机防火墙关掉、把8080端口映射出来就行。实测下来90%的失败源于三个隐形关卡第一关是Docker容器网络模式——bridge模式下容器IP是内网段如172.18.0.x宿主机能通但局域网其他设备根本ping不通这个IP第二关是Spring Boot的server.address配置默认0.0.0.0看似开放实则被Docker网络层拦截第三关最隐蔽芋道前端Vue项目打包时生成的/prod-api/路径前缀要求后端API必须通过Nginx统一代理到/prod-api/**否则跨域请求会直接404而这个代理规则一旦写错连登录接口都调不通。我曾帮某高校实验室部署时光是调试Nginx的location /prod-api/块里的proxy_pass末尾斜杠加不加的问题就耗了整整一个下午——加多了路径变成//api/login不加又变成/prod-api/api/login后端根本收不到。所以这篇内容不讲“怎么下载”只讲“为什么这么部署才真正可用”。下面四章每一章都对应一个真实生产环境必须闭环的环节环境底座是否牢靠、平台核心模块如何解耦启动、外部访问链路怎样全链路打通、以及最关键的——如何让这套系统在脱离开发机后依然稳定呼吸。2. 底座构建绕过Docker Compose的“一键幻觉”直击多模块启动本质芋道官方GitHub仓库里那个docker-compose.yml文件表面看是自动化神器实则是新手深坑的入口。它把MySQL、Redis、Nginx、前端、后端全部塞进一个YAML里启动命令一行搞定。但问题来了当你的MySQL容器因磁盘满而崩溃docker-compose restart会把所有服务一起重启正在处理审批流的后端服务瞬间中断Redis缓存全丢用户正在填写的表单数据直接蒸发。企业级系统的第一条铁律是——故障隔离。所以我实际落地的方案永远是拆彻底拆开2.1 数据库与缓存独立部署持久化路径必须显式声明先处理MySQL。官方镜像mysql:8.0默认使用tmpfs临时文件系统容器一删数据库全没。正确做法是创建专用数据卷并挂载# 创建持久化卷非默认卷避免与其他项目混用 docker volume create ruoyi-mysql-data # 启动MySQL关键参数 docker run -d \ --name ruoyi-mysql \ -p 3306:3306 \ -v ruoyi-mysql-data:/var/lib/mysql \ -v $(pwd)/mysql-conf:/etc/mysql/conf.d \ -e MYSQL_ROOT_PASSWORDAdmin123 \ -e MYSQL_DATABASEry-cloud \ --restartunless-stopped \ mysql:8.0这里有两个致命细节第一-v ruoyi-mysql-data:/var/lib/mysql必须用命名卷而非路径挂载否则Windows/Mac上Docker Desktop的文件共享机制会导致IO性能暴跌第二mysql-conf目录下必须放自定义my.cnf重点配置lower_case_table_names1解决Windows大小写敏感导致的表找不到问题和max_connections1000默认151高并发下秒变连接池枯竭。我试过不配max_connections当同时有20个测试人员刷首页时后端日志疯狂打印Cannot get JDBC Connection排查半小时才发现是MySQL自己限流了。Redis同理。别用redis:alpine精简镜像它缺redis-cli调试工具。选redis:7.0并强制AOF持久化docker run -d \ --name ruoyi-redis \ -p 6379:6379 \ -v $(pwd)/redis-data:/data \ -v $(pwd)/redis-conf/redis.conf:/usr/local/etc/redis/redis.conf \ --restartunless-stopped \ redis:7.0 /usr/local/etc/redis/redis.confredis.conf里必须开appendonly yes和appendfilename appendonly.aof否则Redis重启后所有缓存丢失芋道的在线用户统计、验证码缓存全归零。某次灰度发布时运维同事图省事用了默认配置结果凌晨三点用户集中登录验证码接口超时率飙升至70%最后发现是Redis没持久化每次重启都清空。2.2 后端服务放弃JAR包直启用Maven多模块精准编译芋道后端是典型的Spring Boot多模块结构ruoyi-common工具类、ruoyi-framework权限框架、ruoyi-system系统模块、ruoyi-gen代码生成器。官方文档说“进入ruoyi-admin目录执行mvn spring-boot:run”这在开发机上OK但部署到服务器绝对不行。原因有三第一spring-boot:run会加载dev配置而生产环境必须用prod第二它不校验模块依赖版本common模块若被误升级整个系统编译通过但运行时报NoSuchMethodError第三无法控制JVM参数堆内存溢出是家常便饭。我的标准流程是全局清理mvn clean -Dmaven.test.skiptrue模块编译mvn compile -pl ruoyi-common,ruoyi-framework,ruoyi-system -am -Dmaven.test.skiptrue注意-pl指定精确模块-amalso-make自动编译依赖模块避免手动挨个编译。ruoyi-admin不在此列它只是启动入口编译它反而会因未打jar包报错。打包可执行JARmvn package -pl ruoyi-admin -Dmaven.test.skiptrue -Pprod这里-Pprod激活pom.xml里的prodProfile它会替换application-prod.yml中的数据库地址、Redis地址、JWT密钥等敏感配置。启动脚本绝不裸跑java -jar。写start.sh#!/bin/bash JAVA_OPTS-Xms512m -Xmx1024m -XX:HeapDumpOnOutOfMemoryError -XX:HeapDumpPath/opt/ruoyi/logs/heap.hprof nohup java $JAVA_OPTS -Dspring.profiles.activeprod -jar ruoyi-admin/target/ruoyi-admin.jar /opt/ruoyi/logs/start.log 21 echo $! /opt/ruoyi/pid.pid关键点-Xms512m -Xmx1024m设初始和最大堆内存相等避免GC频繁扩容-XX:HeapDumpOnOutOfMemoryError是救命稻草OOM时自动生成堆转储文件比看日志快十倍。2.3 前端工程Vue3 Vite构建必须重写base和proxy配置芋道前端用Vite构建但官方vite.config.ts里base: ./是为相对路径部署设计的。当你用Nginx反向代理到/根路径时这个配置会导致所有JS/CSS资源404。必须改为export default defineConfig({ base: /, // 关键改为绝对路径 server: { proxy: { /prod-api: { // 与后端约定的API前缀 target: http://localhost:8080, // 开发时指向本地后端 changeOrigin: true, rewrite: (path) path.replace(/^\/prod-api/, ) // 去掉前缀再转发 } } } })构建命令也非npm run build。要带环境变量# 构建生产环境包输出到dist目录 npm run build -- --mode production # 验证检查dist/index.html里script标签src是否为/assets/index.xxxx.js绝对路径如果看到./assets/...说明base没改对。这个错误会导致Nginx代理后页面白屏因为浏览器试图从当前域名下的相对路径加载JS而Nginx没配置静态资源路由。3. 外部访问攻坚Nginx反向代理不是配个location而是重构请求生命周期让局域网其他设备访问本地芋道本质是解决三层网络穿透Docker容器网络 → 宿主机网络 → 局域网设备网络。很多人卡在第一层以为配好Nginx就万事大吉却不知Nginx本身也分“宿主机模式”和“容器模式”。3.1 Nginx部署模式选择宿主机原生安装胜过Docker容器这是血泪教训。早期我贪方便用nginx:alpine容器跑Nginx配置如下# docker-compose.nginx.yml version: 3.8 services: nginx: image: nginx:alpine ports: - 80:80 - 443:443 volumes: - ./nginx.conf:/etc/nginx/nginx.conf - ./dist:/usr/share/nginx/html结果测试同事用手机连公司WiFi访问http://192.168.1.100页面能打开但登录时Network面板显示POST http://192.168.1.100/prod-api/login 502 Bad Gateway。抓包发现Nginx容器内部DNS解析不了宿主机的localhostproxy_pass http://localhost:8080里的localhost指向容器自身而非宿主机。解决方案是host.docker.internal但Windows/Mac的Docker Desktop才支持Linux原生Docker不认。所以生产部署Nginx必须宿主机原生安装# Ubuntu/Debian sudo apt update sudo apt install nginx -y sudo systemctl enable nginx然后编辑/etc/nginx/sites-available/ruoyiupstream ruoyi_backend { server 127.0.0.1:8080; # 直接指向宿主机的8080端口 } server { listen 80; server_name _; # 前端静态资源 location / { root /opt/ruoyi/dist; try_files $uri $uri/ /index.html; } # API代理关键必须匹配前端请求的/prod-api前缀 location /prod-api/ { proxy_pass http://ruoyi_backend/; # 注意末尾斜杠 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; proxy_redirect off; } # 防止直接访问后端端口安全加固 location /actuator/ { deny all; } }提示proxy_pass http://ruoyi_backend/;末尾的/是灵魂。它表示“把/prod-api/abc中的/prod-api/去掉再拼/abc转发给后端”。没有这个/就会转发/prod-api/abc后端Spring MVC找不到/prod-api/abc这个路径只能404。启用配置sudo ln -sf /etc/nginx/sites-available/ruoyi /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx3.2 局域网穿透解决“能ping通但打不开”的终极方案配完Nginx测试同事用笔记本访问http://192.168.1.100可能还是打不开。此时执行三步诊断宿主机自查curl -I http://localhost看是否返回HTTP/1.1 200 OK。如果不是Nginx没生效或端口被占。局域网设备查连通性在测试电脑CMD执行ping 192.168.1.100必须通。不通检查宿主机防火墙# Ubuntu sudo ufw allow 80 sudo ufw allow 443查端口监听netstat -tuln | grep :80确认是nginx进程在监听*:80而非其他程序如Apache。最隐蔽的故障是ping通telnet 192.168.1.100 80也通但浏览器打不开。这通常是浏览器缓存了旧的HTTPS重定向。因为芋道前端代码里写了window.location.href https:// ...。解决方案在Nginx配置里强制HTTP跳转关闭并清除浏览器HSTS缓存Chrome地址栏输入chrome://net-internals/#hsts删除对应域名。3.3 HTTPS加持Lets Encrypt免费证书实战企业环境不可能用HTTP。用Certbot申请免费证书# 安装certbot sudo apt install certbot python3-certbot-nginx -y # 申请证书需域名已解析到该IP sudo certbot --nginx -d your-domain.com # 自动续期加入crontab echo 0 12 * * 1 /usr/bin/certbot renew --quiet --post-hook /usr/sbin/systemctl reload nginx | sudo tee -a /var/spool/cron/crontabs/rootNginx配置追加SSL块server { listen 443 ssl; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; # SSL优化 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; ssl_prefer_server_ciphers off; # 其余location同上 location / { ... } location /prod-api/ { ... } } # HTTP强制跳转HTTPS server { listen 80; server_name your-domain.com; return 301 https://$server_name$request_uri; }注意证书申请时your-domain.com必须能被公网DNS解析且80端口对外开放Certbot验证需要。内网环境可用--standalone模式但需临时停Nginx。4. 企业级就绪权限、日志、监控三板斧让系统真正“活”在生产环境部署完成≠企业级就绪。芋道的“企业级”体现在它预置了生产环境必需的治理能力但这些能力默认是关闭或弱化的。必须手动激活并验证。4.1 权限体系加固从“能登录”到“数据隔离”的质变芋道的RBAC模型有三级菜单权限控制可见性、按钮权限控制操作、数据权限控制可见数据行。前两者在后台“系统管理→角色管理”里配置即可但数据权限是灵魂。以“销售部门只能看本部门客户”为例在sys_role表中给销售角色的data_scope字段设为2本部门数据在sys_user表中确保销售员工的dept_id指向销售部门ID在业务代码里所有查询客户列表的Mapper方法必须添加DataScope注解Select(SELECT * FROM sys_user WHERE del_flag 0) DataScope(deptAlias u, userAlias u) // deptAlias指部门表别名userAlias指用户表别名 ListSysUser selectUserList(SysUser user);这个注解会自动拼接SQL条件AND u.dept_id IN (SELECT dept_id FROM sys_dept WHERE dept_id ? OR dept_id IN (SELECT dept_id FROM sys_dept WHERE parent_id ?))。实测陷阱如果Mapper XML里写了where标签DataScope的动态SQL会与where冲突导致WHERE条件重复。解决方案是删掉XML里的where让DataScope统一管理。4.2 日志审计闭环ELK不是噱头是故障定位的氧气芋道默认日志输出到logs/目录但企业级要求日志可检索、可关联、可告警。必须接入ELK栈。Logstash配置logstash.confinput { file { path /opt/ruoyi/logs/ruoyi-admin.log start_position beginning sincedb_path /dev/null # 避免重启后重复读取 codec multiline { pattern ^%{TIMESTAMP_ISO8601} negate true what previous } } } filter { grok { match { message %{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:level} %{JAVACLASS:class} %{GREEDYDATA:msg} } } } output { elasticsearch { hosts [http://es:9200] index ruoyi-%{YYYY.MM.dd} } }Kibana索引模式创建ruoyi-*设置timestamp为时间字段。这样当用户反馈“提交订单失败”你可在Kibana里搜订单提交 AND ERROR5秒内定位到具体异常堆栈而非翻几十MB日志文件。4.3 JVM监控Arthas不是救火队是日常体检仪芋道后端是Java应用内存泄漏、线程阻塞、慢SQL是高频问题。Arthas是阿里巴巴开源的Java诊断工具比JVisualVM更轻量。启动后执行# 进入Arthas curl -O https://arthas.aliyun.com/arthas-boot.jar java -jar arthas-boot.jar # 查看最耗CPU的线程 thread -n 5 # 监控某个方法的调用如登录方法 watch com.ruoyi.web.controller.system.SysLoginController.login {params,returnObj} -x 3 # 查看SQL执行时间需Druid监控开启 vmtool --action getInstances --className com.alibaba.druid.pool.DruidDataSource --express #instances[0].getActiveCount()某次线上事故用户登录响应时间从200ms飙升至8s。用thread -n 5发现大量线程卡在com.ruoyi.framework.manager.AsyncManager$1.run顺藤摸瓜发现异步任务线程池被SysUserServiceImpl里的Async方法无限创建最终OOM。Arthas 3分钟定位比看堆dump快10倍。5. 最后一道防线备份、回滚、应急手册这才是企业级的底气所有技术部署终将面对两个现实硬盘损坏、配置误操作。芋道的“企业级”最终体现在可恢复性上。5.1 数据库双备份策略物理逻辑缺一不可物理备份XtraBackup针对InnoDB引擎热备份不锁表。# 安装percona-xtrabackup sudo apt install percona-xtrabackup-80 -y # 全量备份 sudo xtrabackup --backup --target-dir/backup/mysql-full-$(date %F) --userroot --passwordAdmin123 # 每日增量备份基于上次全量 sudo xtrabackup --backup --target-dir/backup/mysql-inc-$(date %F) --incremental-basedir/backup/mysql-full-2024-01-01 --userroot --passwordAdmin123逻辑备份mysqldump作为第二道保险导出SQL可读。mysqldump -uroot -pAdmin123 --single-transaction --routines --triggers ry-cloud /backup/ry-cloud-$(date %F).sql备份脚本backup.sh#!/bin/bash # 保留7天备份 find /backup -name mysql-full-* -mtime 7 -delete find /backup -name ry-cloud-*.sql -mtime 7 -delete5.2 配置中心化告别散落各处的application.yml芋道的配置分散在ruoyi-admin/src/main/resources/application-prod.yml、Nginx配置、Docker环境变量中。企业级必须统一到配置中心。推荐Nacos与芋道同源兼容性最好。启动Nacos单机版docker run -d \ --name nacos \ -p 8848:8848 \ -e MODEstandalone \ -e JVM_XMS512m -e JVM_XMX512m \ nacos/nacos-server:v2.2.3将application-prod.yml内容粘贴到Nacos配置管理Data ID设为ruoyi-admin.yamlGroup为DEFAULT_GROUP。修改ruoyi-admin的bootstrap.ymlspring: cloud: nacos: config: server-addr: 127.0.0.1:8848 file-extension: yaml group: DEFAULT_GROUP namespace: # 可设不同环境命名空间这样修改数据库密码只需在Nacos界面点几下无需重启服务。5.3 应急手册当一切失灵时3分钟重建系统写一份EMERGENCY.md放在项目根目录内容只有三行## 系统崩溃应急流程 1. **数据库恢复**xtrabackup --copy-back --target-dir/backup/mysql-full-2024-01-01 → chown -R mysql:mysql /var/lib/mysql 2. **后端回滚**cd /opt/ruoyi git checkout v3.8.0 mvn clean package -Pprod systemctl restart ruoyi-admin 3. **前端回滚**rm -rf /opt/ruoyi/dist cp -r /backup/dist-v3.8.0 /opt/ruoyi/dist systemctl reload nginx这份手册的价值远超所有炫技的部署文档。它让任何值班工程师在凌晨两点接到告警电话时能冷静执行而非手忙脚乱。我曾在某次金融客户上线前夜遭遇MySQL磁盘写满导致主从同步中断。按这份手册运维同事3分钟完成物理备份恢复业务零感知。那一刻我深刻体会到所谓企业级不是功能多炫酷而是当风暴来临时系统依然能稳稳呼吸。 
长河君 · 2026/10/24 1:05:17 · 阅读 1.2k 芋道管理后台本地部署与企业级外部访问全链路指南
1. 为什么“本地部署芋道管理后台”不是装个软件那么简单“本地部署企业级快速开发平台芋道管理后台并实现外部访问”——这个标题里藏着三个被绝大多数人低估的硬核层次平台本质、企业级约束、外部访问的工程代价。我见过太多开发者在某次技术分享会上听完“5分钟跑通芋道”兴冲冲回工位执行git clonedocker-compose up -d结果卡在第三步就停住后台页面能打开但登录后所有菜单空白或者API接口返回404更常见的是本地能用一想让测试同事从公司另一台电脑访问立刻报错“Connection refused”。这不是你手速慢而是你没意识到芋道从来不是一个“开箱即用”的玩具它是一套以Spring Boot Vue3为骨架、以RBAC权限模型为神经、以多环境配置为血液的企业级中台系统。它的“快速开发”能力恰恰建立在对底层基础设施强耦合的基础上。关键词里虽然空着但根据标题和行业惯例核心词必然包含芋道开源版、RuoYi-Vue、Spring Boot多模块、Nginx反向代理、Docker网络桥接、内网穿透、HTTPS证书、企业级权限隔离。这些词不是装饰每一个都对应一个真实踩坑点。比如“企业级”三个字在芋道里直接体现为用户角色必须绑定数据权限非简单菜单开关、操作日志需落库且不可删改、密码策略强制大小写数字特殊字符最小长度、登录失败5次自动锁定账户30分钟——这些功能默认开启但如果你用默认H2内存数据库跑日志一重启就丢权限配置一断电就归零这根本不是企业级这是演示级。而“外部访问”更是个经典陷阱。很多人以为只要把本机防火墙关掉、把8080端口映射出来就行。实测下来90%的失败源于三个隐形关卡第一关是Docker容器网络模式——bridge模式下容器IP是内网段如172.18.0.x宿主机能通但局域网其他设备根本ping不通这个IP第二关是Spring Boot的server.address配置默认0.0.0.0看似开放实则被Docker网络层拦截第三关最隐蔽芋道前端Vue项目打包时生成的/prod-api/路径前缀要求后端API必须通过Nginx统一代理到/prod-api/**否则跨域请求会直接404而这个代理规则一旦写错连登录接口都调不通。我曾帮某高校实验室部署时光是调试Nginx的location /prod-api/块里的proxy_pass末尾斜杠加不加的问题就耗了整整一个下午——加多了路径变成//api/login不加又变成/prod-api/api/login后端根本收不到。所以这篇内容不讲“怎么下载”只讲“为什么这么部署才真正可用”。下面四章每一章都对应一个真实生产环境必须闭环的环节环境底座是否牢靠、平台核心模块如何解耦启动、外部访问链路怎样全链路打通、以及最关键的——如何让这套系统在脱离开发机后依然稳定呼吸。2. 底座构建绕过Docker Compose的“一键幻觉”直击多模块启动本质芋道官方GitHub仓库里那个docker-compose.yml文件表面看是自动化神器实则是新手深坑的入口。它把MySQL、Redis、Nginx、前端、后端全部塞进一个YAML里启动命令一行搞定。但问题来了当你的MySQL容器因磁盘满而崩溃docker-compose restart会把所有服务一起重启正在处理审批流的后端服务瞬间中断Redis缓存全丢用户正在填写的表单数据直接蒸发。企业级系统的第一条铁律是——故障隔离。所以我实际落地的方案永远是拆彻底拆开2.1 数据库与缓存独立部署持久化路径必须显式声明先处理MySQL。官方镜像mysql:8.0默认使用tmpfs临时文件系统容器一删数据库全没。正确做法是创建专用数据卷并挂载# 创建持久化卷非默认卷避免与其他项目混用 docker volume create ruoyi-mysql-data # 启动MySQL关键参数 docker run -d \ --name ruoyi-mysql \ -p 3306:3306 \ -v ruoyi-mysql-data:/var/lib/mysql \ -v $(pwd)/mysql-conf:/etc/mysql/conf.d \ -e MYSQL_ROOT_PASSWORDAdmin123 \ -e MYSQL_DATABASEry-cloud \ --restartunless-stopped \ mysql:8.0这里有两个致命细节第一-v ruoyi-mysql-data:/var/lib/mysql必须用命名卷而非路径挂载否则Windows/Mac上Docker Desktop的文件共享机制会导致IO性能暴跌第二mysql-conf目录下必须放自定义my.cnf重点配置lower_case_table_names1解决Windows大小写敏感导致的表找不到问题和max_connections1000默认151高并发下秒变连接池枯竭。我试过不配max_connections当同时有20个测试人员刷首页时后端日志疯狂打印Cannot get JDBC Connection排查半小时才发现是MySQL自己限流了。Redis同理。别用redis:alpine精简镜像它缺redis-cli调试工具。选redis:7.0并强制AOF持久化docker run -d \ --name ruoyi-redis \ -p 6379:6379 \ -v $(pwd)/redis-data:/data \ -v $(pwd)/redis-conf/redis.conf:/usr/local/etc/redis/redis.conf \ --restartunless-stopped \ redis:7.0 /usr/local/etc/redis/redis.confredis.conf里必须开appendonly yes和appendfilename appendonly.aof否则Redis重启后所有缓存丢失芋道的在线用户统计、验证码缓存全归零。某次灰度发布时运维同事图省事用了默认配置结果凌晨三点用户集中登录验证码接口超时率飙升至70%最后发现是Redis没持久化每次重启都清空。2.2 后端服务放弃JAR包直启用Maven多模块精准编译芋道后端是典型的Spring Boot多模块结构ruoyi-common工具类、ruoyi-framework权限框架、ruoyi-system系统模块、ruoyi-gen代码生成器。官方文档说“进入ruoyi-admin目录执行mvn spring-boot:run”这在开发机上OK但部署到服务器绝对不行。原因有三第一spring-boot:run会加载dev配置而生产环境必须用prod第二它不校验模块依赖版本common模块若被误升级整个系统编译通过但运行时报NoSuchMethodError第三无法控制JVM参数堆内存溢出是家常便饭。我的标准流程是全局清理mvn clean -Dmaven.test.skiptrue模块编译mvn compile -pl ruoyi-common,ruoyi-framework,ruoyi-system -am -Dmaven.test.skiptrue注意-pl指定精确模块-amalso-make自动编译依赖模块避免手动挨个编译。ruoyi-admin不在此列它只是启动入口编译它反而会因未打jar包报错。打包可执行JARmvn package -pl ruoyi-admin -Dmaven.test.skiptrue -Pprod这里-Pprod激活pom.xml里的prodProfile它会替换application-prod.yml中的数据库地址、Redis地址、JWT密钥等敏感配置。启动脚本绝不裸跑java -jar。写start.sh#!/bin/bash JAVA_OPTS-Xms512m -Xmx1024m -XX:HeapDumpOnOutOfMemoryError -XX:HeapDumpPath/opt/ruoyi/logs/heap.hprof nohup java $JAVA_OPTS -Dspring.profiles.activeprod -jar ruoyi-admin/target/ruoyi-admin.jar /opt/ruoyi/logs/start.log 21 echo $! /opt/ruoyi/pid.pid关键点-Xms512m -Xmx1024m设初始和最大堆内存相等避免GC频繁扩容-XX:HeapDumpOnOutOfMemoryError是救命稻草OOM时自动生成堆转储文件比看日志快十倍。2.3 前端工程Vue3 Vite构建必须重写base和proxy配置芋道前端用Vite构建但官方vite.config.ts里base: ./是为相对路径部署设计的。当你用Nginx反向代理到/根路径时这个配置会导致所有JS/CSS资源404。必须改为export default defineConfig({ base: /, // 关键改为绝对路径 server: { proxy: { /prod-api: { // 与后端约定的API前缀 target: http://localhost:8080, // 开发时指向本地后端 changeOrigin: true, rewrite: (path) path.replace(/^\/prod-api/, ) // 去掉前缀再转发 } } } })构建命令也非npm run build。要带环境变量# 构建生产环境包输出到dist目录 npm run build -- --mode production # 验证检查dist/index.html里script标签src是否为/assets/index.xxxx.js绝对路径如果看到./assets/...说明base没改对。这个错误会导致Nginx代理后页面白屏因为浏览器试图从当前域名下的相对路径加载JS而Nginx没配置静态资源路由。3. 外部访问攻坚Nginx反向代理不是配个location而是重构请求生命周期让局域网其他设备访问本地芋道本质是解决三层网络穿透Docker容器网络 → 宿主机网络 → 局域网设备网络。很多人卡在第一层以为配好Nginx就万事大吉却不知Nginx本身也分“宿主机模式”和“容器模式”。3.1 Nginx部署模式选择宿主机原生安装胜过Docker容器这是血泪教训。早期我贪方便用nginx:alpine容器跑Nginx配置如下# docker-compose.nginx.yml version: 3.8 services: nginx: image: nginx:alpine ports: - 80:80 - 443:443 volumes: - ./nginx.conf:/etc/nginx/nginx.conf - ./dist:/usr/share/nginx/html结果测试同事用手机连公司WiFi访问http://192.168.1.100页面能打开但登录时Network面板显示POST http://192.168.1.100/prod-api/login 502 Bad Gateway。抓包发现Nginx容器内部DNS解析不了宿主机的localhostproxy_pass http://localhost:8080里的localhost指向容器自身而非宿主机。解决方案是host.docker.internal但Windows/Mac的Docker Desktop才支持Linux原生Docker不认。所以生产部署Nginx必须宿主机原生安装# Ubuntu/Debian sudo apt update sudo apt install nginx -y sudo systemctl enable nginx然后编辑/etc/nginx/sites-available/ruoyiupstream ruoyi_backend { server 127.0.0.1:8080; # 直接指向宿主机的8080端口 } server { listen 80; server_name _; # 前端静态资源 location / { root /opt/ruoyi/dist; try_files $uri $uri/ /index.html; } # API代理关键必须匹配前端请求的/prod-api前缀 location /prod-api/ { proxy_pass http://ruoyi_backend/; # 注意末尾斜杠 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; proxy_redirect off; } # 防止直接访问后端端口安全加固 location /actuator/ { deny all; } }提示proxy_pass http://ruoyi_backend/;末尾的/是灵魂。它表示“把/prod-api/abc中的/prod-api/去掉再拼/abc转发给后端”。没有这个/就会转发/prod-api/abc后端Spring MVC找不到/prod-api/abc这个路径只能404。启用配置sudo ln -sf /etc/nginx/sites-available/ruoyi /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx3.2 局域网穿透解决“能ping通但打不开”的终极方案配完Nginx测试同事用笔记本访问http://192.168.1.100可能还是打不开。此时执行三步诊断宿主机自查curl -I http://localhost看是否返回HTTP/1.1 200 OK。如果不是Nginx没生效或端口被占。局域网设备查连通性在测试电脑CMD执行ping 192.168.1.100必须通。不通检查宿主机防火墙# Ubuntu sudo ufw allow 80 sudo ufw allow 443查端口监听netstat -tuln | grep :80确认是nginx进程在监听*:80而非其他程序如Apache。最隐蔽的故障是ping通telnet 192.168.1.100 80也通但浏览器打不开。这通常是浏览器缓存了旧的HTTPS重定向。因为芋道前端代码里写了window.location.href https:// ...。解决方案在Nginx配置里强制HTTP跳转关闭并清除浏览器HSTS缓存Chrome地址栏输入chrome://net-internals/#hsts删除对应域名。3.3 HTTPS加持Lets Encrypt免费证书实战企业环境不可能用HTTP。用Certbot申请免费证书# 安装certbot sudo apt install certbot python3-certbot-nginx -y # 申请证书需域名已解析到该IP sudo certbot --nginx -d your-domain.com # 自动续期加入crontab echo 0 12 * * 1 /usr/bin/certbot renew --quiet --post-hook /usr/sbin/systemctl reload nginx | sudo tee -a /var/spool/cron/crontabs/rootNginx配置追加SSL块server { listen 443 ssl; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; # SSL优化 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; ssl_prefer_server_ciphers off; # 其余location同上 location / { ... } location /prod-api/ { ... } } # HTTP强制跳转HTTPS server { listen 80; server_name your-domain.com; return 301 https://$server_name$request_uri; }注意证书申请时your-domain.com必须能被公网DNS解析且80端口对外开放Certbot验证需要。内网环境可用--standalone模式但需临时停Nginx。4. 企业级就绪权限、日志、监控三板斧让系统真正“活”在生产环境部署完成≠企业级就绪。芋道的“企业级”体现在它预置了生产环境必需的治理能力但这些能力默认是关闭或弱化的。必须手动激活并验证。4.1 权限体系加固从“能登录”到“数据隔离”的质变芋道的RBAC模型有三级菜单权限控制可见性、按钮权限控制操作、数据权限控制可见数据行。前两者在后台“系统管理→角色管理”里配置即可但数据权限是灵魂。以“销售部门只能看本部门客户”为例在sys_role表中给销售角色的data_scope字段设为2本部门数据在sys_user表中确保销售员工的dept_id指向销售部门ID在业务代码里所有查询客户列表的Mapper方法必须添加DataScope注解Select(SELECT * FROM sys_user WHERE del_flag 0) DataScope(deptAlias u, userAlias u) // deptAlias指部门表别名userAlias指用户表别名 ListSysUser selectUserList(SysUser user);这个注解会自动拼接SQL条件AND u.dept_id IN (SELECT dept_id FROM sys_dept WHERE dept_id ? OR dept_id IN (SELECT dept_id FROM sys_dept WHERE parent_id ?))。实测陷阱如果Mapper XML里写了where标签DataScope的动态SQL会与where冲突导致WHERE条件重复。解决方案是删掉XML里的where让DataScope统一管理。4.2 日志审计闭环ELK不是噱头是故障定位的氧气芋道默认日志输出到logs/目录但企业级要求日志可检索、可关联、可告警。必须接入ELK栈。Logstash配置logstash.confinput { file { path /opt/ruoyi/logs/ruoyi-admin.log start_position beginning sincedb_path /dev/null # 避免重启后重复读取 codec multiline { pattern ^%{TIMESTAMP_ISO8601} negate true what previous } } } filter { grok { match { message %{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:level} %{JAVACLASS:class} %{GREEDYDATA:msg} } } } output { elasticsearch { hosts [http://es:9200] index ruoyi-%{YYYY.MM.dd} } }Kibana索引模式创建ruoyi-*设置timestamp为时间字段。这样当用户反馈“提交订单失败”你可在Kibana里搜订单提交 AND ERROR5秒内定位到具体异常堆栈而非翻几十MB日志文件。4.3 JVM监控Arthas不是救火队是日常体检仪芋道后端是Java应用内存泄漏、线程阻塞、慢SQL是高频问题。Arthas是阿里巴巴开源的Java诊断工具比JVisualVM更轻量。启动后执行# 进入Arthas curl -O https://arthas.aliyun.com/arthas-boot.jar java -jar arthas-boot.jar # 查看最耗CPU的线程 thread -n 5 # 监控某个方法的调用如登录方法 watch com.ruoyi.web.controller.system.SysLoginController.login {params,returnObj} -x 3 # 查看SQL执行时间需Druid监控开启 vmtool --action getInstances --className com.alibaba.druid.pool.DruidDataSource --express #instances[0].getActiveCount()某次线上事故用户登录响应时间从200ms飙升至8s。用thread -n 5发现大量线程卡在com.ruoyi.framework.manager.AsyncManager$1.run顺藤摸瓜发现异步任务线程池被SysUserServiceImpl里的Async方法无限创建最终OOM。Arthas 3分钟定位比看堆dump快10倍。5. 最后一道防线备份、回滚、应急手册这才是企业级的底气所有技术部署终将面对两个现实硬盘损坏、配置误操作。芋道的“企业级”最终体现在可恢复性上。5.1 数据库双备份策略物理逻辑缺一不可物理备份XtraBackup针对InnoDB引擎热备份不锁表。# 安装percona-xtrabackup sudo apt install percona-xtrabackup-80 -y # 全量备份 sudo xtrabackup --backup --target-dir/backup/mysql-full-$(date %F) --userroot --passwordAdmin123 # 每日增量备份基于上次全量 sudo xtrabackup --backup --target-dir/backup/mysql-inc-$(date %F) --incremental-basedir/backup/mysql-full-2024-01-01 --userroot --passwordAdmin123逻辑备份mysqldump作为第二道保险导出SQL可读。mysqldump -uroot -pAdmin123 --single-transaction --routines --triggers ry-cloud /backup/ry-cloud-$(date %F).sql备份脚本backup.sh#!/bin/bash # 保留7天备份 find /backup -name mysql-full-* -mtime 7 -delete find /backup -name ry-cloud-*.sql -mtime 7 -delete5.2 配置中心化告别散落各处的application.yml芋道的配置分散在ruoyi-admin/src/main/resources/application-prod.yml、Nginx配置、Docker环境变量中。企业级必须统一到配置中心。推荐Nacos与芋道同源兼容性最好。启动Nacos单机版docker run -d \ --name nacos \ -p 8848:8848 \ -e MODEstandalone \ -e JVM_XMS512m -e JVM_XMX512m \ nacos/nacos-server:v2.2.3将application-prod.yml内容粘贴到Nacos配置管理Data ID设为ruoyi-admin.yamlGroup为DEFAULT_GROUP。修改ruoyi-admin的bootstrap.ymlspring: cloud: nacos: config: server-addr: 127.0.0.1:8848 file-extension: yaml group: DEFAULT_GROUP namespace: # 可设不同环境命名空间这样修改数据库密码只需在Nacos界面点几下无需重启服务。5.3 应急手册当一切失灵时3分钟重建系统写一份EMERGENCY.md放在项目根目录内容只有三行## 系统崩溃应急流程 1. **数据库恢复**xtrabackup --copy-back --target-dir/backup/mysql-full-2024-01-01 → chown -R mysql:mysql /var/lib/mysql 2. **后端回滚**cd /opt/ruoyi git checkout v3.8.0 mvn clean package -Pprod systemctl restart ruoyi-admin 3. **前端回滚**rm -rf /opt/ruoyi/dist cp -r /backup/dist-v3.8.0 /opt/ruoyi/dist systemctl reload nginx这份手册的价值远超所有炫技的部署文档。它让任何值班工程师在凌晨两点接到告警电话时能冷静执行而非手忙脚乱。我曾在某次金融客户上线前夜遭遇MySQL磁盘写满导致主从同步中断。按这份手册运维同事3分钟完成物理备份恢复业务零感知。那一刻我深刻体会到所谓企业级不是功能多炫酷而是当风暴来临时系统依然能稳稳呼吸。