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

| 项目 | 说明 |
|------|------|
| 文档版本 | 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 代理，生产可不依赖）：

```bash
# 页面标题（也可部署后改 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. 本地构建步骤

在项目根目录执行：

```bash
# 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 中已配置：

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

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

### 5.2 推荐发布流程

```bash
# 在本地项目根目录，将 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
```

在服务器上执行：

```bash
# 备份旧版本（建议保留最近 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` 增量同步：

```bash
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` 块摘要如下：

| 监听 | `8899` |
| server_name | `energy-manage-analyse` |
| 静态根目录 | `html/dist-analyse/` |

### 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

```bash
# 检查配置语法
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 修改系统标题

编辑服务器上的文件：

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

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

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

默认 `dist/config/config.js`：

```javascript
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. 回滚方案

```bash
# 假设备份目录为 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`），供运维对照：

```nginx
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. 快速命令备忘

```bash
# 本地构建
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/
```

---

*文档结束*