feat: 添加部署脚本和文档并优化Kafka消费者配置

- 添加部署相关脚本(deploy.bat/update.bat/package.bat)和文档(deployment.md/package-guide.md) - 新增PM2配置文件(ecosystem.config.js/ecosystem.config.cjs) - 优化Kafka消费者配置支持动态fromOffset - 添加环境检查脚本(check-env.js) - 更新.gitignore添加release目录 - 补充.env.example配置文件
2026-01-16 16:19:31 +08:00
parent 455185ac5d
commit 625cb9eea4
13 changed files with 1028 additions and 3 deletions
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -0,0 +1,292 @@
+# BLS心跳接收端发布流程
+
+## 环境要求
+
+- Windows Server系统
+- Node.js 环境（已安装）
+- PM2 进程管理器（已安装）
+- PostgreSQL 数据库
+- Kafka 消息队列
+- Redis（可选）
+
+## 发布流程
+
+### 1. 准备发布包
+
+在开发机器上执行以下命令：
+
+```bash
+# 安装依赖
+npm install
+
+# 构建项目
+npm run build
+
+# 创建发布包（包含必要的文件）
+# 方法1：手动复制文件
+# 复制以下文件到发布目录：
+# - dist/ (构建后的文件)
+# - package.json
+# - package-lock.json
+# - src/config/config.example.js
+# - scripts/db/ (数据库脚本)
+
+# 方法2：使用压缩包
+# 创建包含上述文件的压缩包
+```
+
+### 2. 上传到目标服务器
+
+将发布包上传到目标服务器的指定目录，例如：`C:\BLS_Heartbeat_Server`
+
+### 3. 在目标服务器上部署
+
+```bash
+# 进入项目目录
+cd C:\BLS_Heartbeat_Server
+
+# 安装生产依赖
+npm install --production
+
+# 创建环境变量文件
+# 复制配置示例并修改
+copy src\config\config.example.js src\config\config.js
+
+# 或者创建 .env 文件（推荐）
+# 复制 .env.example 并修改为 .env
+copy .env.example .env
+
+# 编辑配置文件，设置实际的数据库、Kafka、Redis连接信息
+notepad .env
+```
+
+### 4. 配置环境变量
+
+编辑 `.env` 文件，设置以下关键配置：
+
+```env
+# 应用配置
+NODE_ENV=production
+PORT=3000
+
+# Kafka配置
+KAFKA_BROKERS=localhost:9092
+KAFKA_TOPIC=blwlog4Nodejs-rcu-heartbeat-topic
+KAFKA_GROUP_ID=bls-heartbeat-consumer
+KAFKA_CONSUMER_INSTANCES=6
+
+# PostgreSQL配置
+POSTGRES_HOST=127.0.0.1
+POSTGRES_PORT=5432
+POSTGRES_DATABASE=log_platform
+POSTGRES_USER=log_admin
+POSTGRES_PASSWORD=your_password
+
+# Redis配置（可选）
+REDIS_ENABLED=true
+REDIS_HOST=10.8.8.109
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=15
+
+# 日志配置
+LOG_LEVEL=info
+LOG_FORMAT=json
+```
+
+### 5. 初始化数据库
+
+```bash
+# 运行数据库初始化脚本
+npm run db:apply
+```
+
+### 6. 使用PM2启动服务
+
+```bash
+# 使用PM2启动服务
+pm2 start ecosystem.config.js
+
+# 查看服务状态
+pm2 status
+
+# 查看日志
+pm2 logs web-bls-heartbeat-server
+
+# 查看详细信息
+pm2 show web-bls-heartbeat-server
+```
+
+### 7. 设置PM2开机自启
+
+```bash
+# 保存当前PM2进程列表
+pm2 save
+
+# 设置开机自启（Windows需要管理员权限）
+pm2 startup
+```
+
+## PM2配置说明
+
+项目提供了 `ecosystem.config.js` 配置文件，包含以下配置：
+
+- 应用名称：`web-bls-heartbeat-server`
+- 运行模式：`cluster`（集群模式）
+- 实例数量：根据CPU核心数自动设置
+- 日志文件：`logs/` 目录下
+- 环境变量：从 `.env` 文件加载
+
+## 监控和维护
+
+### 查看服务状态
+
+```bash
+# 查看所有服务状态
+pm2 status
+
+# 查看特定服务状态
+pm2 show web-bls-heartbeat-server
+
+# 实时监控
+pm2 monit
+```
+
+### 日志管理
+
+```bash
+# 查看实时日志
+pm2 logs web-bls-heartbeat-server
+
+# 查看错误日志
+pm2 logs web-bls-heartbeat-server --err
+
+# 清空日志
+pm2 flush
+
+# 日志轮转（需要安装pm2-logrotate）
+pm2 install pm2-logrotate
+```
+
+### 服务重启
+
+```bash
+# 重启服务
+pm2 restart web-bls-heartbeat-server
+
+# 优雅重启（集群模式）
+pm2 reload web-bls-heartbeat-server
+
+# 停止服务
+pm2 stop web-bLS-heartbeat-server
+
+# 删除服务
+pm2 delete web-bls-heartbeat-server
+```
+
+### 更新部署
+
+```bash
+# 停止服务
+pm2 stop web-bls-heartbeat-server
+
+# 备份当前版本
+xcopy /E /I /Y C:\BLS_Heartbeat_Server C:\BLS_Heartbeat_Server_backup
+
+# 上传新版本文件
+
+# 安装依赖（如果有更新）
+npm install --production
+
+# 重启服务
+pm2 start ecosystem.config.js
+
+# 验证服务状态
+pm2 status
+pm2 logs web-bls-heartbeat-server
+```
+
+## 故障排查
+
+### 服务无法启动
+
+1. 检查Node.js版本：`node --version`
+2. 检查PM2状态：`pm2 list`
+3. 查看错误日志：`pm2 logs web-bls-heartbeat-server --err`
+4. 检查配置文件：确认 `.env` 文件配置正确
+5. 检查网络连接：确认Kafka、PostgreSQL、Redis服务可访问
+
+### 数据库连接失败
+
+1. 检查PostgreSQL服务状态
+2. 验证数据库连接信息
+3. 检查防火墙设置
+4. 确认数据库用户权限
+
+### Kafka连接失败
+
+1. 检查Kafka服务状态
+2. 验证Kafka地址和端口
+3. 检查主题是否存在
+4. 确认消费者组配置
+
+### Redis连接失败
+
+1. 检查Redis服务状态
+2. 验证Redis连接信息
+3. 如果不需要Redis，设置 `REDIS_ENABLED=false`
+
+## 性能优化
+
+### 调整消费者实例数
+
+在 `.env` 文件中修改：
+
+```env
+KAFKA_CONSUMER_INSTANCES=8
+```
+
+### 调整批量处理参数
+
+```env
+PROCESSOR_BATCH_SIZE=200
+PROCESSOR_BATCH_TIMEOUT=3000
+```
+
+### 调整数据库连接池
+
+```env
+DB_MAX_CONNECTIONS=10
+DB_IDLE_TIMEOUT_MS=30000
+```
+
+## 安全建议
+
+1. 不要在代码中硬编码密码，使用环境变量
+2. 限制数据库和Redis的访问IP
+3. 定期更新依赖包：`npm audit fix`
+4. 配置防火墙规则，限制不必要的端口访问
+5. 定期备份配置文件和数据库
+
+## 备份策略
+
+### 配置文件备份
+
+```bash
+# 备份环境配置
+copy .env .env.backup
+
+# 备份PM2配置
+pm2 save
+```
+
+### 数据库备份
+
+```bash
+# 使用pg_dump备份数据库
+pg_dump -h localhost -U log_admin -d log_platform > backup.sql
+```
+
+## 联系支持
+
+如有问题，请查看项目文档或联系技术支持团队。
--- a/docs/package-guide.md
+++ b/docs/package-guide.md
@@ -0,0 +1,157 @@
+# 发布包使用指南
+
+## 发布包位置
+
+发布包已生成在项目根目录下的 `release` 文件夹中。
+
+## 发布包内容
+
+```
+release/
+├── dist/                           # 构建后的应用程序文件
+│   └── index.es.js                # 主程序文件
+├── scripts/                        # 部署脚本
+│   ├── deploy.bat                 # 首次部署脚本
+│   └── update.bat                 # 更新部署脚本
+├── src/
+│   └── config/
+│       └── config.example.js      # 配置文件示例
+├── .env.example                    # 环境变量配置示例
+├── ecosystem.config.js             # PM2进程管理配置
+├── package.json                    # 项目依赖配置
+├── package-lock.json               # 依赖锁定文件
+└── README.txt                      # 快速使用说明
+```
+
+## 部署步骤
+
+### 1. 复制发布包
+
+将整个 `release` 文件夹复制到目标服务器的指定目录，例如：
+- `C:\BLS_Heartbeat_Server`
+
+### 2. 在目标服务器上部署
+
+打开命令提示符（CMD）或PowerShell，进入项目目录：
+
+```cmd
+cd C:\BLS_Heartbeat_Server
+```
+
+### 3. 运行部署脚本
+
+```cmd
+scripts\deploy.bat
+```
+
+部署脚本会自动完成以下操作：
+- 检查Node.js和PM2环境
+- 安装项目依赖
+- 创建日志目录
+- 初始化数据库
+- 启动服务
+
+### 4. 配置环境变量
+
+首次运行后，需要编辑 `.env` 文件，设置实际的配置参数：
+
+```cmd
+notepad .env
+```
+
+关键配置项：
+- `KAFKA_BROKERS`: Kafka服务器地址
+- `KAFKA_TOPIC`: Kafka主题名称
+- `POSTGRES_HOST`: PostgreSQL服务器地址
+- `POSTGRES_DATABASE`: 数据库名称
+- `POSTGRES_USER`: 数据库用户名
+- `POSTGRES_PASSWORD`: 数据库密码
+- `REDIS_HOST`: Redis服务器地址（可选）
+
+### 5. 重启服务
+
+配置完成后，重启服务使配置生效：
+
+```cmd
+pm2 restart web-bls-heartbeat-server
+```
+
+## 更新部署
+
+当有新版本时，可以运行更新脚本：
+
+```cmd
+scripts\update.bat
+```
+
+更新脚本会自动完成以下操作：
+- 停止当前服务
+- 备份当前版本
+- 更新依赖
+- 更新数据库
+- 重启服务
+
+## 常用PM2命令
+
+```cmd
+# 查看服务状态
+pm2 status
+
+# 查看实时日志
+pm2 logs web-bls-heartbeat-server
+
+# 查看错误日志
+pm2 logs web-bls-heartbeat-server --err
+
+# 重启服务
+pm2 restart web-bls-heartbeat-server
+
+# 停止服务
+pm2 stop web-bls-heartbeat-server
+
+# 启动服务
+pm2 start ecosystem.config.js
+
+# 实时监控
+pm2 monit
+
+# 查看服务详情
+pm2 show web-bls-heartbeat-server
+
+# 清空日志
+pm2 flush
+```
+
+## 故障排查
+
+### 服务无法启动
+
+1. 检查Node.js版本：`node --version`
+2. 检查PM2状态：`pm2 list`
+3. 查看错误日志：`pm2 logs web-bls-heartbeat-server --err`
+4. 检查配置文件：确认 `.env` 文件配置正确
+
+### 数据库连接失败
+
+1. 检查PostgreSQL服务是否运行
+2. 验证数据库连接信息
+3. 检查防火墙设置
+4. 确认数据库用户权限
+
+### Kafka连接失败
+
+1. 检查Kafka服务是否运行
+2. 验证Kafka地址和端口
+3. 检查主题是否存在
+
+## 注意事项
+
+1. 首次部署需要配置 `.env` 文件
+2. 确保目标服务器已安装Node.js和PM2
+3. 确保PostgreSQL、Kafka、Redis服务可访问
+4. 建议定期备份数据库和配置文件
+5. 生产环境建议设置PM2开机自启
+
+## 技术支持
+
+如有问题，请参考详细部署文档：`docs/deployment.md`