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 [arch=amd64 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_PASSWORD=yourpassword -e MYSQL_DATABASE=ry-vue -e MYSQL_CHARSET=utf8mb4 -e MYSQL_COLLATION=utf8mb4_unicode_ci -d mysql:5.7.38我曾因为漏掉utf8mb4导致emoji存储异常，这个字符集才是真正的UTF-8。
3.3 Redis避坑配置
官方说Redis>=3.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 git@gitee.com:y_project/RuoYi-Vue.git用IDEA打开后，记得检查Maven配置：
- 设置阿里云镜像：在
settings.xml中加入
<mirror> <id>aliyunmaven</id> <url>https://maven.aliyun.com/repository/public</url> <mirrorOf>*</mirrorOf> </mirror>- JDK要选我们安装的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容器的IP：
docker inspect ruoyi-mysql | grep IPAddress4.3 配置文件关键修改点
在ruoyi-admin/src/main/resources目录下：
application-druid.yml：数据库连接字符串要加时区
url: jdbc:mysql://localhost:3306/ry-vue?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=Asia/Shanghaiapplication.yml：Redis配置如果用了Docker，host改为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 memory
5.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.js：
devServer: { proxy: { '/api': { target: 'http://localhost:8081', changeOrigin: true, pathRewrite: { '^/api': '' } } } }这样前端请求/api/user/login会自动转发到后端。
6. 常见问题速查手册
- Logback报错：检查日志目录权限，执行
mkdir -p logs && chmod 777 logs - MySQL连接失败：在Docker容器内登录MySQL执行：
ALTER USER 'root'@'%' IDENTIFIED WITH mysql_native_password BY 'password'; FLUSH PRIVILEGES; - 前端白屏：删除
node_modules和package-lock.json后重新npm install - IDEA报程序包不存在：右键项目 -> Maven -> Reimport
- Redis连接超时：检查防火墙
sudo ufw allow 6379
这套环境我部署过不下20次，最耗时的一次是因为Ubuntu自带的MySQL客户端版本不兼容。后来总结出这个金科玉律：所有依赖都用Docker容器化部署，保持宿主机的干净。现在每次换新机器，30分钟就能搭好全套环境。
