Web_BLS_ProjectConsole/docs/deployment-guide-systemd.md

BLS Project Console 部署指南（Systemd版本）

一、部署架构说明

• 前端：Nginx作为Web服务器，提供静态文件服务
• 后端：Express应用，通过systemd服务管理
• 部署环境：飞牛OS NAS系统
• 容器化：Nginx运行在Docker容器中，后端运行在宿主机上

二、环境信息

• 前端访问地址: blv-rd.tech:20100
• 后端API地址: http://127.0.0.1:19910
• NAS项目文件目录: /vol1/1000/Docker/nginx/project/bls/bls_project_console
• NAS配置文件目录: /vol1/1000/Docker/nginx/conf.d
• Systemd服务目录: /etc/systemd/system/

三、部署前环境检查

1. 检查Node.js环境

# 检查Node.js版本（需要 >= 14.x）
node --version

# 检查npm版本
npm --version

# 如果未安装，请先安装Node.js

2. 检查Nginx容器状态

# 查看Nginx容器是否运行
docker ps | grep nginx

# 查看Nginx容器日志
docker logs nginx

# 检查Nginx容器端口映射
docker port nginx

3. 检查端口占用

# 检查后端端口19910是否被占用
netstat -tlnp | grep 19910

# 检查前端端口20100是否被占用
netstat -tlnp | grep 20100

4. 检查Redis服务

# 检查Redis是否运行
redis-cli ping

# 如果Redis未运行，请先启动Redis服务

5. 检查文件权限

# 检查项目目录权限
ls -la /vol1/1000/Docker/nginx/project/bls/bls_project_console

# 确保有读写权限，如果没有则修改
chmod -R 755 /vol1/1000/Docker/nginx/project/bls/bls_project_console

四、前端部署步骤

步骤1：本地编译前端

# 在本地项目根目录执行
npm install
npm run build

编译成功后，会在项目根目录生成 dist 文件夹。

步骤2：上传前端文件到NAS

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

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

上传方式：

• 使用SFTP工具（如FileZilla、WinSCP）
• 使用NAS提供的Web管理界面上传
• 使用rsync命令同步

注意:

• 上传的是 dist 文件夹内的文件，不是 dist 文件夹本身
• 确保上传后，NAS目录结构如下：

  /vol1/1000/Docker/nginx/project/bls/bls_project_console/
  ├── index.html
  ├── assets/
  │   ├── index-xxx.js
  │   └── index-xxx.css
  └── ...
  

步骤3：上传Nginx配置文件

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

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

步骤4：验证Nginx配置

在NAS上执行以下命令验证Nginx配置：

# 测试Nginx配置文件语法
docker exec nginx nginx -t

# 如果配置正确，会显示：
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

如果配置测试失败，检查配置文件语法错误：

# 查看Nginx错误日志
docker logs nginx --tail 50

# 进入容器查看详细错误
docker exec -it nginx bash
nginx -t

步骤5：重启Nginx容器

# 重启Nginx容器
docker restart nginx

# 等待容器启动
sleep 5

# 检查容器状态
docker ps | grep nginx

或者只重新加载配置（不重启容器）：

docker exec nginx nginx -s reload

步骤6：验证前端部署

在浏览器中访问：

http://blv-rd.tech:20100

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

如果无法访问，检查以下内容：

# 检查Nginx容器日志
docker logs nginx --tail 100

# 检查Nginx访问日志
docker exec nginx tail -f /var/log/nginx-custom/access.log

# 检查Nginx错误日志
docker exec nginx tail -f /var/log/nginx-custom/error.log

五、后端部署步骤

步骤1：准备后端文件（本地）

需要上传的后端文件包括：

• src/backend/app.js
• src/backend/server.js
• src/backend/routes/ （整个目录）
• src/backend/services/ （整个目录）
• package.json
• package-lock.json

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

将上述文件上传到NAS：

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

上传后的目录结构：

/vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/
├── app.js
├── server.js
├── package.json
├── package-lock.json
├── routes/
│   ├── commands.js
│   ├── logs.js
│   └── projects.js
└── services/
    ├── migrateHeartbeatData.js
    ├── redisClient.js
    └── redisKeys.js

步骤3：安装Node.js依赖

登录NAS，执行以下命令：

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

# 安装生产环境依赖
npm install --production

# 验证依赖安装成功
ls node_modules

如果安装失败，检查以下内容：

# 检查npm配置
npm config list

# 检查网络连接
ping registry.npmjs.org

# 清除npm缓存后重试
npm cache clean --force
npm install --production

步骤4：创建环境变量文件（可选）

如果需要配置环境变量，创建 .env 文件：

cd /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend
nano .env

添加以下内容：

NODE_ENV=production
PORT=19910
REDIS_HOST=localhost
REDIS_PORT=6379

保存并退出（Ctrl+O，Enter，Ctrl+X）。

步骤5：测试后端服务启动

在启动systemd服务之前，先手动测试后端服务是否能正常启动：

cd /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend

# 启动后端服务（前台运行）
node server.js

# 如果看到类似以下输出，说明启动成功：
# BLS Project Console backend server is running on port 19910

如果启动失败，查看错误信息并修复：

# 检查Redis连接
redis-cli ping

# 检查端口占用
netstat -tlnp | grep 19910

# 查看详细错误日志
node server.js 2>&1 | tee startup.log

测试成功后，按 Ctrl+C 停止服务。

步骤6：创建systemd服务配置文件

将项目中的 docs/bls-project-console.service 文件上传到NAS：

NAS路径: /etc/systemd/system/bls-project-console.service

或者直接在NAS上创建：

sudo nano /etc/systemd/system/bls-project-console.service

添加以下内容：

[Unit]
Description=BLS Project Console Backend Service
After=network.target redis.service

[Service]
Type=simple
User=root
WorkingDirectory=/vol1/1000/Docker/nginx/project/bls/bls_project_console/backend
ExecStart=/usr/bin/node /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/server.js
Restart=on-failure
RestartSec=10
StandardOutput=append:/vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/logs/systemd-out.log
StandardError=append:/vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/logs/systemd-err.log
Environment=NODE_ENV=production
Environment=PORT=19910

[Install]
WantedBy=multi-user.target

保存并退出（Ctrl+O，Enter，Ctrl+X）。

步骤7：创建日志目录

# 创建日志目录
mkdir -p /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/logs

# 设置日志目录权限
chmod 755 /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/logs

步骤8：重新加载systemd配置

# 重新加载systemd配置
sudo systemctl daemon-reload

# 启用服务开机自启
sudo systemctl enable bls-project-console.service

步骤9：启动systemd服务

# 启动服务
sudo systemctl start bls-project-console.service

# 查看服务状态
sudo systemctl status bls-project-console.service

如果服务启动成功，会看到类似以下输出：

● bls-project-console.service - BLS Project Console Backend Service
   Loaded: loaded (/etc/systemd/system/bls-project-console.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2026-01-16 10:00:00 CST; 5s ago
 Main PID: 12345 (node)
    Tasks: 6 (limit: 4915)
   Memory: 45.2M
   CGroup: /system.slice/bls-project-console.service
           └─12345 /usr/bin/node /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/server.js

如果服务启动失败，查看详细错误：

# 查看服务状态
sudo systemctl status bls-project-console.service -l

# 查看服务日志
sudo journalctl -u bls-project-console.service -n 50 --no-pager

# 查看应用日志
tail -f /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/logs/systemd-out.log
tail -f /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/logs/systemd-err.log

步骤10：验证后端服务

# 检查端口监听
netstat -tlnp | grep 19910

# 测试API接口
curl http://localhost:19910/api/projects

# 查看服务进程
ps aux | grep "node server.js"

在浏览器中访问：

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

应该能返回JSON数据。

六、Systemd服务管理命令

基本服务管理

# 启动服务
sudo systemctl start bls-project-console.service

# 停止服务
sudo systemctl stop bls-project-console.service

# 重启服务
sudo systemctl restart bls-project-console.service

# 重新加载配置
sudo systemctl reload bls-project-console.service

# 查看服务状态
sudo systemctl status bls-project-console.service

日志查看

# 查看实时日志
sudo journalctl -u bls-project-console.service -f

# 查看最近50行日志
sudo journalctl -u bls-project-console.service -n 50

# 查看今天的日志
sudo journalctl -u bls-project-console.service --since today

# 查看应用输出日志
tail -f /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/logs/systemd-out.log

# 查看应用错误日志
tail -f /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/logs/systemd-err.log

开机自启管理

# 启用开机自启
sudo systemctl enable bls-project-console.service

# 禁用开机自启
sudo systemctl disable bls-project-console.service

# 查看是否启用开机自启
sudo systemctl is-enabled bls-project-console.service

服务配置管理

# 重新加载systemd配置
sudo systemctl daemon-reload

# 重启服务（应用新配置）
sudo systemctl restart bls-project-console.service

# 查看服务配置文件
cat /etc/systemd/system/bls-project-console.service

七、后续更新流程

更新前端

# 1. 本地编译
npm run build

# 2. 上传新的 dist 文件夹内容到NAS
#    删除NAS上的旧文件，上传新文件

# 3. 重启Nginx容器
docker restart nginx

# 4. 刷新浏览器（Ctrl + F5）

更新后端

# 1. 上传修改后的后端文件到NAS

# 2. 如果有新依赖，执行：
cd /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend
npm install --production

# 3. 重启systemd服务
sudo systemctl restart bls-project-console.service

# 4. 查看服务状态
sudo systemctl status bls-project-console.service

# 5. 查看日志确认启动成功
sudo journalctl -u bls-project-console.service -n 50

更新配置文件

# 1. 更新Nginx配置
#    上传新的配置文件到 /vol1/1000/Docker/nginx/conf.d/bls_project_console.conf

# 2. 测试Nginx配置
docker exec nginx nginx -t

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

# 4. 更新systemd服务配置
#    上传新的服务文件到 /etc/systemd/system/bls-project-console.service

# 5. 重新加载systemd配置
sudo systemctl daemon-reload

# 6. 重启服务
sudo systemctl restart bls-project-console.service

八、常见问题排查

问题1：前端页面404

可能原因:

• 前端文件未正确上传
• Nginx配置中的 root 路径不正确
• Nginx容器内的 /var/www 目录映射不正确

解决方法:

# 1. 检查NAS上的文件是否存在
ls -la /vol1/1000/Docker/nginx/project/bls/bls_project_console

# 2. 检查Nginx容器内的文件
docker exec nginx ls -la /var/www/bls_project_console

# 3. 检查Nginx配置
docker exec nginx cat /etc/nginx/conf.d/bls_project_console.conf

# 4. 查看Nginx错误日志
docker logs nginx --tail 100

问题2：API请求失败

可能原因:

• 后端服务未启动
• 后端端口不是19910
• Redis连接失败
• 防火墙阻止了连接

解决方法:

# 1. 检查systemd服务状态
sudo systemctl status bls-project-console.service

# 2. 检查后端端口
netstat -tlnp | grep 19910

# 3. 查看服务日志
sudo journalctl -u bls-project-console.service -n 50

# 4. 检查Redis连接
redis-cli ping

# 5. 测试后端API
curl http://localhost:19910/api/projects

# 6. 重启服务
sudo systemctl restart bls-project-console.service

问题3：Systemd服务启动失败

可能原因:

• 配置文件语法错误
• 依赖服务未启动（如Redis）
• 文件权限不足
• 端口被占用

解决方法:

# 1. 查看详细错误信息
sudo systemctl status bls-project-console.service -l

# 2. 查看服务日志
sudo journalctl -u bls-project-console.service -n 100 --no-pager

# 3. 检查配置文件语法
cat /etc/systemd/system/bls-project-console.service

# 4. 检查文件权限
ls -la /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend

# 5. 检查端口占用
netstat -tlnp | grep 3001

# 6. 检查Redis服务
sudo systemctl status redis
redis-cli ping

# 7. 手动启动测试
cd /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend
node server.js

问题4：Nginx配置加载失败

可能原因:

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

解决方法:

# 1. 检查配置文件语法
docker exec nginx nginx -t

# 2. 检查端口占用
netstat -tlnp | grep 20100

# 3. 查看Nginx错误日志
docker logs nginx --tail 100

# 4. 检查配置文件内容
docker exec nginx cat /etc/nginx/conf.d/bls_project_console.conf

问题5：服务无法开机自启

可能原因:

• 服务未启用开机自启
• 依赖服务未启动
• 网络未就绪

解决方法:

# 1. 启用开机自启
sudo systemctl enable bls-project-console.service

# 2. 检查是否启用
sudo systemctl is-enabled bls-project-console.service

# 3. 检查依赖服务
sudo systemctl status redis

# 4. 查看启动失败日志
sudo journalctl -u bls-project-console.service --boot -n 100

九、目录结构总结

本地项目结构

Web_BLS_ProjectConsole/
├── dist/                    # 编译后的前端文件（需要上传）
├── src/
│   ├── backend/             # 后端源码（需要上传）
│   │   ├── app.js
│   │   ├── server.js
│   │   ├── routes/
│   │   └── services/
│   └── frontend/            # 前端源码
├── docs/
│   ├── nginx-deployment.conf        # Nginx配置文件（需要上传）
│   ├── bls-project-console.service  # Systemd服务配置（需要上传）
│   ├── deployment-guide.md           # 部署指南
│   └── ai-deployment-request-guide.md
├── 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
        ├── routes/
        ├── services/
        ├── package.json
        ├── package-lock.json
        ├── node_modules/       # npm install后生成
        └── logs/               # 日志目录
            ├── systemd-out.log  # systemd输出日志
            └── systemd-err.log  # systemd错误日志

/etc/systemd/system/
└── bls-project-console.service  # Systemd服务配置

十、监控和维护

日常监控

# 1. 检查服务状态
sudo systemctl status bls-project-console.service

# 2. 检查Nginx状态
docker ps | grep nginx

# 3. 查看服务日志
sudo journalctl -u bls-project-console.service --since today

# 4. 查看Nginx日志
docker logs nginx --since 1h

# 5. 检查磁盘空间
df -h /vol1/1000/Docker/nginx/project/bls/bls_project_console

# 6. 检查内存使用
free -h

日志轮转

创建日志轮转配置：

sudo nano /etc/logrotate.d/bls-project-console

添加以下内容：

/vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/logs/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0644 root root
    postrotate
        systemctl reload bls-project-console.service > /dev/null 2>&1 || true
    endscript
}

性能优化

# 1. 查看服务资源使用
systemctl show bls-project-console.service -p CPUUsage,MemoryCurrent

# 2. 查看进程资源使用
top -p $(pgrep -f "node server.js")

# 3. 调整systemd服务资源限制
sudo nano /etc/systemd/system/bls-project-console.service

添加资源限制：

[Service]
...
MemoryLimit=512M
CPUQuota=50%

重新加载并重启：

sudo systemctl daemon-reload
sudo systemctl restart bls-project-console.service

十一、备份和恢复

备份

# 1. 备份前端文件
tar -czf bls-project-console-frontend-$(date +%Y%m%d).tar.gz \
    /vol1/1000/Docker/nginx/project/bls/bls_project_console

# 2. 备份后端文件
tar -czf bls-project-console-backend-$(date +%Y%m%d).tar.gz \
    /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend

# 3. 备份配置文件
tar -czf bls-project-console-config-$(date +%Y%m%d).tar.gz \
    /vol1/1000/Docker/nginx/conf.d/bls_project_console.conf \
    /etc/systemd/system/bls-project-console.service

恢复

# 1. 恢复前端文件
tar -xzf bls-project-console-frontend-YYYYMMDD.tar.gz -C /

# 2. 恢复后端文件
tar -xzf bls-project-console-backend-YYYYMMDD.tar.gz -C /

# 3. 恢复配置文件
tar -xzf bls-project-console-config-YYYYMMDD.tar.gz -C /

# 4. 重新加载systemd配置
sudo systemctl daemon-reload

# 5. 重启服务
sudo systemctl restart bls-project-console.service
docker restart nginx

十二、安全建议

1. 文件权限

   # 设置适当的文件权限
   chmod 755 /vol1/1000/Docker/nginx/project/bls/bls_project_console
   chmod 644 /vol1/1000/Docker/nginx/project/bls/bls_project_console/backend/*.js
   

2. 防火墙配置

# 只允许必要的端口
sudo ufw allow 20100/tcp
sudo ufw allow 19910/tcp
sudo ufw enable

3. 定期更新

   # 定期更新Node.js和npm
   npm install -g npm@latest
   

4. 日志监控

   • 定期检查日志文件大小
   • 设置日志轮转
   • 监控异常错误

5. 备份策略

   • 定期备份配置文件
   • 定期备份重要数据
   • 测试恢复流程