Vben Admin 前端应用 Jenkins 自动化部署指南

项目信息

• 项目名称: RuoYi Office Vben Admin
• 技术栈: Vue 3.5 + Vite 6 + Ant Design Vue 4 + TypeScript 5.8
• 包管理器: pnpm (Monorepo 工作空间)
• Git 仓库: git@codeup.aliyun.com:676b69e335730943ed494c52/ruoyi-office/ruoyi-office-vben.git
• 应用目录: apps/web-antd
• 访问地址: http://127.0.0.1/web

部署架构

Jenkins服务器(140)                    Nginx服务器(127.0.0.1)
┌─────────────────┐                  ┌──────────────────────┐
│  Jenkins容器     │                  │  Nginx容器            │
│  - 拉取代码      │  SSH/Publish     │  - 静态文件服务       │
│  - pnpm install  │  Over SSH        │  - /data/nginx/html/  │
│  - pnpm build    │ ───────────────> │    web/               │
│  - 部署文件      │                  │  - location /web      │
└─────────────────┘                  └──────────────────────┘

前置条件

• Jenkins 服务器(140)已部署并运行
• Nginx 服务器(127.0.0.1)已部署并运行
• Jenkins 已安装 NodeJS Plugin 和 Publish Over SSH Plugin
• Jenkins 已配置 SSH 连接到 Nginx 服务器
• 两台服务器之间网络互通

部署步骤

步骤1: 配置 Vite Base 路径

已完成: vite.config.mts 已配置 base: '/web/'

该配置确保生产环境下所有静态资源路径正确指向 /web/ 前缀。

步骤1.1: 配置后端 API 地址

重要: 根据后端服务部署位置，配置 .env.production 文件。

场景1: 后端服务在同一服务器或内网可访问（推荐使用 Nginx 反向代理）

如果后端服务可以通过 Nginx 代理访问，强烈推荐使用相对路径，这样无论使用 IP 还是域名访问都能正常工作：

配置 .env.production（推荐配置）:

# 基础路径（Vite 构建时的 base 路径）
VITE_BASE=/

# 请求路径（基础URL，用于文件上传、WebSocket等）
# ⚠️ 重要：必须设置为空字符串，不能设置为 /web
# 设置为空字符串，会自动使用当前访问的域名（支持IP和域名）
# 如果设置为 /web，会导致 API 请求路径错误（变成 /web/admin-api/...）
VITE_BASE_URL=

# 接口地址（全局API URL，用于所有API请求）
# 使用相对路径，自动使用当前访问的域名（支持IP和域名）
VITE_GLOB_API_URL=/admin-api

说明:

• VITE_BASE_URL 必须设置为空字符串，不能设置为 /web
  • ❌ 错误配置：VITE_BASE_URL=/web - 会导致 API 请求路径变成 /web/admin-api/...
  • ✅ 正确配置：VITE_BASE_URL= - API 请求路径为 /admin-api/...
• VITE_GLOB_API_URL 使用相对路径 /admin-api，会自动使用当前访问的域名
• 这样配置后，无论通过 http://127.0.0.1/web 还是 https://yourdomain.com/web 访问，都能正常工作
• 无需修改配置即可切换域名，这是最佳实践

同时需要启用 Nginx 反向代理（见步骤4.3）。

场景2: 后端服务在不同服务器（直接访问）

如果后端服务部署在其他服务器，且无法通过 Nginx 代理：

配置 .env.production:

# 请求路径（基础URL，用于文件上传、WebSocket等）
VITE_BASE_URL=http://127.0.0.1:48080

# 接口地址（全局API URL，用于所有API请求）
VITE_GLOB_API_URL=http://127.0.0.1:48080/admin-api

注意: 此方案需要后端配置 CORS 允许跨域请求。

步骤2: 配置 Node.js 和 pnpm

重要说明: Jenkins 基础镜像不包含 Node.js，需要通过 NodeJS Plugin 提供 Node.js 环境。

方式1: 使用 Jenkinsfile 自动安装（推荐）

Jenkinsfile 已包含自动安装 pnpm 的逻辑（在环境检查阶段），无需手动操作。

当 Pipeline 执行时，会：

1. 使用 NodeJS Plugin 提供的 Node.js 环境
2. 自动检测 pnpm 是否存在
3. 如果不存在，自动执行 npm install -g pnpm

前提条件:

• ✅ Jenkins 已安装 NodeJS Plugin
• ✅ Jenkins 已配置 Node.js 工具（名称：node20）
• ✅ Jenkinsfile 中包含 tools { nodejs 'node20' }

方式2: 在 Jenkins 容器中手动安装 Node.js（可选）

如果需要在容器系统中安装 Node.js：

# 进入 Jenkins 容器
docker exec -it jenkins bash

# 方式A: 使用 apt 安装（适用于 Debian/Ubuntu 基础镜像）
apt-get update
apt-get install -y curl
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs

# 方式B: 使用 nvm 安装（推荐，更灵活）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install 20
nvm use 20

# 验证安装
node -v
npm -v

# 安装 pnpm
npm install -g pnpm@latest

# 验证 pnpm
pnpm -v

注意:

• 容器重启后手动安装会丢失
• 建议使用方式1（Jenkinsfile 自动安装）
• 或者使用自定义 Docker 镜像

步骤3: 配置 Publish Over SSH

复用已有配置（如果已为 ruoyi-office-doc 配置过）:

Jenkins 系统配置中的 nginx-server SSH 配置可以直接复用。

配置参数:

• Name: nginx-server
• Hostname: 127.0.0.1
• Username: root
• Remote Directory: /data/nginx/html
• Key: SSH 私钥内容

详细配置请参考 ruoyi-office-doc/JENKINS_PUBLISH_OVER_SSH.md。

步骤4: 配置 Nginx

💡 推荐: 如果您同时部署了 VitePress 文档和 Vben Admin，建议跳过此步骤，直接使用 统一配置方案。统一配置方案更易维护，性能更优。

在 Nginx 服务器(127.0.0.1)上执行:

4.1 创建部署目录

mkdir -p /data/nginx/html/web
chmod 755 /data/nginx/html/web

4.2 添加 Nginx 配置

重要: location 指令必须在 server 块内，不能单独存在。

方式1: 添加到现有配置文件（推荐）

编辑现有的 server 配置文件（通常是 /data/nginx/conf/conf.d/default.conf），在 server { ... } 块内添加 location 配置：

# 编辑现有配置
vi /data/nginx/conf/conf.d/default.conf

在 server { ... } 块内添加以下内容：

location /web {
    alias /usr/share/nginx/html/web;
    index index.html;
    try_files $uri $uri/ /web/index.html;

    charset utf-8;

    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json application/javascript;

    location ~* ^/web/.*\.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot|map)$ {
        alias /usr/share/nginx/html/web;
        expires 30d;
        add_header Cache-Control "public, immutable";
        access_log off;
    }
}

方式2: 创建完整的独立配置文件

如果想创建独立的配置文件，需要包含完整的 server 块：

cat > /data/nginx/conf/conf.d/web-antd.conf << 'EOF'
server {
    listen 80;
    server_name 127.0.0.1;  # 或使用域名

    # Vben Admin 前端应用
    location /web {
        alias /usr/share/nginx/html/web;
        index index.html;
        try_files $uri $uri/ /web/index.html;

        charset utf-8;

        gzip on;
        gzip_vary on;
        gzip_min_length 1024;
        gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json application/javascript;

        location ~* ^/web/.*\.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot|map)$ {
            alias /usr/share/nginx/html/web;
            expires 30d;
            add_header Cache-Control "public, immutable";
            access_log off;
        }

        location ~ /web/\. {
            deny all;
            access_log off;
            log_not_found off;
        }
    }
}
EOF

注意: 如果创建独立配置文件，可能与现有的 listen 80 冲突，建议使用方式1。

4.3 启用后端 API 代理（推荐）

如果后端服务部署在同一服务器或内网可访问，建议启用 Nginx 反向代理，避免跨域问题：

编辑 Nginx 配置文件:

# 编辑统一配置文件（如果使用统一配置）
vi /data/nginx/conf/conf.d/ruoyi-office.conf

# 或编辑独立配置文件
vi /data/nginx/conf/conf.d/web-antd.conf

启用 /admin-api 代理配置:

location /admin-api {
    # 代理到后端服务
    # 如果后端在同一服务器，使用 localhost
    # proxy_pass http://localhost:48080;
    
    # 如果后端在其他服务器，使用实际IP（例如：192.168.30.130）
    proxy_pass http://192.168.30.130:48080;

    # 代理头设置
    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;

    # WebSocket 支持
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # 超时设置
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;

    # 缓冲区设置
    proxy_buffer_size 64k;
    proxy_buffers 4 64k;
    proxy_busy_buffers_size 128k;
}

注意:

• 如果后端服务在其他服务器（如 192.168.30.130），需要将 proxy_pass 设置为实际的后端服务地址
• 如果后端在同一服务器，使用 http://localhost:48080
• 确保后端服务允许来自 Nginx 服务器的访问
• 配置文件已默认启用代理，只需根据实际情况修改 proxy_pass 地址

4.4 验证并重新加载 Nginx

# 验证配置
docker exec nginx nginx -t

# 重新加载配置
docker exec nginx nginx -s reload

步骤5: 创建 Jenkins Pipeline 任务

1. 登录 Jenkins Web 界面
2. 点击 新建任务
3. 输入任务名称（如：ruoyi-office-vben-web-antd-deploy）
4. 选择 流水线 (Pipeline)
5. 点击 确定
6. 在配置页面：
   • Pipeline 定义: 选择 Pipeline script from SCM
   • SCM: 选择 Git
   • Repository URL: git@codeup.aliyun.com:676b69e335730943ed494c52/ruoyi-office/ruoyi-office-vben.git
   • Credentials: 选择可以访问 Git 仓库的凭据
   • 分支: */main 或 */master（根据实际分支名）
   • 脚本路径: apps/web-antd/Jenkinsfile
7. 点击 保存

步骤6: 执行首次部署

1. 在 Jenkins 任务页面，点击 立即构建
2. 查看构建日志，确认：
   • ✅ 拉取代码：代码拉取成功
   • ✅ 环境检查：Node、npm、pnpm 版本正常
   • ✅ 安装依赖：pnpm install 成功
   • ✅ 构建应用：pnpm build 成功，生成 dist 目录
   • ✅ 部署到 Nginx：文件传输成功
   • ✅ 验证部署：显示访问地址
3. 如果构建失败，查看日志排查问题

步骤7: 验证部署

7.1 检查文件是否传输成功

# 在 Nginx 服务器上执行
ls -la /data/nginx/html/web/

应该看到 index.html、assets/ 等文件。

7.2 访问站点

浏览器访问: http://127.0.0.1/web

应该能看到 Vben Admin 登录页面。

7.3 检查 Nginx 日志

docker exec nginx tail -f /var/log/nginx/access.log
docker exec nginx tail -f /var/log/nginx/error.log

后续维护

自动触发部署

可以配置 Git Webhook，在代码推送时自动触发 Jenkins 构建：

1. 在 Git 仓库设置中添加 Webhook
2. Webhook URL: http://140:8080/github-webhook/（根据实际 Jenkins 配置）
3. 触发事件: Push events
4. 分支过滤: main 或 master

手动触发部署

在 Jenkins 任务页面点击 立即构建 即可。

查看部署历史

在 Jenkins 任务页面可以查看所有构建历史和日志。

故障排查

pnpm 未安装或找不到

问题: 构建失败，提示 pnpm: command not found 或 pnpm: not found

/var/jenkins_home/workspace/xxx@tmp/durable-xxx/script.sh.copy: 3: pnpm: not found

原因:

1. Jenkins 容器中没有 Node.js/npm（基础镜像不包含）
2. NodeJS Plugin 未正确配置
3. 不同的 sh 块是独立的 shell 会话，全局安装的 pnpm 可能无法在后续 stage 中使用
4. pnpm 未全局安装或 PATH 未正确配置

解决方案:

方案A（最佳方案，已更新）: 使用 npx 运行 pnpm

修改 Jenkinsfile，使用 npx pnpm@latest 代替 pnpm：

stage('3. 安装依赖') {
  steps {
    sh '''
      # 使用 npx 运行 pnpm，自动下载最新版本
      npx pnpm@latest install --frozen-lockfile --prefer-offline
    '''
  }
}

stage('4. 构建应用') {
  steps {
    dir(env.APP_DIR) {
      sh '''
        # 使用 npx 运行 pnpm
        npx pnpm@latest build
      '''
    }
  }
}

优势:

• ✅ 无需全局安装 pnpm
• ✅ 每次都使用最新版本
• ✅ 跨 shell 会话可用
• ✅ 更加可靠和简单

注意: 当前 Jenkinsfile 已经更新为使用 npx 方案，如果您使用的是最新版本，直接重新构建即可。

方案B（传统方案）: 确保 Jenkins 配置正确

1. 检查 NodeJS Plugin 是否已安装：

   • Jenkins管理 -> 插件管理 -> 已安装
   • 搜索 NodeJS

2. 检查 Node.js 工具是否已配置：

   • Jenkins管理 -> 全局工具配置
   • 找到 NodeJS 部分
   • 确认有名称为 node20 的配置

3. 等待 Jenkinsfile 自动安装：

   • Jenkinsfile 的环境检查阶段会自动安装 pnpm
   • 无需手动操作

方案C: 手动在容器中安装 Node.js

如果容器中提示 npm: command not found，说明容器系统中没有 Node.js：

# 进入 Jenkins 容器
docker exec -it jenkins bash

# 检查当前用户
whoami  # 如果是 jenkins 用户，需要切换到 root

# 切换到 root 用户（如需要）
# 退出容器，使用以下命令：
exit

# 以 root 用户进入
docker exec -u root -it jenkins bash

# 安装 Node.js（Debian/Ubuntu）
apt-get update
apt-get install -y curl
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt-get install -y nodejs

# 验证
node -v
npm -v

# 安装 pnpm
npm install -g pnpm@latest

# 验证
pnpm -v

# 退出
exit

方案D: 使用自定义 Jenkins 镜像（长期方案）

创建包含 Node.js 的 Jenkins 镜像：

# Dockerfile
FROM jenkins/jenkins:latest

USER root

# 安装 Node.js
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs \
    && npm install -g pnpm

USER jenkins

构建并使用：

docker build -t jenkins-with-nodejs .
docker stop jenkins
docker rm jenkins
# 使用新镜像启动 Jenkins（使用原来的启动命令，替换镜像名）

推荐:

• 最佳: 方案A（使用 npx），最简单可靠
• 次选: 方案B（Jenkins Plugin），Jenkins 的标准做法
• 备选: 方案C/D（手动安装或自定义镜像），适合特殊需求

依赖安装失败

问题: pnpm install 失败

排查步骤:

1. 检查网络连接：

   docker exec jenkins ping registry.npmjs.org

2. 检查 pnpm-lock.yaml 是否存在：

   ls -la pnpm-lock.yaml

3. 清理缓存重试：

   pnpm store prune
   pnpm install

构建失败 - Monorepo 内部包解析错误

错误信息:

Failed to resolve entry for package "@vben-core/design".
The package may have incorrect main/module/exports specified in its package.json.

或类似的内部包解析错误（如 @vben-core/*, @vben/* 等）。

原因:

1. Monorepo 内部包（workspace packages）依赖解析失败
2. 使用 --frozen-lockfile 可能导致内部包没有正确构建或链接
3. pnpm workspace 依赖处理不当

解决方案:

方式1（推荐，已更新）: 修改 pnpm install 参数

Jenkinsfile 已更新为使用 --no-frozen-lockfile：

stage('3. 安装依赖') {
  steps {
    sh '''
      # 去掉 --frozen-lockfile 确保内部包正确构建
      npx pnpm@latest install --no-frozen-lockfile
    '''
  }
}

方式2（推荐，已更新）: 添加独立的构建内部依赖包阶段

Jenkinsfile 已更新为独立的构建阶段：

stage('3. 安装依赖') {
  steps {
    sh '''
      npx pnpm@latest install --no-frozen-lockfile
    '''
  }
}

stage('4. 构建内部依赖包') {
  steps {
    sh '''
      # 构建 Monorepo 内部的 packages（@vben-core/*, @vben/* 等）
      npx pnpm@latest -r --filter "./packages/**" --filter "./internal/**" build || true
    '''
  }
}

stage('5. 构建应用') {
  steps {
    dir(env.APP_DIR) {
      sh '''
        npx pnpm@latest build
      '''
    }
  }
}

这是最可靠的方案，确保内部依赖包先于应用构建。

方式3: 手动清理并重新安装

# 进入 Jenkins 工作空间
docker exec -it jenkins bash
cd /var/jenkins_home/workspace/ruoyi-office-vben-deploy

# 清理依赖
rm -rf node_modules apps/*/node_modules packages/*/node_modules
rm -f pnpm-lock.yaml

# 重新安装
npx pnpm@latest install

# 退出
exit

推荐: 使用方式1，当前 Jenkinsfile 已更新，直接重新构建即可。

构建失败 - JavaScript 堆内存溢出

错误信息:

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

原因:

1. Node.js 默认内存限制约为 2GB，大型项目构建时可能不够
2. Vite 构建需要处理大量文件，内存消耗较大
3. Jenkins 容器内存限制可能较低

解决方案:

方式1（推荐，已更新）: Jenkinsfile 已自动配置

Jenkinsfile 已自动设置内存限制为 4GB，无需手动操作。如果仍然失败，可以增加限制：

environment {
  // 增加到 6GB 或 8GB
  NODE_MEMORY_LIMIT = '6144'  // 或 '8192'
}

方式2: 手动在构建命令中设置

# 设置内存限制为 4GB
export NODE_OPTIONS="--max-old-space-size=4096"
pnpm build

# 如果 4GB 不够，可以增加到 6GB 或 8GB
export NODE_OPTIONS="--max-old-space-size=6144"
pnpm build

方式3: 在 package.json 中配置

{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' vite build --mode production"
  }
}

内存限制参考:

• 2GB (默认): 小型项目
• 4GB: 中型项目（当前配置）
• 6GB: 大型项目
• 8GB: 超大型项目

推荐: 使用方式1，Jenkinsfile 已自动配置，无需手动操作。

构建失败 - 其他原因

问题: pnpm build 失败

常见原因:

1. TypeScript 错误: 检查构建日志中的 TS 错误
2. 环境变量缺失: 检查 .env.production 文件
3. 依赖问题: 检查 pnpm-lock.yaml 是否最新
4. 磁盘空间不足: 检查 Jenkins 工作空间磁盘空间

页面无法访问

问题: 访问 http://127.0.0.1/web 显示 404

排查步骤:

1. 检查 Nginx 配置是否生效:

   docker exec nginx nginx -T | grep -A 20 "location /web"

2. 检查文件是否存在:

   docker exec nginx ls -la /usr/share/nginx/html/web/

3. 检查 Nginx 错误日志:

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

4. 重新加载 Nginx 配置:

   docker exec nginx nginx -s reload

静态资源 404 或返回 HTML

问题: 页面可以访问，但 JS/CSS 等资源 404 或返回 HTML 内容

错误信息:

Failed to load module script: Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/html".
Uncaught SyntaxError: Unexpected token '<'

原因: Nginx 配置中 try_files 导致静态资源请求被重定向到 index.html

解决方案:

方案1: 修复 Nginx 配置（推荐）

确保静态资源在 SPA 路由之前匹配，修改 ruoyi-office.conf：

# 静态资源优先匹配（必须在 location /web 之前）
location ~* ^/web/.+\.(jpg|jpeg|png|gif|ico|css|js|mjs|svg|woff|woff2|ttf|eot|map|json)$ {
    alias /usr/share/nginx/html/web;
    try_files $uri =404;
    expires 30d;
    add_header Cache-Control "public, immutable";
    access_log off;
}

# Vben Admin 主配置
location /web {
    alias /usr/share/nginx/html/web;
    index index.html;
    try_files $uri $uri/ /web/index.html;
}

关键点:

• 静态资源的 location 块必须在 location /web 之前
• 使用正则表达式 ~* 确保优先级更高
• 静态资源使用 try_files $uri =404; 直接返回文件
• SPA 路由使用 try_files $uri $uri/ /web/index.html; 作为 fallback

方案2: 检查文件路径

# 检查文件是否存在
docker exec nginx ls -la /usr/share/nginx/html/web/assets/

# 检查 index.html 中的资源路径
docker exec nginx cat /usr/share/nginx/html/web/index.html | grep -E "\.js|\.css"

方案3: 检查 Vite base 配置

确保 vite.config.mts 中的 base 配置正确：

base: process.env.NODE_ENV === 'production' ? '/web/' : '/';

验证步骤:

1. 修改 Nginx 配置后，验证配置：

   docker exec nginx nginx -t

2. 重新加载配置：

   docker exec nginx nginx -s reload

3. 清除浏览器缓存，重新访问

4. 检查浏览器控制台，确认 JS 文件正确加载

API 请求失败

问题: 前端页面正常，但 API 请求失败

错误示例:

• 请求路径错误：http://127.0.0.1/web/admin-api/...（错误，多了 /web 前缀）
• 正确路径应该是：http://127.0.0.1/admin-api/...

常见原因:

1. .env.production 配置错误：VITE_BASE_URL 设置为 /web
2. Nginx 代理未启用：/admin-api 代理配置被注释
3. 后端服务地址错误：Nginx 代理的后端地址不正确

解决方案:

步骤1: 检查并修复 .env.production 配置

错误配置:

VITE_BASE_URL=/web  # ❌ 错误！会导致 API 请求路径变成 /web/admin-api/...

正确配置:

# 基础路径（Vite 构建时的 base 路径）
VITE_BASE=/

# 请求路径（基础URL，用于文件上传、WebSocket等）
# ⚠️ 必须设置为空字符串，不能设置为 /web
VITE_BASE_URL=

# 接口地址（全局API URL，用于所有API请求）
VITE_GLOB_API_URL=/admin-api

修复后需要重新构建:

# 在 Jenkins 中重新构建项目
# 或本地构建：
cd apps/web-antd
pnpm build

步骤2: 检查并启用 Nginx 代理

确保 ruoyi-office.conf 中的 /admin-api 代理已启用：

location /admin-api {
    # 根据实际情况修改后端地址
    proxy_pass http://192.168.30.130:48080;  # 或 http://localhost:48080
    
    # ... 其他配置 ...
}

验证并重新加载:

docker exec nginx nginx -t
docker exec nginx nginx -s reload

步骤3: 验证 API 请求

1. 检查浏览器网络面板：

   • 打开开发者工具 -> Network
   • 查看 API 请求的 URL
   • 应该是：http://127.0.0.1/admin-api/...（不是 /web/admin-api/...）

2. 测试代理是否工作：

   # 在服务器上测试
   curl http://localhost/admin-api/system/tenant/get-by-website?website=127.0.0.1

3. 检查后端服务：

   # 确认后端服务正常运行
   curl http://192.168.30.130:48080/admin-api/system/tenant/get-by-website?website=127.0.0.1

完整解决方案:

根据后端服务部署位置，有两种配置方案：

方案1: 使用 Nginx 反向代理（推荐）

适用场景: 后端服务部署在同一服务器或内网可访问

步骤1: 启用 Nginx 反向代理

编辑 ruoyi-office.conf，取消注释 /admin-api 代理配置：

location /admin-api {
    # 代理到后端服务（如果后端在同一服务器，使用 localhost）
    proxy_pass http://localhost:48080;

    # 如果后端在其他服务器，使用实际IP
    # proxy_pass http://192.168.30.130:48080;

    # 代理头设置
    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;

    # WebSocket 支持
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # 超时设置
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;

    # 缓冲区设置
    proxy_buffer_size 64k;
    proxy_buffers 4 64k;
    proxy_busy_buffers_size 128k;
}

步骤2: 配置 .env.production

# 请求路径（基础URL，用于文件上传、WebSocket等）
# 设置为空字符串，自动使用当前访问的域名（支持IP和域名）
VITE_BASE_URL=

# 接口地址（全局API URL，用于所有API请求）
# 使用相对路径，自动使用当前访问的域名（支持IP和域名）
VITE_GLOB_API_URL=/admin-api

优势:

• ✅ 不写死 IP 或域名，支持通过 IP 或域名访问
• ✅ 切换域名时无需修改配置，重新构建即可
• ✅ 支持 HTTP/HTTPS 自动切换
• ✅ 更灵活，便于迁移和部署
• ✅ 一次配置，多环境通用

步骤3: 重新加载 Nginx 配置

docker exec nginx nginx -t
docker exec nginx nginx -s reload

优势:

• ✅ 避免跨域问题
• ✅ 统一域名，更安全
• ✅ 可以统一处理 SSL/TLS
• ✅ 便于统一管理

方案2: 前端直接访问后端（跨域）

适用场景: 后端服务部署在不同服务器，且无法通过 Nginx 代理

步骤1: 配置 .env.production

# 请求路径（基础URL，用于文件上传、WebSocket等）
VITE_BASE_URL=http://127.0.0.1:48080

# 接口地址（全局API URL，用于所有API请求）
VITE_GLOB_API_URL=http://127.0.0.1:48080/admin-api

步骤2: 后端需要配置 CORS

确保后端服务允许来自 http://127.0.0.1 的跨域请求。

注意:

• 如果后端不支持 CORS，此方案不可行
• 生产环境建议使用方案1（Nginx 反向代理）

配置文件说明

• Jenkinsfile: Jenkins Pipeline 配置文件，定义了构建和部署流程
• nginx/web-antd.conf: Nginx 虚拟主机配置文件模板
• vite.config.mts: Vite 构建配置，包含 base 路径设置
• package.json: 项目依赖和构建脚本
• .env.production: 生产环境变量配置

.env.production 配置示例

推荐配置（使用相对路径，支持 IP 和域名）:

# 基础路径（Vite 构建时的 base 路径）
VITE_BASE=/

# 请求路径（基础URL，用于文件上传、WebSocket等）
# 设置为空字符串，自动使用当前访问的域名（支持IP和域名）
VITE_BASE_URL=

# 接口地址（全局API URL，用于所有API请求）
# 使用相对路径，自动使用当前访问的域名（支持IP和域名）
VITE_GLOB_API_URL=/admin-api

# 文件上传类型: server - 后端上传, client - 前端直连上传,仅支持S3服务
VITE_UPLOAD_TYPE=server

# 是否开启压缩,可以设置为 none, brotli, gzip
VITE_COMPRESS=none

# 是否开启 PWA
VITE_PWA=false

# vue-router 的模式
VITE_ROUTER_HISTORY=hash

# 是否注入全局loading
VITE_INJECT_APP_LOADING=true

# 打包后是否生成dist.zip
VITE_ARCHIVER=true

配置说明:

• VITE_BASE_URL 设置为空字符串，代码中会自动使用当前访问的域名
• VITE_GLOB_API_URL 使用相对路径 /admin-api，会自动使用当前访问的域名
• 这样配置后，无论通过 http://127.0.0.1/web 还是 https://yourdomain.com/web 访问，都能正常工作
• 切换域名时无需修改配置，只需重新构建即可

与 ruoyi-office-doc 部署的差异

项目	ruoyi-office-doc	ruoyi-office-vben/web-antd
包管理器	npm	pnpm (Monorepo)
构建命令	npm run docs:build	pnpm build
产物目录	docs/.vitepress/dist	apps/web-antd/dist
访问路径	/ruoyi-office-doc	/web
Base 配置	不需要	需要 base: '/web/'
工作目录	项目根目录	apps/web-antd
依赖安装	单项目	Monorepo 工作空间

注意事项

1. Monorepo 依赖:

   • 必须在根目录安装依赖（pnpm install）
   • web-antd 依赖 workspace 中的其他包

2. Base 路径:

   • 生产环境必须配置 base: '/web/'
   • 开发环境使用 base: '/'

3. Nginx 路径:

   • 使用 location /web 而非 location /web/
   • 使用 alias 而非 root
   • try_files 必须包含 /web/index.html

4. pnpm 版本:

   • 建议使用最新稳定版
   • 确保 Jenkins 容器中已安装

5. 构建性能:

   • Vben Admin 项目较大，构建可能需要 2-5 分钟
   • 可以考虑增加 Jenkins 容器的内存限制

6. API 配置:

   • 生产环境需要配置正确的 API 地址
   • 强烈推荐使用相对路径（VITE_BASE_URL= 和 VITE_GLOB_API_URL=/admin-api）
   • 使用相对路径可以支持 IP 和域名访问，无需修改配置
   • 建议使用 Nginx 反向代理统一管理

参考文档

• Vite 配置文档
• Vben Admin 文档
• pnpm 文档
• Nginx 配置文档
• Jenkins Pipeline 文档
• Publish Over SSH 插件文档

统一配置方案（推荐）

如果您同时部署了 VitePress 文档 和 Vben Admin 管理后台，强烈推荐使用统一的 Nginx 配置文件。

统一配置的优势

1. ✅ 配置统一管理：一个配置文件管理所有项目
2. ✅ 避免冲突：不会出现多个 server 块监听同一端口的问题
3. ✅ 易于维护：修改配置只需要编辑一个文件
4. ✅ 性能优化：统一的 Gzip、缓存策略

快速部署统一配置

项目提供了完整的统一配置文件和自动化部署脚本：

# 进入 nginx 配置目录
cd w:/ruoyi-office/ruoyi-office-vben/apps/web-antd/nginx

# 执行自动化部署脚本
chmod +x deploy-nginx-config.sh
./deploy-nginx-config.sh

相关文档

• 📄 统一配置文件 - 包含完整的 Nginx 配置
• 📄 配置说明文档 - 详细的配置说明和部署步骤
• 📄 配置对比文档 - 新旧配置对比和改进说明
• 🚀 deploy-nginx-config.sh - 自动化部署脚本（位于 nginx/ 目录下）

手动部署（可选）

如果不想使用自动化脚本，也可以手动部署：

# 1. 备份现有配置
ssh root@127.0.0.1 "mkdir -p /data/nginx/conf/conf.d/backup && cp /data/nginx/conf/conf.d/*.conf /data/nginx/conf/conf.d/backup/"

# 2. 上传新配置
scp nginx/ruoyi-office.conf root@127.0.0.1:/data/nginx/conf/conf.d/

# 3. 删除旧配置
ssh root@127.0.0.1 "cd /data/nginx/conf/conf.d && rm -f default.conf ruoyi-office-doc.conf web-antd.conf"

# 4. 验证配置
ssh root@127.0.0.1 "docker exec nginx nginx -t"

# 5. 重新加载 Nginx
ssh root@127.0.0.1 "docker exec nginx nginx -s reload"

访问地址

统一配置后的访问地址：

• VitePress 文档: http://127.0.0.1/
• Vben Admin 管理后台: http://127.0.0.1/web
• 健康检查: http://127.0.0.1/health

成功部署示例

访问 http://127.0.0.1/web 应该看到：

1. ✅ Vben Admin 登录页面
2. ✅ 页面样式正常显示
3. ✅ 静态资源加载正常
4. ✅ 路由跳转正常工作

如有问题，请参考故障排查部分或查看 Jenkins 构建日志。