Web_BLS_ProjectConsole/docs/deployment-guide-windows.md

# Windows 部署指南

## 环境要求

- Windows Server
- Node.js (已安装)
- PM2 (已安装)
- Nginx (已安装)
- Redis 服务

## 部署步骤

### 1. 准备文件

将以下文件复制到测试服务器：

#### 必需文件清单

```
项目根目录/
├── src/backend/           # 后端源码
│   ├── server.js
│   ├── app.js
│   ├── routes/
│   └── services/
├── dist/                  # 前端构建产物（已构建）
│   ├── index.html
│   └── assets/
├── package.json
├── package-lock.json
└── node_modules/          # 依赖包（需要在服务器上安装）
```

#### 配置文件

从 `docs/` 目录复制以下配置文件：

```
docs/
├── ecosystem.config.windows.js    # PM2 配置文件
├── nginx.conf.windows             # Nginx 配置文件
└── .env.example                   # 环境变量示例
```

### 2. 服务器目录结构

在测试服务器上创建以下目录结构：

```
E:/projects/bls_project_console/
├── src/backend/
├── dist/
├── logs/
├── node_modules/
├── package.json
├── package-lock.json
└── .env
```

### 3. 安装依赖

在服务器项目目录下运行：

```bash
cd E:/projects/bls_project_console
npm install --production
```

### 4. 配置环境变量

复制 `.env.example` 为 `.env`，并根据实际情况修改配置：

```bash
# Redis connection
REDIS_HOST=10.8.8.109          # 修改为实际的Redis服务器地址
REDIS_PORT=6379
REDIS_PASSWORD=               # 如果有密码则填写
REDIS_DB=15
REDIS_CONNECT_TIMEOUT_MS=2000

# Command control (HTTP)
COMMAND_API_TIMEOUT_MS=5000

# Heartbeat liveness
HEARTBEAT_OFFLINE_THRESHOLD_MS=10000

# Node environment
NODE_ENV=production
```

### 5. 配置 PM2

修改 `ecosystem.config.windows.js` 中的路径配置：

```javascript
module.exports = {
  apps: [
    {
      name: 'bls-project-console',
      script: './src/backend/server.js',
      cwd: 'E:/projects/bls_project_console', // 修改为实际部署路径
      instances: 1,
      autorestart: true,
      watch: false,
      max_memory_restart: '1G',
      env: {
        NODE_ENV: 'production',
        PORT: 19910,
      },
      error_file: './logs/pm2-error.log',
      out_file: './logs/pm2-out.log',
      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
      merge_logs: true,
    },
  ],
};
```

### 6. 启动后端服务

使用 PM2 启动服务：

```bash
cd E:/projects/bls_project_console
pm2 start ecosystem.config.windows.js
pm2 save
pm2 startup
```

查看服务状态：

```bash
pm2 status
pm2 logs bls-project-console
```

### 7. 配置 Nginx

#### 7.1 部署前端静态文件

将 `dist/` 目录内容复制到 Nginx 静态文件目录：

```bash
# 创建静态文件目录
mkdir C:/nginx/sites/bls_project_console

# 复制前端文件
xcopy E:/projects/bls_project_console\dist\* C:/nginx/sites/bls_project_console /E /I /Y
```

#### 7.2 配置 Nginx

将 `nginx.conf.windows` 的内容添加到 Nginx 主配置文件中，或作为独立的站点配置文件：

```bash
# 复制配置文件到 Nginx 配置目录
copy docs\nginx.conf.windows C:/nginx/conf.d/bls_project_console.conf
```

#### 7.3 修改配置文件中的路径

根据实际部署路径修改 `nginx.conf.windows` 中的路径：

```nginx
root C:/nginx/sites/bls_project_console;  # 修改为实际的静态文件路径
```

#### 7.4 测试并重启 Nginx

```bash
# 测试配置
nginx -t

# 重启 Nginx
nginx -s reload
```

### 8. 验证部署

#### 8.1 检查后端服务

```bash
# 检查 PM2 进程状态
pm2 status

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

# 测试健康检查接口
curl http://localhost:19910/api/health
```

#### 8.2 检查前端访问

在浏览器中访问：

- `http://localhost/` 或配置的域名

#### 8.3 检查 API 代理

```bash
curl http://localhost/api/health
```

## 常用命令

### PM2 命令

```bash
# 启动服务
pm2 start ecosystem.config.windows.js

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

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

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

# 查看状态
pm2 status

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

# 保存当前进程列表
pm2 save
```

### Nginx 命令

```bash
# 测试配置
nginx -t

# 重启 Nginx
nginx -s reload

# 停止 Nginx
nginx -s stop

# 查看 Nginx 版本
nginx -v
```

## 故障排查

### 后端无法启动

1. 检查端口是否被占用：

   ```bash
   netstat -ano | findstr :19910
   ```

2. 检查 Redis 连接：

   ```bash
   # 查看 .env 文件中的 Redis 配置
   # 确保可以连接到 Redis 服务器
   ```

3. 查看日志：
   ```bash
   pm2 logs bls-project-console
   ```

### 前端无法访问

1. 检查 Nginx 配置：

   ```bash
   nginx -t
   ```

2. 检查静态文件目录：

   ```bash
   dir C:/nginx/sites/bls_project_console
   ```

3. 查看 Nginx 错误日志：
   ```bash
   type C:/nginx/logs/bls_project_console_error.log
   ```

### API 请求失败

1. 检查后端服务是否运行：

   ```bash
   pm2 status
   ```

2. 检查 Nginx 代理配置：
   ```bash
   # 确保 proxy_pass 指向正确的后端地址
   curl http://localhost:19910/api/health
   ```

## 端口说明

- **19910**: 后端 API 服务端口
- **80**: Nginx HTTP 服务端口

## 注意事项

1. 确保 Redis 服务正常运行并可访问
2. 确保 Windows 防火墙允许相关端口访问
3. 生产环境建议使用 HTTPS
4. 定期备份 `.env` 配置文件
5. 监控 PM2 日志和 Nginx 日志