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环境

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

# 检查npm版本
npm --version

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

### 2. 检查Nginx容器状态

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

# 查看Nginx容器日志
docker logs nginx

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

### 3. 检查端口占用

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

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

### 4. 检查Redis服务

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

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

### 5. 检查文件权限

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

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

## 四、前端部署步骤

### 步骤1：本地编译前端

```bash
# 在本地项目根目录执行
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配置：

```bash
# 测试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
```

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

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

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

### 步骤5：重启Nginx容器

```bash
# 重启Nginx容器
docker restart nginx

# 等待容器启动
sleep 5

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

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

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

### 步骤6：验证前端部署

在浏览器中访问：

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

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

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

```bash
# 检查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，执行以下命令：

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

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

# 验证依赖安装成功
ls node_modules
```

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

```bash
# 检查npm配置
npm config list

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

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

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

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

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

添加以下内容：

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

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

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

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

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

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

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

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

```bash
# 检查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上创建：

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

添加以下内容：

```ini
[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：创建日志目录

```bash
# 创建日志目录
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配置

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

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

### 步骤9：启动systemd服务

```bash
# 启动服务
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
```

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

```bash
# 查看服务状态
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：验证后端服务

```bash
# 检查端口监听
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服务管理命令

### 基本服务管理

```bash
# 启动服务
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
```

### 日志查看

```bash
# 查看实时日志
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
```

### 开机自启管理

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

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

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

### 服务配置管理

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

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

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

## 七、后续更新流程

### 更新前端

```bash
# 1. 本地编译
npm run build

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

# 3. 重启Nginx容器
docker restart nginx

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

### 更新后端

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

### 更新配置文件

```bash
# 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` 目录映射不正确

**解决方法**:

```bash
# 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连接失败
- 防火墙阻止了连接

**解决方法**:

```bash
# 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）
- 文件权限不足
- 端口被占用

**解决方法**:

```bash
# 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已被占用
- 配置文件路径错误

**解决方法**:

```bash
# 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：服务无法开机自启

**可能原因**:

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

**解决方法**:

```bash
# 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服务配置
```

## 十、监控和维护

### 日常监控

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

### 日志轮转

创建日志轮转配置：

```bash
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
}
```

### 性能优化

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

添加资源限制：

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

重新加载并重启：

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

## 十一、备份和恢复

### 备份

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

### 恢复

```bash
# 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. **文件权限**

   ```bash
   # 设置适当的文件权限
   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. **防火墙配置**

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

3. **定期更新**

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

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

5. **备份策略**
   - 定期备份配置文件
   - 定期备份重要数据
   - 测试恢复流程