Ubuntu 系统部署 Vue/Vite 应用到 Nginx

文章目录

[Ubuntu 系统部署 Vue/Vite 应用到 Nginx](#Ubuntu 系统部署 Vue/Vite 应用到 Nginx)
- 一、核心概念与文件结构
- - [1. Nginx 配置加载优先级](#1. Nginx 配置加载优先级)
- 二、部署前准备工作
- - [1. 环境变量配置](#1. 环境变量配置)
  - [2. 构建项目](#2. 构建项目)
- [三、Nginx 配置方案（二选一）](#三、Nginx 配置方案（二选一）)
- - [方案 A：在 `/etc/nginx/nginx.conf` 主文件中添加（推荐，更可靠）](#方案 A：在 /etc/nginx/nginx.conf 主文件中添加（推荐，更可靠）)
  - [方案 B：在 `sites-enabled/default` 中添加](#方案 B：在 sites-enabled/default 中添加)
- 四、文件部署与权限设置
- - [1. 创建目录并复制文件](#1. 创建目录并复制文件)
  - [2. 设置所有权和权限（必须执行）](#2. 设置所有权和权限（必须执行）)
- 五、访问方式
- - 子应用模式（本方案）
  - [独立域名模式（需要额外配置 DNS）](#独立域名模式（需要额外配置 DNS）)
- 六、故障排查速查表
- - [问题 1：访问 `/flux` 报 404 Not Found](#问题 1：访问 /flux 报 404 Not Found)
  - [问题 2：修改配置后没生效](#问题 2：修改配置后没生效)
  - [问题 3：权限不足无法编辑文件](#问题 3：权限不足无法编辑文件)
- 七、快速命令汇总
- 八、部署流程图
- 九、关键注意事项总结

Ubuntu 系统部署 Vue/Vite 应用到 Nginx

一、核心概念与文件结构

1. Nginx 配置加载优先级

主配置文件： /etc/nginx/nginx.conf
虚拟主机配置： /etc/nginx/sites-enabled/*（通过软链接加载 sites-available 里的文件）

关键原则：

sites-available 目录只是文件存放地，不会自动加载
sites-enabled 目录里的软链接才是真正被 Nginx 加载的配置
如果在 nginx.conf 主文件里已经定义了 server { listen 80; server_name IP; }，它会优先于 sites-enabled 里的配置匹配
修改配置后必须执行 sudo nginx -s reload 才能生效

二、部署前准备工作

1. 环境变量配置

编辑 .env.production 文件：

bash 复制代码

# 子应用模式（推荐，共用端口）
VITE_APP_BASE_API = '/flux/server'

# 独立域名模式（需要新域名）
# VITE_APP_BASE_API = '/server'

2. 构建项目

bash 复制代码

npm run build:prod   # 生成 dist/ 目录

三、Nginx 配置方案（二选一）

方案 A：在 `/etc/nginx/nginx.conf` 主文件中添加（推荐，更可靠）

适用场景： 当你执行 sudo nginx -t 看到 the configuration file /etc/nginx/nginx.conf 时

操作步骤：

备份主配置文件

bash 复制代码

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup

复制代码

# ==========================================
# 全局配置段
# ==========================================
user www-data;                     # Nginx 工作进程运行用户
worker_processes auto;             # 自动根据 CPU 核数启动进程
pid /run/nginx.pid;                # 主进程 PID 文件
error_log /var/log/nginx/error.log; # 全局错误日志
include /etc/nginx/modules-enabled/*.conf; # 加载动态模块

events {
    worker_connections 768;        # 每个 worker 最大连接数
}

# ==========================================
# HTTP 配置段
# ==========================================
http {
    # 基础性能优化
    sendfile on;                   # 开启零拷贝文件传输
    tcp_nopush on;                 # 减少网络报文段数量
    types_hash_max_size 2048;      # MIME 类型哈希表大小
    
    # MIME 类型配置
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # SSL 协议配置（仅为预留，当前 server 块未启用 443）
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;

    # 日志配置
    access_log /var/log/nginx/access.log;

    # Gzip 压缩
    gzip on;

    # 引入其他配置文件（通常为空）
    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;

    # ==========================================
    # 核心：主应用 + Flux 子应用虚拟主机
    # ==========================================
    server {
        listen 80;                           # 仅监听 IPv4 的 80 端口（HTTP）
        server_name 10.8.100.102;            # 精确匹配服务器 IP 地址

        # LASA_Data_Hub 主应用配置
        root /home/lasahub/LASA_Data_Hub_v1/frontend/dist;
        index index.html;

        location / {
            try_files $uri $uri/ /index.html; # 支持前端路由 history 模式
        }

        location /api/ {
            proxy_pass http://localhost:8899/api/; # 主应用后端代理
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }

        # Flux 子应用配置（关键部分）
        location /flux {
            alias /var/www/flux-frontend/dist;     # Flux 前端打包文件路径
            try_files $uri $uri/ /flux/index.html; # 必须包含子路径 /flux
        }

        location /flux/server {
            proxy_pass http://localhost:9099/api/; # Flux 后端 API 代理
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

编辑主文件

bash 复制代码

sudo nano /etc/nginx/nginx.conf

找到 server_name 你的IP; 所在的 server { listen 80; ... } 块，在其内部追加：

nginx 复制代码

# ============= 新增 Flux 子应用配置 =============
location /flux {
    alias /var/www/flux-frontend/dist;          # 注意：用 alias，末尾不加 /
    try_files $uri $uri/ /flux/index.html;      # 注意：必须以 /flux 开头
}

location /flux/server {
    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;
}
# ============= 新增结束 =============

测试并 reload

bash 复制代码

sudo nginx -t              # 必须看到 "test is successful"
sudo nginx -s reload

方案 B：在 `sites-enabled/default` 中添加

适用场景： 主文件里没有 server_name IP; 这种具体 server 块时

操作步骤：

确认软链接存在

bash 复制代码

ls -l /etc/nginx/sites-enabled/
# 应该看到：default -> /etc/nginx/sites-available/default

如果没有，创建链接：

bash 复制代码

sudo ln -s /etc/nginx/sites-available/default /etc/nginx/sites-enabled/

编辑 default 文件

bash 复制代码

sudo nano /etc/nginx/sites-available/default

在 server { listen 443 ssl ... } 块内追加相同的 location /flux {...} 配置
测试并 reload

bash 复制代码

sudo nginx -t
sudo nginx -s reload

四、文件部署与权限设置

1. 创建目录并复制文件

bash 复制代码

# 创建目标目录
sudo mkdir -p /var/www/flux-frontend/dist

# 复制打包后的文件（在项目根目录执行）
cp -r dist/* /var/www/flux-frontend/dist/

# 如果提示权限不足，在前面加 sudo
sudo cp -r dist/* /var/www/flux-frontend/dist/

2. 设置所有权和权限（必须执行）

bash 复制代码

# 把文件所有者改为 Nginx 进程用户（通常是 www-data）
sudo chown -R www-data:www-data /var/www/flux-frontend/dist

# 设置权限：所有者可读写执行，其他人只读执行
sudo chmod -R 755 /var/www/flux-frontend/dist

验证：

bash 复制代码

ls -ld /var/www/flux-frontend/dist
# 应显示：drwxr-xr-x www-data www-data /var/www/flux-frontend/dist

ls -l /var/www/flux-frontend/dist/index.html
# 应显示：-rw-r--r-- www-data www-data index.html

五、访问方式

子应用模式（本方案）

复制代码

http://<服务器IP>/flux
https://<服务器IP>/flux  （如果主文件里有 HTTPS 配置）

注意：

浏览器会提示证书不安全（因为证书是域名的，不是 IP 的），点击"继续访问"即可测试
等域名 lasahub.inventec.com 批下来后，直接用域名访问，证书警告会消失

独立域名模式（需要额外配置 DNS）

复制代码

https://flux.lasahub.inventec.com

六、故障排查速查表

问题 1：访问 `/flux` 报 404 Not Found

排查步骤：

检查文件是否存在

bash 复制代码

sudo ls -l /var/www/flux-frontend/dist/index.html

如果报错 No such file or directory → 文件没拷进去，重新执行 cp 命令

检查 Nginx 权限

bash 复制代码

sudo chown -R www-data:www-data /var/www/flux-frontend/dist
sudo nginx -s reload

看实时错误日志（最关键）

bash 复制代码

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

然后浏览器刷新 /flux，看日志里具体报什么路径找不到
如果显示 /var/www/flux-frontend/distflux/index.html → try_files 写错了，必须 /flux/index.html

检查 Nginx 配置是否已加载

bash 复制代码

sudo nginx -T | grep "/flux"
# 必须能看到 location /flux 和 location /flux/server 的内容

问题 2：修改配置后没生效

原因： 没 reload 或改错了文件

解决：

bash 复制代码

# 确认修改的是哪个文件
sudo nginx -t

# 必须 reload
sudo nginx -s reload

# 如果 reload 没效果，检查进程
ps aux | grep nginx
# 如果有多个 master 进程，说明有旧的 Nginx 没关闭，需要重启
sudo systemctl restart nginx

问题 3：权限不足无法编辑文件

正确做法：

bash 复制代码

# 不要改文件所有者！用 sudo 编辑
sudo nano /etc/nginx/nginx.conf

错误做法：

bash 复制代码

# 极其危险，不要这样做
chmod 777 /etc/nginx/nginx.conf
chown your-user /etc/nginx/...

七、快速命令汇总

bash 复制代码

# 1. 查看 Nginx 加载哪个配置文件
sudo nginx -t

# 2. 测试配置语法
sudo nginx -t

# 3. 重载配置（修改后必须执行）
sudo nginx -s reload

# 4. 重启 Nginx（当 reload 无效时）
sudo systemctl restart nginx

# 5. 查看错误日志
sudo tail -f /var/log/nginx/error.log

# 6. 查看访问日志
sudo tail -f /var/log/nginx/access.log

# 7. 检查端口监听
sudo netstat -tuln | grep nginx

# 8. 清理 dist 目录（重新部署前）
sudo rm -rf /var/www/flux-frontend/dist

八、部署流程图

是
否
修改 .env.production
npm run build:prod
SSH 登录服务器
备份 nginx.conf
编辑 nginx.conf 添加 location /flux
测试配置 sudo nginx -t
重载 Nginx sudo nginx -s reload
删除旧 dist sudo rm -rf ...
复制新文件 cp -r dist/* ...
设置权限 chown & chmod
浏览器访问 http://IP/flux
看到 404?
检查日志 tail -f /var/log/nginx/error.log
部署成功!

九、关键注意事项总结

server_name 不重要时 ：用 _ 或 IP 都能匹配，关键是 listen 端口
alias vs root ：alias 用于子路径，root 用于根域名
try_files 路径 ：必须以子路径开头，如 /flux/index.html
proxy_pass 格式 ：末尾不要加 / 和空格
权限：每次复制文件后都必须 chown 和 chmod
重载：每次修改 Nginx 配置后必须 sudo nginx -s reload
测试：sudo nginx -t 能发现 90% 的语法错误

最终验证命令（按顺序执行一次）：

bash 复制代码

sudo nginx -t
sudo nginx -s reload
ls -l /var/www/flux-frontend/dist/index.html
sudo chown -R www-data:www-data /var/www/flux-frontend/dist
# 浏览器访问：http://<你的IP>/flux

Ubuntu 系统部署 Vue/Vite 应用到 Nginx

文章目录