【实战】RuoYi-Vue开发环境一站式部署：从零到启动的避坑指南

1. 环境准备Ubuntu系统基础配置第一次在Ubuntu上部署RuoYi-Vue时我建议先做系统级准备。很多人会忽略这个步骤结果在后续环节频繁遇到权限问题。先执行sudo apt update sudo apt upgrade -y更新系统这个操作能避免90%的依赖冲突。记得检查系统版本我用的是Ubuntu 22.04 LTS如果你用其他版本某些命令可能需要微调。开发环境最怕依赖缺失建议直接安装这个全家桶sudo apt install -y git curl wget vim net-tools openssl这些工具在后续排查问题时非常有用。比如net-tools里的netstat命令当遇到端口冲突时用sudo netstat -tulnp | grep 3306就能快速定位谁占用了MySQL端口。2. JDK安装与避坑指南RuoYi要求JDK1.8但千万别直接apt install openjdk-11-jdk我踩过坑OpenJDK的某些实现会导致RuoYi的Shiro组件报错。推荐用Oracle JDK按这个步骤操作wget https://download.oracle.com/java/17/latest/jdk-17_linux-x64_bin.deb sudo dpkg -i jdk-17_linux-x64_bin.deb配置环境变量时有个细节在/etc/environment中添加JAVA_HOME/usr/lib/jvm/jdk-17 PATH$PATH:$JAVA_HOME/bin这比写在.bashrc里更彻底对所有用户生效。验证时别只用java -version还要跑个javac命令确保开发工具链完整。3. Docker一站式部署中间件3.1 Docker引擎安装官方文档的方法需要翻墙注意规避敏感词用国内镜像源更稳curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo deb [archamd64 signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null安装后务必执行sudo usermod -aG docker $USER然后重新登录否则每次都要sudo。3.2 MySQL容器化部署RuoYi对MySQL有版本要求这个命令能拉取指定版本docker pull mysql:5.7.38 --platform linux/x86_64启动容器时重点注意字符集docker run --name ruoyi-mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORDyourpassword -e MYSQL_DATABASEry-vue -e MYSQL_CHARSETutf8mb4 -e MYSQL_COLLATIONutf8mb4_unicode_ci -d mysql:5.7.38我曾因为漏掉utf8mb4导致emoji存储异常这个字符集才是真正的UTF-8。3.3 Redis避坑配置官方说Redis3.0但实测6.x版本更稳定。启动时加上内存限制docker run --name ruoyi-redis -p 6379:6379 -d redis:6.2.6 --maxmemory 512mb --maxmemory-policy allkeys-lru这个配置能防止开发环境内存溢出。连接测试时用redis-cli -h localhost如果返回PONG就是成功了。4. 源码配置实战技巧4.1 项目克隆与IDE配置从Gitee克隆时可能会超时改用SSH协议git clone gitgitee.com:y_project/RuoYi-Vue.git用IDEA打开后记得检查Maven配置设置阿里云镜像在settings.xml中加入mirror idaliyunmaven/id urlhttps://maven.aliyun.com/repository/public/url mirrorOf*/mirrorOf /mirrorJDK要选我们安装的Oracle JDK不要用IDEA自带的4.2 数据库初始化陷阱执行SQL脚本前先创建数据库CREATE DATABASE ry-vue DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;重点来了RuoYi的SQL文件有两个ry_20210908.sql- 核心数据quartz.sql- 定时任务表用MySQL客户端连接时如果遇到ERROR 2003 (HY000)检查Docker容器的IPdocker inspect ruoyi-mysql | grep IPAddress4.3 配置文件关键修改点在ruoyi-admin/src/main/resources目录下application-druid.yml数据库连接字符串要加时区url: jdbc:mysql://localhost:3306/ry-vue?useUnicodetruecharacterEncodingutf8zeroDateTimeBehaviorconvertToNulluseSSLfalseserverTimezoneAsia/Shanghaiapplication.ymlRedis配置如果用了Dockerhost改为host.docker.internallogback.xml把/home/ruoyi/logs改为./logs否则会报路径错误5. 前后端联调实战5.1 后端启动排错用Maven编译时如果报Could not transfer artifact先执行mvn dependency:purge-local-repository启动类RuoYiApplication的日志出现猫咪ASCII艺术就成功了。如果卡住检查MySQL连接数是否够用show status like Threads_connected;Redis内存是否耗尽info memory5.2 前端环境搭建Node.js建议用nvm管理curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash nvm install 16.14.2在ruoyi-ui目录下安装依赖时如果npm install太慢npm config set registry https://registry.npmmirror.com npm install --legacy-peer-deps这个--legacy-peer-deps能解决Vue CLI和某些插件的版本冲突。5.3 跨域问题解决开发时前端npm run dev默认用8080端口后端是8081需要配置代理。修改ruoyi-ui/vue.config.jsdevServer: { proxy: { /api: { target: http://localhost:8081, changeOrigin: true, pathRewrite: { ^/api: } } } }这样前端请求/api/user/login会自动转发到后端。6. 常见问题速查手册Logback报错检查日志目录权限执行mkdir -p logs chmod 777 logsMySQL连接失败在Docker容器内登录MySQL执行ALTER USER root% IDENTIFIED WITH mysql_native_password BY password; FLUSH PRIVILEGES;前端白屏删除node_modules和package-lock.json后重新npm installIDEA报程序包不存在右键项目 - Maven - ReimportRedis连接超时检查防火墙sudo ufw allow 6379这套环境我部署过不下20次最耗时的一次是因为Ubuntu自带的MySQL客户端版本不兼容。后来总结出这个金科玉律所有依赖都用Docker容器化部署保持宿主机的干净。现在每次换新机器30分钟就能搭好全套环境。