Web_BLS_ProjectConsole/docs/deployment-guide.md

# BLS Project Console 发布流程

## 一、环境信息

- **前端访问地址**: blv-rd.tech:19199
- **NAS项目文件目录**: `/vol1/1000/Docker/nginx/project/bls/bls_project_console`
- **NAS配置文件目录**: `/vol1/1000/Docker/nginx/conf.d`
- **项目类型**: Vue3前端 + Express后端
- **后端端口**: 19070

## 二、本地编译步骤

### 1. 安装依赖（首次执行）

```bash
npm install
```

### 2. 编译前端

```bash
npm run build
```

编译成功后，会在项目根目录生成 `dist` 文件夹，里面包含所有前端静态文件。

### 3. 准备后端文件

后端文件位于 `src/backend` 目录，需要上传的文件包括：

- `ecosystem.config.js` （PM2配置文件）
- `src/backend/app.js`
- `src/backend/server.js`
- `src/backend/routes/` （整个目录）
- `src/backend/services/` （整个目录）
- `package.json`
- `package-lock.json`

## 三、NAS端部署步骤

### 步骤1：上传前端文件到NAS

将本地编译生成的 `dist` 文件夹内的所有文件上传到NAS：

```
NAS路径: /vol1/1000/Docker/nginx/project/bls/bls_project_console
```

**注意**:

- 上传的是 `dist` 文件夹内的文件，不是 `dist` 文件夹本身
- 确保上传后，NAS目录结构如下：
  ```
  /vol1/1000/Docker/nginx/project/bls/bls_project_console/
  ├── index.html
  ├── assets/
  │   ├── index-xxx.js
  │   └── index-xxx.css
  └── ...
  ```

### 步骤2：上传后端文件到NAS

将后端文件上传到NAS的同一目录（或单独的目录）：

```
NAS路径: /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/
```

上传以下文件：

- `ecosystem.config.js` （PM2配置文件）
- `package.json`
- `package-lock.json`
- `src/backend/app.js` → `backend/app.js`
- `src/backend/server.js` → `backend/server.js`
- `src/backend/routes/` → `backend/routes/`
- `src/backend/services/` → `backend/services/`

### 步骤3：上传Nginx配置文件

将项目中的 `docs/nginx-deployment.conf` 文件上传到NAS：

```
NAS路径: /vol1/1000/Docker/nginx/conf.d/bls_project_console.conf
```

### 步骤4：安装后端依赖和PM2（首次部署时执行）

登录到NAS，执行以下命令：

```bash
# 进入后端目录
cd /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend

# 安装Node.js依赖
npm install --production

# 全局安装PM2（如果尚未安装）
npm install -g pm2
```

### 步骤5：启动后端服务（使用PM2）

使用PM2启动后端服务，PM2会自动管理进程、自动重启、日志记录等：

```bash
# 进入后端目录
cd /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend

# 使用PM2启动服务（根据配置文件）
pm2 start ecosystem.config.js

# 设置PM2开机自启
pm2 startup
pm2 save
```

**PM2常用命令**：

```bash
# 查看服务状态
pm2 status

# 查看日志
pm2 logs bls-project-console

# 重启服务
pm2 restart bls-project-console

# 停止服务
pm2 stop bls-project-console

# 删除服务
pm2 delete bls-project-console
```

**注意**:

- 后端服务会在宿主机上运行，端口为19070
- 确保Redis服务已启动并可访问
- PM2会自动管理进程崩溃重启

### 步骤6：重启Nginx容器（在NAS上执行）

重启Nginx容器以加载新的配置：

```bash
docker restart nginx
```

或者进入Nginx容器重新加载配置：

```bash
docker exec nginx nginx -s reload
```

### 步骤7：检查Nginx配置（可选）

检查Nginx配置是否正确：

```bash
docker exec nginx nginx -t
```

## 四、验证部署

### 1. 检查前端访问

在浏览器中访问：

```
http://blv-rd.tech:19199
```

应该能看到项目的前端页面。

### 2. 检查API接口

在浏览器中访问：

```
http://blv-rd.tech:19199/api/projects
```

应该能返回JSON数据（如果后端正常运行）。

### 3. 检查Nginx日志

查看Nginx访问日志和错误日志：

```bash
docker logs nginx
```

或查看容器内的日志文件：

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

## 五、常见问题排查

### 问题1：前端页面404

**可能原因**:

- 前端文件未正确上传到 `/vol1/1000/Docker/nginx/project/bls/bls_project_console`
- Nginx配置中的 `root` 路径不正确
- Nginx容器内的 `/var/www` 目录映射不正确

**解决方法**:

1. 检查NAS上的文件是否存在
2. 检查Nginx配置文件中的 `root` 路径是否正确
3. 检查Docker容器的挂载配置

### 问题2：API请求失败

**可能原因**:

- 后端服务未启动
- 后端端口不是19070
- `host.docker.internal` 无法解析
- 防火墙阻止了连接

**解决方法**:

1. 检查PM2服务状态：`pm2 status`
2. 检查后端端口：`netstat -tlnp | grep 19070`
3. 查看PM2日志：`pm2 logs bls-project-console`
4. 在Nginx容器内测试连接：`docker exec nginx ping host.docker.internal`
5. 检查防火墙规则
6. 重启PM2服务：`pm2 restart bls-project-console`

### 问题3：Nginx配置加载失败

**可能原因**:

- 配置文件语法错误
- 端口19199已被占用
- 配置文件路径错误

**解决方法**:

1. 检查配置文件语法：`docker exec nginx nginx -t`
2. 检查端口占用：`netstat -tlnp | grep 19199`
3. 查看Nginx错误日志：`docker logs nginx`

## 六、后续更新流程

当需要更新项目时，只需执行以下步骤：

1. **本地编译**:

   ```bash
   npm run build
   ```

2. **上传前端文件**:
   - 删除NAS上的旧文件
   - 上传新的 `dist` 文件夹内容到 `/vol1/1000/Docker/nginx/project/bls/bls_project_console`

3. **上传后端文件**（如果有修改）:
   - 上传修改后的后端文件到 `/vol1/1000/Docker/nginx/project/bls/bls_project_console/backend`
   - 如果有新的依赖，需要重新运行 `npm install --production`

4. **重启后端服务**（使用PM2）:

   ```bash
   cd /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend
   pm2 restart bls-project-console
   ```

5. **刷新浏览器缓存**:
   - 在浏览器中按 `Ctrl + F5` 强制刷新

## 七、目录结构总结

### 本地项目结构

```
Web_BLS_ProjectConsole/
├── dist/                    # 编译后的前端文件（需要上传）
├── src/
│   ├── backend/             # 后端源码（需要上传）
│   │   ├── app.js
│   │   ├── server.js
│   │   ├── routes/
│   │   └── services/
│   └── frontend/            # 前端源码
├── docs/
│   └── nginx-deployment.conf # Nginx配置文件（需要上传）
├── ecosystem.config.js      # PM2配置文件（需要上传）
├── package.json             # 依赖配置（需要上传）
└── package-lock.json        # 依赖锁定文件（需要上传）
```

### NAS部署结构

```
/vol1/1000/Docker/nginx/
├── conf.d/
│   ├── weknora.conf
│   └── bls_project_console.conf  # 上传的Nginx配置
└── project/bls/bls_project_console/
    ├── index.html              # 前端入口文件
    ├── assets/                 # 前端静态资源
    │   ├── index-xxx.js
    │   └── index-xxx.css
    └── backend/                # 后端文件
        ├── app.js
        ├── server.js
        ├── ecosystem.config.js # PM2配置文件
        ├── routes/
        ├── services/
        ├── package.json
        ├── package-lock.json
        ├── node_modules/       # npm install后生成
        └── logs/               # PM2日志目录（自动生成）
            ├── pm2-error.log   # 错误日志
            └── pm2-out.log     # 输出日志
```

## 八、PM2进程管理说明

### PM2的优势

使用PM2管理Node.js进程有以下优势：

- **自动重启**: 进程崩溃时自动重启
- **开机自启**: 配置后系统重启自动启动服务
- **日志管理**: 自动记录和管理日志文件
- **进程监控**: 实时查看进程状态和资源使用情况
- **集群模式**: 支持多进程负载均衡（本项目配置为单进程）

### PM2配置文件说明

`ecosystem.config.js` 配置文件已包含以下设置：

- 应用名称：`bls-project-console`
- 工作目录：`/vol1/1000/Docker/nginx/project/bls/bls_project_console/backend`
- 启动脚本：`./server.js`
- 环境变量：`NODE_ENV=production`, `PORT=19070`
- 内存限制：1GB（超过自动重启）
- 日志文件：`./logs/pm2-error.log` 和 `./logs/pm2-out.log`

### PM2日志查看

```bash
# 实时查看日志
pm2 logs bls-project-console

# 查看错误日志
pm2 logs bls-project-console --err

# 查看输出日志
pm2 logs bls-project-console --out

# 清空日志
pm2 flush
```

### PM2监控

```bash
# 查看实时监控界面
pm2 monit

# 查看详细信息
pm2 show bls-project-console
```

## 九、注意事项

1. **端口映射**: 确保Nginx容器的19199端口已映射到宿主机的19199端口
2. **host.docker.internal**: 在Linux上，需要在Docker Compose中添加 `extra_hosts` 配置
3. **文件权限**: 确保上传的文件有正确的读写权限
4. **Redis连接**: 确保后端能连接到Redis服务
5. **日志监控**: 定期检查Nginx和后端日志，及时发现和解决问题