Web_BLS_ProjectConsole/docs/deployment-guide.md

BLS Project Console 发布流程

一、环境信息

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

二、本地编译步骤

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

npm install

2. 编译前端

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，执行以下命令：

# 进入后端目录
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会自动管理进程、自动重启、日志记录等：

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

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

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

PM2常用命令：

# 查看服务状态
pm2 status

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

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

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

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

注意:

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

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

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

docker restart nginx

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

docker exec nginx nginx -s reload

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

检查Nginx配置是否正确：

docker exec nginx nginx -t

四、验证部署

1. 检查前端访问

在浏览器中访问：

http://blv-rd.tech:20100

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

2. 检查API接口

在浏览器中访问：

http://blv-rd.tech:20100/api/projects

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

3. 检查Nginx日志

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

docker logs nginx

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

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请求失败

可能原因:

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

解决方法:

1. 检查PM2服务状态：pm2 status
2. 检查后端端口：netstat -tlnp | grep 19910
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配置加载失败

可能原因:

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

解决方法:

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

六、后续更新流程

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

1. 本地编译:

   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）:

   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=19910
• 内存限制：1GB（超过自动重启）
• 日志文件：./logs/pm2-error.log 和 ./logs/pm2-out.log

PM2日志查看

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

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

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

# 清空日志
pm2 flush

PM2监控

# 查看实时监控界面
pm2 monit

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

九、注意事项

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