Ubuntu 部署 RuoYi-Vue-FastAPI 完整实战指南（含踩坑总结）

文章目录

一、项目说明
二、为什么这篇文章值得看
三、服务器基础环境
[四、先说第一个坑：MySQL 安装失败](#四、先说第一个坑：MySQL 安装失败)
- 原因
- 解决方案
[五、初始化 MariaDB 数据库](#五、初始化 MariaDB 数据库)
- 这里有两个关键点
- - [1. 不建议用 root 给项目连库](#1. 不建议用 root 给项目连库)
  - [2. 数据库名建议统一用下划线](#2. 数据库名建议统一用下划线)
[六、导入项目 SQL](#六、导入项目 SQL)
[七、配置 Redis](#七、配置 Redis)
[八、第二个大坑：Python 版本太低，依赖安装失败](#八、第二个大坑：Python 版本太低，依赖安装失败)
- 原因
- 解决方案
[九、编译安装 Python 3.11](#九、编译安装 Python 3.11)
[十、创建 Python 虚拟环境](#十、创建 Python 虚拟环境)
十一、安装后端依赖
[十二、配置后端 `.env.prod`](#十二、配置后端 .env.prod)
- [1. 修改数据库配置](#1. 修改数据库配置)
- [2. 修改 Redis 配置](#2. 修改 Redis 配置)
- [3. 修改服务监听地址和端口](#3. 修改服务监听地址和端口)
- - 这里有一个坑
十三、前台启动后端测试
十四、构建前端
- [这里的 warning 要不要管？](#这里的 warning 要不要管？)
[十五、部署前端到 Nginx](#十五、部署前端到 Nginx)
[十六、配置 Nginx](#十六、配置 Nginx)
[十七、第三个大坑：页面能打开，但接口 502](#十七、第三个大坑：页面能打开，但接口 502)
- [1. Nginx 代理路径错了](#1. Nginx 代理路径错了)
- [2. 后端没起来](#2. 后端没起来)
- [3. 后端配置根路径不一致](#3. 后端配置根路径不一致)
- [4. 看 Nginx 错误日志](#4. 看 Nginx 错误日志)
[十八、第四个大坑：浏览器提示不支持 Web Crypto API](#十八、第四个大坑：浏览器提示不支持 Web Crypto API)
- 原因
- 临时解决方案
- 注意
[十九、第五个大坑：nohup 启动失败，日志无权限](#十九、第五个大坑：nohup 启动失败，日志无权限)
- 原因
- 解决方案
[二十、正确的 nohup 后台启动方式](#二十、正确的 nohup 后台启动方式)
- [为什么不用 `python app.py`](#为什么不用 python app.py)
[二十一、第六个大坑：address already in use](#二十一、第六个大坑：address already in use)
- 原因
- 解决方法
二十二、后台运行后的检查方法
二十三、完整部署流程总结
- 第一步：准备环境
- 第二步：下载项目
- [第三步：配置 MariaDB](#第三步：配置 MariaDB)
- [第四步：配置 Redis](#第四步：配置 Redis)
- [第五步：安装 Python 3.11](#第五步：安装 Python 3.11)
- [第六步：配置 `.env.prod`](#第六步：配置 .env.prod)
- 第七步：前台测试后端
- 第八步：构建前端
- [第九步：配置 Nginx](#第九步：配置 Nginx)
- [第十步：解决浏览器 Web Crypto](#第十步：解决浏览器 Web Crypto)
- [第十一步：nohup 后台启动](#第十一步：nohup 后台启动)
二十四、部署完成后的效果
二十五、最后的建议
- [1. systemd 开机自启](#1. systemd 开机自启)
- [2. 配置 HTTPS](#2. 配置 HTTPS)
- [3. 做日志和进程管理](#3. 做日志和进程管理)
二十六、本文踩坑总结
结语

本文不是"照搬官方 README"，而是基于一次真实部署过程整理出来的完整实战手册。

从环境安装、MariaDB、Redis、Python 3.11、前后端启动、Nginx 代理，到浏览器 Web Crypto 问题、nohup 后台运行，全部一步一步写清楚。

特别适合第一次在 Linux 服务器上部署 RuoYi-Vue-FastAPI 的同学。

一、项目说明

本次部署项目：

bash 复制代码

https://github.com/insistence/RuoYi-Vue-FastAPI

项目结构大致如下：

bash 复制代码

RuoYi-Vue-FastAPI
├── ruoyi-fastapi-backend   # FastAPI 后端
├── ruoyi-fastapi-frontend  # Vue 前端
├── ruoyi-fastapi-app

部署目标：

前端：Nginx 托管
后端：FastAPI 运行在 9099
数据库：MariaDB
缓存：Redis
访问方式：浏览器访问服务器 IP

二、为什么这篇文章值得看

因为这次部署过程中，真实踩到了这些坑：

mysql-server 安装失败
Python 版本太低，alembic==1.18.3 无法安装
数据库用户配置错误，导致连接失败
Redis 开了密码，但项目没配密码
前端能打开，后端返回 502
HTTP + IP 访问时，浏览器报 Web Crypto API 不支持
nohup 后台启动时日志无权限
重复启动后端，导致 address already in use

所以这篇文章不是空讲理论，而是把这些问题都实打实解决掉。

三、服务器基础环境

本文环境大致如下：

系统：Ubuntu / Debian 系
用户：普通用户 lcb
Web 服务：Nginx
数据库：MariaDB
缓存：Redis
Python：3.11
Node：用于前端构建

先安装基础依赖：

bash 复制代码

sudo apt update
sudo apt -y install git curl wget vim unzip zip build-essential
sudo apt -y install nginx redis-server mariadb-server
sudo apt -y install python3 python3-pip python3-venv

创建部署目录：

bash 复制代码

sudo mkdir -p /data
sudo chown -R $USER:$USER /data

克隆项目：

bash 复制代码

cd /data
git clone https://github.com/insistence/RuoYi-Vue-FastAPI.git
cd /data/RuoYi-Vue-FastAPI

四、先说第一个坑：MySQL 安装失败

很多人一上来会执行：

bash 复制代码

sudo apt -y install mysql-server

结果直接报错：

bash 复制代码

Package mysql-server is not available
E: Package 'mysql-server' has no installation candidate

原因

在很多 Ubuntu / Debian 环境中，默认提供的是 MariaDB，不是 Oracle MySQL。

解决方案

直接使用 MariaDB 即可，若依这个项目完全可以正常使用。

启动并设置开机自启：

bash 复制代码

sudo systemctl enable mariadb
sudo systemctl start mariadb
sudo systemctl status mariadb

五、初始化 MariaDB 数据库

登录数据库：

bash 复制代码

sudo mysql

执行以下 SQL：

sql 复制代码

CREATE DATABASE ruoyi_fastapi DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

CREATE USER 'ruoyi'@'localhost' IDENTIFIED BY 'Ruoyi@123456';

GRANT ALL PRIVILEGES ON ruoyi_fastapi.* TO 'ruoyi'@'localhost';

FLUSH PRIVILEGES;
EXIT;

这里有两个关键点

1. 不建议用 root 给项目连库

很多人会直接在配置里写：

python 复制代码

DB_USERNAME = 'root'
DB_PASSWORD = 'root'

这很容易出问题，因为 MariaDB 在很多环境下 root 默认是走本地 socket 登录，不适合作为业务连接账号。

2. 数据库名建议统一用下划线

建议统一用：

bash 复制代码

ruoyi_fastapi

不要一会儿写：

bash 复制代码

ruoyi-fastapi

一会儿又写：

bash 复制代码

ruoyi_fastapi

这会导致"明明建了库却连不上"的低级问题。

六、导入项目 SQL

进入后端目录：

bash 复制代码

cd /data/RuoYi-Vue-FastAPI/ruoyi-fastapi-backend

导入 SQL：

bash 复制代码

mysql -u ruoyi -p'Ruoyi@123456' ruoyi_fastapi < sql/ruoyi-fastapi.sql

检查是否成功：

bash 复制代码

mysql -u ruoyi -p'Ruoyi@123456' -D ruoyi_fastapi -e "show tables;"

只要能看到一堆表，就说明数据库初始化成功。

七、配置 Redis

启动 Redis：

bash 复制代码

sudo systemctl enable redis-server
sudo systemctl start redis-server
sudo systemctl status redis-server

编辑配置文件：

bash 复制代码

sudo vim /etc/redis/redis.conf

找到：

conf 复制代码

# requirepass foobared

改成：

conf 复制代码

requirepass Redis@123456

重启 Redis：

bash 复制代码

sudo systemctl restart redis-server

测试是否生效：

bash 复制代码

redis-cli

输入：

bash 复制代码

PING

如果提示：

bash 复制代码

(error) NOAUTH Authentication required.

说明密码已经生效。

再执行：

bash 复制代码

AUTH Redis@123456
PING

bash 复制代码

PONG

说明 Redis 正常。

八、第二个大坑：Python 版本太低，依赖安装失败

很多机器自带的是 Python 3.9。

项目安装依赖时执行：

bash 复制代码

pip install -r requirements.txt

结果报错：

bash 复制代码

ERROR: Could not find a version that satisfies the requirement alembic==1.18.3
ERROR: No matching distribution found for alembic==1.18.3

同时还会看到类似：

bash 复制代码

Requires-Python >=3.10

原因

项目依赖里的 alembic==1.18.3 要求 Python 3.10 及以上，你当前 Python 太低。

解决方案

安装 Python 3.11。

九、编译安装 Python 3.11

安装编译依赖：

bash 复制代码

sudo apt update
sudo apt -y install \
  build-essential \
  zlib1g-dev \
  libncurses5-dev \
  libgdbm-dev \
  libnss3-dev \
  libssl-dev \
  libreadline-dev \
  libffi-dev \
  libsqlite3-dev \
  libbz2-dev \
  liblzma-dev \
  tk-dev \
  uuid-dev \
  wget

下载源码：

bash 复制代码

cd /usr/local/src
sudo wget https://www.python.org/ftp/python/3.11.11/Python-3.11.11.tgz
sudo tar -xzf Python-3.11.11.tgz
cd Python-3.11.11

编译安装：

bash 复制代码

sudo ./configure --prefix=/usr/local/python3.11
sudo make -j"$(nproc)"
sudo make install

验证安装：

bash 复制代码

/usr/local/python3.11/bin/python3.11 -V
/usr/local/python3.11/bin/pip3.11 -V

正常会看到：

bash 复制代码

Python 3.11.11

十、创建 Python 虚拟环境

删除旧的低版本虚拟环境：

bash 复制代码

rm -rf /data/RuoYi-Vue-FastAPI/venv

创建新的 3.11 虚拟环境：

bash 复制代码

cd /data/RuoYi-Vue-FastAPI
/usr/local/python3.11/bin/python3.11 -m venv venv
source /data/RuoYi-Vue-FastAPI/venv/bin/activate

检查版本：

bash 复制代码

python -V
pip -V
which python

确保输出指向虚拟环境里的 Python 3.11。

十一、安装后端依赖

进入后端目录：

bash 复制代码

cd /data/RuoYi-Vue-FastAPI/ruoyi-fastapi-backend

升级工具：

bash 复制代码

pip install --upgrade pip setuptools wheel

安装依赖：

bash 复制代码

pip install -r requirements.txt

到这里，如果不再报 alembic 版本问题，说明 Python 环境已经没问题了。

十二、配置后端 `.env.prod`

打开配置文件：

bash 复制代码

vim /data/RuoYi-Vue-FastAPI/ruoyi-fastapi-backend/.env.prod

1. 修改数据库配置

把原来类似这种：

python 复制代码

DB_USERNAME = 'root'
DB_PASSWORD = 'root'
DB_DATABASE = 'ruoyi-fastapi'

改成：

python 复制代码

DB_TYPE = 'mysql'
DB_HOST = '127.0.0.1'
DB_PORT = 3306
DB_USERNAME = 'ruoyi'
DB_PASSWORD = 'Ruoyi@123456'
DB_DATABASE = 'ruoyi_fastapi'

2. 修改 Redis 配置

你 Redis 已设置密码，所以这里必须同步：

python 复制代码

REDIS_HOST = '127.0.0.1'
REDIS_PORT = 6379
REDIS_PASSWORD = 'Redis@123456'

3. 修改服务监听地址和端口

这个项目不是 HOST / PORT，而是：

python 复制代码

APP_HOST = '0.0.0.0'
APP_PORT = 9099
APP_ROOT_PATH = '/prod-api'

这里有一个坑

很多人会找：

python 复制代码

HOST = '0.0.0.0'
PORT = 9099

结果找不到。

其实这个项目实际用的是：

python 复制代码

APP_HOST
APP_PORT

一定别改错位置。

十三、前台启动后端测试

先用前台方式跑一次，确认程序本身能正常启动：

bash 复制代码

cd /data/RuoYi-Vue-FastAPI/ruoyi-fastapi-backend
source /data/RuoYi-Vue-FastAPI/venv/bin/activate
python app.py --env=prod

新开一个终端检查：

bash 复制代码

ss -lntp | grep 9099

如果看到：

bash 复制代码

0.0.0.0:9099

说明后端已成功启动。

再测试：

bash 复制代码

curl http://127.0.0.1:9099

如果返回：

json 复制代码

{"detail":"Not Found"}

这不是错误，而是 FastAPI 根路径没有定义，服务本身是正常的。

十四、构建前端

进入前端目录：

bash 复制代码

cd /data/RuoYi-Vue-FastAPI/ruoyi-fastapi-frontend

安装依赖：

bash 复制代码

npm install

构建生产包：

bash 复制代码

npm run build:prod

如果看到：

bash 复制代码

DONE  Build complete. The dist directory is ready to be deployed.

说明构建成功。

这里的 warning 要不要管？

例如：

bash 复制代码

npm warn deprecated vue@2.x
npm warn deprecated core-js@2.x
119 vulnerabilities

这些通常是老项目常见提示，不影响当前部署，不用在这个阶段纠结。

十五、部署前端到 Nginx

创建前端目录：

bash 复制代码

sudo mkdir -p /var/www/ruoyi
sudo rm -rf /var/www/ruoyi/*
sudo cp -r /data/RuoYi-Vue-FastAPI/ruoyi-fastapi-frontend/dist/* /var/www/ruoyi/

十六、配置 Nginx

创建配置文件：

bash 复制代码

sudo vim /etc/nginx/sites-available/ruoyi.conf

写入：

nginx 复制代码

server {
    listen 80;
    server_name _;

    root /var/www/ruoyi;
    index index.html index.htm;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /prod-api/ {
        proxy_pass http://127.0.0.1:9099/;
        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_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

启用配置：

bash 复制代码

sudo ln -sf /etc/nginx/sites-available/ruoyi.conf /etc/nginx/sites-enabled/ruoyi.conf
sudo rm -f /etc/nginx/sites-enabled/default

检查并重启：

bash 复制代码

sudo nginx -t
sudo systemctl restart nginx
sudo systemctl enable nginx

十七、第三个大坑：页面能打开，但接口 502

部署后，如果你遇到前端提示：

text 复制代码

系统接口502异常

那大概率是这几个问题：

1. Nginx 代理路径错了

必须保证：

nginx 复制代码

location /prod-api/ {
    proxy_pass http://127.0.0.1:9099/;
}

注意 proxy_pass 末尾的 / 不要少。

2. 后端没起来

执行：

bash 复制代码

ps -ef | grep app.py
ss -lntp | grep 9099

3. 后端配置根路径不一致

.env.prod 里必须有：

python 复制代码

APP_ROOT_PATH = '/prod-api'

4. 看 Nginx 错误日志

bash 复制代码

tail -f /var/log/nginx/error.log

这个日志最能直接说明 502 的原因。

十八、第四个大坑：浏览器提示不支持 Web Crypto API

如果你直接用：

text 复制代码

http://服务器IP

访问，登录页会提示：

text 复制代码

当前浏览器不支持 Web Crypto API

原因

浏览器对 Web Crypto API 有安全限制。

一般要求：

https://域名
或 http://localhost

而你现在是：

http://IP

所以被浏览器拦了。

临时解决方案

在本地 Mac 上用 Chrome 特殊参数启动：

bash 复制代码

killall "Google Chrome"
open -n -a "Google Chrome" --args \
--unsafely-treat-insecure-origin-as-secure="http://你的服务器IP" \
--user-data-dir=/tmp/chrome-test

然后重新访问：

text 复制代码

http://你的服务器IP

这时你会看到顶部灰色提示，但验证码会正常显示，系统就能正常登录。

注意

这个方法只适合测试环境。

正式环境建议还是上：

域名
HTTPS

十九、第五个大坑：nohup 启动失败，日志无权限

很多人想让后端后台运行，会执行：

bash 复制代码

nohup python app.py --env=prod > /var/log/ruoyi.log 2>&1 &

结果报错：

bash 复制代码

Permission denied

原因

普通用户没有直接写 /var/log/ruoyi.log 的权限。

解决方案

先创建日志文件并授权：

bash 复制代码

sudo touch /var/log/ruoyi.log
sudo chmod 666 /var/log/ruoyi.log

二十、正确的 nohup 后台启动方式

推荐使用绝对路径，不依赖当前 shell 环境：

bash 复制代码

nohup /data/RuoYi-Vue-FastAPI/venv/bin/python \
/data/RuoYi-Vue-FastAPI/ruoyi-fastapi-backend/app.py \
--env=prod > /var/log/ruoyi.log 2>&1 &

为什么不用 `python app.py`

因为你系统里可能没有全局 python 命令，或者不是虚拟环境里的解释器。

绝对路径最稳。

二十一、第六个大坑：address already in use

如果你后面又重复执行了 nohup，很可能会在日志里看到：

bash 复制代码

[Errno 98] error while attempting to bind on address ('0.0.0.0', 9099): address already in use

原因

9099 已经被旧进程占用，你又启动了一次。

解决方法

先找到旧进程：

bash 复制代码

ps -ef | grep app.py

杀掉旧进程：

bash 复制代码

kill -9 进程ID

确认端口已释放：

bash 复制代码

ss -lntp | grep 9099

然后重新启动：

bash 复制代码

nohup /data/RuoYi-Vue-FastAPI/venv/bin/python \
/data/RuoYi-Vue-FastAPI/ruoyi-fastapi-backend/app.py \
--env=prod > /var/log/ruoyi.log 2>&1 &

二十二、后台运行后的检查方法

检查进程：

bash 复制代码

ps -ef | grep app.py

检查端口：

bash 复制代码

ss -lntp | grep 9099

查看日志：

bash 复制代码

tail -f /var/log/ruoyi.log

只要：

进程存在
9099 在监听
日志没有致命报错

就说明后端已经稳定运行。

二十三、完整部署流程总结

如果你想快速复盘，整个过程大致就是：

第一步：准备环境

bash 复制代码

sudo apt update
sudo apt -y install git curl wget vim unzip zip build-essential
sudo apt -y install nginx redis-server mariadb-server
sudo apt -y install python3 python3-pip python3-venv

第二步：下载项目

bash 复制代码

cd /data
git clone https://github.com/insistence/RuoYi-Vue-FastAPI.git

第三步：配置 MariaDB

建库 ruoyi_fastapi
建用户 ruoyi
导入 SQL

第四步：配置 Redis

设置密码 Redis@123456
项目配置同步密码

第五步：安装 Python 3.11

编译安装
创建虚拟环境
安装 requirements

第六步：配置 `.env.prod`

数据库
Redis
APP_HOST
APP_PORT
APP_ROOT_PATH

第七步：前台测试后端

bash 复制代码

python app.py --env=prod

第八步：构建前端

bash 复制代码

npm install
npm run build:prod

第九步：配置 Nginx

托管 dist
代理 /prod-api/

第十步：解决浏览器 Web Crypto

临时用 Chrome 参数
正式环境建议 HTTPS

第十一步：nohup 后台启动

bash 复制代码

nohup /data/RuoYi-Vue-FastAPI/venv/bin/python \
/data/RuoYi-Vue-FastAPI/ruoyi-fastapi-backend/app.py \
--env=prod > /var/log/ruoyi.log 2>&1 &

二十四、部署完成后的效果

部署成功后你应该具备这些状态：

可以正常打开登录页
验证码正常显示
可以成功登录后台
菜单加载正常
页面接口不再 502
后端可后台长期运行

二十五、最后的建议

这次我们用 nohup 已经能让服务稳定跑起来，但如果要更正式一点，建议下一步做：

1. systemd 开机自启

这样服务器重启后，服务也会自动拉起来。

2. 配置 HTTPS

现在为了绕过浏览器 Web Crypto 限制，用了 Chrome 启动参数。

测试环境没问题，但正式环境应该：

绑定域名
配置 HTTPS
去掉浏览器特殊参数

3. 做日志和进程管理

至少建议定期检查：

bash 复制代码

tail -f /var/log/ruoyi.log

二十六、本文踩坑总结

最后把本次真实遇到的问题总结成一句话版：

问题	原因	解决办法
`mysql-server` 装不上	系统默认用 MariaDB	改用 mariadb-server
`alembic` 安装失败	Python 太低	安装 Python 3.11
数据库连接失败	用了 root / 库名不一致	使用 `ruoyi` 用户，统一 `ruoyi_fastapi`
Redis 连不上	设置了密码但项目没配	`.env.prod` 同步密码
接口 502	Nginx 代理或后端路径错	配置 `/prod-api/` 代理
Web Crypto 报错	HTTP + IP 被浏览器限制	Chrome 临时参数或正式上 HTTPS
nohup 日志权限报错	`/var/log/ruoyi.log` 无权限	先创建并授权
address already in use	重复启动	杀旧进程再启动

结语

这次部署下来，最大的体会就是：

Linux 部署项目，真正难的不是"命令不会写"，而是"每一层都可能有配置细节"。

从 Python 版本、数据库账户、Redis 密码，到 Nginx 路径、浏览器安全策略，每一层只要差一点，最后表现出来都可能是"页面打不开""接口 502""登录异常"。

所以最稳的做法永远是：

一层一层验证
每一步都确认结果
出错先看日志，再看配置

如果你也在部署 RuoYi-Vue-FastAPI，希望这篇文章能帮你少踩几个坑。

Ubuntu 部署 RuoYi-Vue-FastAPI 完整实战指南（含踩坑总结）

文章目录

一、项目说明

二、为什么这篇文章值得看

三、服务器基础环境

四、先说第一个坑：MySQL 安装失败

原因

解决方案

五、初始化 MariaDB 数据库

这里有两个关键点

1. 不建议用 root 给项目连库

2. 数据库名建议统一用下划线

六、导入项目 SQL

七、配置 Redis

八、第二个大坑：Python 版本太低，依赖安装失败

原因

解决方案

九、编译安装 Python 3.11

十、创建 Python 虚拟环境

十一、安装后端依赖

十二、配置后端 .env.prod

1. 修改数据库配置

2. 修改 Redis 配置

3. 修改服务监听地址和端口

这里有一个坑

十三、前台启动后端测试

十四、构建前端

这里的 warning 要不要管？

十五、部署前端到 Nginx

十六、配置 Nginx

十七、第三个大坑：页面能打开，但接口 502

1. Nginx 代理路径错了

2. 后端没起来

3. 后端配置根路径不一致

4. 看 Nginx 错误日志

十八、第四个大坑：浏览器提示不支持 Web Crypto API

原因

临时解决方案

注意

十九、第五个大坑：nohup 启动失败，日志无权限

原因

解决方案

二十、正确的 nohup 后台启动方式

为什么不用 python app.py

二十一、第六个大坑：address already in use

原因

解决方法

二十二、后台运行后的检查方法

二十三、完整部署流程总结

第一步：准备环境

第二步：下载项目

第三步：配置 MariaDB

第四步：配置 Redis

第五步：安装 Python 3.11

第六步：配置 .env.prod

第七步：前台测试后端

第八步：构建前端

第九步：配置 Nginx

第十步：解决浏览器 Web Crypto

第十一步：nohup 后台启动

二十四、部署完成后的效果

二十五、最后的建议

1. systemd 开机自启

2. 配置 HTTPS

3. 做日志和进程管理

二十六、本文踩坑总结

结语

十二、配置后端 `.env.prod`

为什么不用 `python app.py`

第六步：配置 `.env.prod`