风机数据管理平台 — 前端部署说明

项目	说明
文档版本	V1.0
适用工程	performance-test（Vue 2 前端）
目标服务器	`10.172.12.211`
部署目录	`/usr/local/nginx/html/dist-analyse/`
访问地址	`http://10.172.12.211:8899/`
Nginx 配置	`/usr/local/nginx/conf/nginx.conf`

1. 部署架构说明

生产环境由 Nginx 静态托管前端 + 反向代理后端接口 组成，浏览器只访问 8899 端口，接口通过同源路径转发，无需在页面中写死后端 IP。

浏览器
  │
  ├─ GET  /、/js/*、/css/*、/runtime-config.js     →  Nginx 静态目录 dist-analyse
  ├─ GET  /dist/*（Luckysheet 等公共资源）          →  dist-analyse/dist/*
  ├─ /api/*                                        →  10.172.12.211:16200
  ├─ /healthApi/*                                  →  10.172.12.211:16880
  ├─ /DatangEnosData/*                             →  10.172.12.212:8101
  └─ /tiles/*                                      →  服务器本地 /data/roadmap

1.1 与开发环境的差异

项目	本地开发（`npm run serve:dt`）	生产部署
页面访问	`http://本机IP:8080`	`http://10.172.12.211:8899`
主业务 API	`vue.config.js` 代理 `/api` → `.env.dt` 中 `VUE_APP_APIPROXY`	浏览器请求 `/api`，由 Nginx 转发
健康/异常/尾流 API	代理 `/healthApi`	浏览器请求 `/healthApi`，由 Nginx 转发
EnOS 驾驶舱 API	代理 `/DatangEnosData`	浏览器请求 `/DatangEnosData`，由 Nginx 转发
地图瓦片	代理 `/tiles`	浏览器请求 `/tiles`，由 Nginx 读本地目录

前端运行时默认使用相对路径（见 src/utils/request.js、src/utils/healthRequest.js）：

主接口：/api
健康分析：/healthApi

生产构建时无需把后端地址打进 JS，只要 Nginx 代理配置正确即可。

2. 部署前准备

2.1 本地构建机要求

软件	建议版本
Node.js	16.x 或 18.x（LTS）
npm	8.x 及以上

2.2 服务器要求

项目	要求
操作系统	已安装 Nginx，监听 `8899`
部署目录	`/usr/local/nginx/html/dist-analyse/` 存在且可写
后端服务	`16200`（主 API）、`16880`（健康分析）已启动
地图瓦片	`/data/roadmap` 目录存在（驾驶舱地图使用）

2.3 构建模式选择

大唐分析环境使用 dt 模式（对应 .env.dt）：

配置项	值
构建命令	`npm run build:dt`
主题	`tech-blue`
系统标题	机组健康评估与异常检测系统
首页驾驶舱	已启用

3. 构建前环境变量检查

部署到 10.172.12.211:8899 前，请确认 .env.dt 中与页面直连地址相关的变量如下（其余 VUE_APP_*PROXY 主要供本地 devServer 代理，生产可不依赖）：

# 页面标题（也可部署后改 runtime-config.js）
VUE_APP_TITLE='机组健康评估与异常检测系统'
VUE_APP_THEM="tech-blue"
VUE_APP_PROJECT='dt'

# 地图瓦片：须走 Nginx /tiles 代理
VUE_APP_MAPVIEW=/tiles/{z}/{x}/{y}.png

# 文件上传：建议走 Nginx 同源，避免跨域
VUE_APP_UPLOAD="http://10.172.12.211:8899/api/energy-manage-service/api/check/upload"

说明： VUE_APP_APIPROXY、VUE_APP_HEALTH_APIPROXY 等仅在 npm run serve:dt 时生效；生产环境接口走 /api、/healthApi 相对路径。

4. 本地构建步骤

在项目根目录执行：

# 1. 安装依赖（首次或 package.json 变更后）
npm install

# 2. 使用 dt 环境打包
npm run build:dt

构建成功后，产物位于项目根目录 dist/，主要结构：

dist/
├── index.html
├── runtime-config.js      # 运行时标题配置，部署后可单独修改
├── config/
│   └── config.js          # _BASE_CONFIG（默认 API: /api）
├── dist/                  # Luckysheet 等静态依赖（index.html 以 /dist/ 引用）
│   ├── plugins/
│   ├── css/
│   └── luckysheet.umd.js
├── js/
├── css/
└── ...

5. 上传至服务器

5.1 目录约定

路径	用途
`/usr/local/nginx/html/dist-analyse/`	前端构建产物（本系统）
`/usr/local/nginx/conf/nginx.conf`	Nginx 主配置

Nginx 中已配置：

location / {
    root   html/dist-analyse/;
    index  index.html;
    try_files $uri $uri/ /index.html =404;
}

即静态根目录为 /usr/local/nginx/html/dist-analyse/。

5.2 推荐发布流程

# 在本地项目根目录，将 dist 目录打包
cd /path/to/performance-test
tar -czf dist-analyse-$(date +%Y%m%d).tar.gz -C dist .

# 上传到服务器（示例，按实际账号替换）
scp dist-analyse-20260701.tar.gz user@10.172.12.211:/tmp/

# SSH 登录服务器
ssh user@10.172.12.211

在服务器上执行：

# 备份旧版本（建议保留最近 1～2 个版本）
sudo mv /usr/local/nginx/html/dist-analyse \
        /usr/local/nginx/html/dist-analyse.bak.$(date +%Y%m%d%H%M)

# 创建新目录并解压
sudo mkdir -p /usr/local/nginx/html/dist-analyse
sudo tar -xzf /tmp/dist-analyse-20260701.tar.gz -C /usr/local/nginx/html/dist-analyse

# 权限（按运维规范调整用户/组）
sudo chown -R nginx:nginx /usr/local/nginx/html/dist-analyse
sudo chmod -R 755 /usr/local/nginx/html/dist-analyse

也可使用 rsync 增量同步：

rsync -avz --delete dist/ user@10.172.12.211:/usr/local/nginx/html/dist-analyse/

注意： 使用 --delete 会删除目标端多余文件，执行前务必确认目录正确。

6. Nginx 配置说明

配置文件路径：/usr/local/nginx/conf/nginx.conf

当前与本系统相关的 server 块摘要如下：

6.1 反向代理映射

前端请求路径	转发目标	说明
`/api/`	`http://10.172.12.211:16200/`	主业务后端（登录、权限、能管等）
`/healthApi/`	`http://10.172.12.211:16880/`	健康评估、异常检测、尾流分析等
`/DatangEnosData/`	`http://10.172.12.212:8101/`	驾驶舱 EnOS 相关接口
`/tiles`	`alias /data/roadmap`	地图瓦片静态资源

6.2 修改配置后重载 Nginx

# 检查配置语法
sudo /usr/local/nginx/sbin/nginx -t

# 重载（不中断服务）
sudo /usr/local/nginx/sbin/nginx -s reload

仅更新前端静态文件时，无需重载 Nginx；修改 nginx.conf 或后端地址后必须执行 nginx -t 与 reload。

6.3 Vue Router history 模式

location / 已配置 try_files $uri $uri/ /index.html，支持前端路由刷新不 404。若子路径刷新异常，请检查该配置是否被改动。

7. 部署后配置（无需重新打包）

7.1 修改系统标题

编辑服务器上的文件：

vi /usr/local/nginx/html/dist-analyse/runtime-config.js

修改 title 字段后保存，清除浏览器缓存或强制刷新即可生效，无需重新 npm run build。

7.2 修改 API 前缀（特殊情况）

默认 dist/config/config.js：

window._BASE_CONFIG = { API: "/api" };

若需调整主接口前缀，可修改该文件；健康接口默认使用 /healthApi（见 src/utils/healthRequest.js）。一般保持默认即可。

8. 验收检查清单

部署完成后，按下列项逐项验证：

编号	检查项	操作	预期结果
D-01	首页访问	浏览器打开 `http://10.172.12.211:8899/`	显示登录页，标题正确
D-02	登录	使用有效账号登录	进入系统首页/驾驶舱，无接口跨域报错
D-03	静态资源	F12 网络面板查看 js/css	均返回 200，无 404
D-04	Luckysheet	打开含表格的页面	`/dist/plugins/`、`luckysheet.umd.js` 加载正常
D-05	主 API	登录、菜单加载	`/api/` 请求 200，后端 `16200` 可达
D-06	健康 API	进入健康评估页	`/healthApi/` 请求正常
D-07	异常检测	进入异常检测页	概览、热力图、列表数据正常
D-08	尾流分析	进入尾流页	图表与表格正常
D-09	驾驶舱地图	首页地图与瓦片	`/tiles/` 瓦片加载正常
D-10	路由刷新	在子页面按 F5 刷新	不出现 Nginx 404
D-11	EnOS 接口	驾驶舱相关数据	`/DatangEnosData/` 转发至 `10.172.12.212:8101` 正常

9. 常见问题

现象	可能原因	处理建议
页面空白	`dist-analyse` 目录不完整或 `index.html` 缺失	确认解压路径为 `/usr/local/nginx/html/dist-analyse/`，且含 `index.html`
接口 502/504	后端 `16200`/`16880` 未启动	检查后端进程与防火墙
接口 404	Nginx `proxy_pass` 路径错误或末尾斜杠不一致	对照本文第 6 节检查 `location` 与 `proxy_pass`
登录后立刻跳回登录页	Token 未写入或 `/api` 代理异常	查看浏览器 Network 中登录接口响应与后续请求 Header
地图不显示	`/data/roadmap` 无瓦片或 `/tiles` 未配置	检查 Nginx `location /tiles` 与磁盘目录
Luckysheet 样式错乱	`dist/dist/` 未随构建产物一并部署	确认 `dist-analyse/dist/plugins` 等目录存在
修改标题不生效	浏览器缓存	强刷或清缓存；确认改的是 `runtime-config.js`
健康/异常无数据	`16880` 服务或库无数据	确认日期、风场及 healthApi 后端状态

10. 回滚方案

# 假设备份目录为 dist-analyse.bak.202607011200
sudo rm -rf /usr/local/nginx/html/dist-analyse
sudo mv /usr/local/nginx/html/dist-analyse.bak.202607011200 \
        /usr/local/nginx/html/dist-analyse

回滚后访问 http://10.172.12.211:8899/ 验证即可，无需重启 Nginx（静态文件替换）。

11. 附录：完整 Nginx server 配置参考

以下为当前生产使用的 server 配置（摘自 nginx.conf），供运维对照：

server {
    listen       8899;
    server_name  energy-manage-analyse;

    location / {
        root   html/dist-analyse/;
        index  index.html;
        try_files $uri $uri/ /index.html =404;
    }

    location /api/ {
        proxy_pass http://10.172.12.211:16200/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /healthApi/ {
        add_header 'Access-Control-Allow-Origin' '*';
        proxy_pass http://10.172.12.211:16880/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /DatangEnosData/ {
        add_header 'Access-Control-Allow-Origin' '*';
        proxy_pass http://10.172.12.212:8101/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /tiles {
        alias /data/roadmap;
        autoindex on;
        expires 30d;
        access_log off;
        add_header Cache-Control "public";
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   html;
    }
}

12. 快速命令备忘

# 本地构建
npm install && npm run build:dt

# 服务器验配置
sudo /usr/local/nginx/sbin/nginx -t

# 重载 Nginx
sudo /usr/local/nginx/sbin/nginx -s reload

# 访问地址
http://10.172.12.211:8899/

文档结束

DEPLOY_FRONTEND.md 12 KB Cronologia Originale