XuJiacheng
e45d14b720
- 新增 HeartbeatBuffer 类，用于收集和去重 Kafka 心跳消息，并定期将数据刷新到数据库。 - 新增 HeartbeatDbManager 类，负责与 PostgreSQL 数据库的交互，支持批量 upsert 操作。 - 新增配置文件 config.js，支持从环境变量加载配置。 - 新增 Kafka 消费者模块，支持从 Kafka 中消费心跳消息。 - 新增 Redis 集成模块，支持将日志和心跳信息推送到 Redis。 - 新增心跳消息解析器，负责解析 Kafka 消息并提取心跳字段。 - 新增日志记录工具，支持不同级别的日志输出。 - 新增指标收集器，跟踪 Kafka 消息处理和数据库操作的指标。 - 新增单元测试，覆盖 HeartbeatBuffer 和 HeartbeatDbManager 的主要功能。 - 新增数据库表结构 SQL 文件，定义 room_status_moment_g5 表的结构。 - 配置 Vite 构建工具，支持 Node.js 环境的构建。
3.2 KiB
3.2 KiB
部署与运维规范 (Deployment & Operations Specification)
1. 环境配置
1.1 环境变量总表
# ========== PostgreSQL G5 连接 ==========
POSTGRES_HOST_G5=10.8.8.80
POSTGRES_PORT_G5=5434
POSTGRES_DATABASE_G5=dbv6
POSTGRES_USER_G5=<your_username>
POSTGRES_PASSWORD_G5=<your_password>
# ========== Kafka 消费 ==========
KAFKA_BROKERS=kafka.blv-oa.com:9092
KAFKA_TOPIC_HEARTBEAT=blwlog4Nodejs-oldrcu-heartbeat-topic
KAFKA_CONSUMER_INSTANCES=3 # 配置的消费者数（自动伸缩到分区数）
KAFKA_BATCH_SIZE=100000 # 单次拉取消息条数
KAFKA_FETCH_MIN_BYTES=65536 # 等待最少字节数
KAFKA_COMMIT_INTERVAL_MS=200 # 偏移量提交周期
# ========== Redis 连接 ==========
REDIS_HOST=10.8.8.109
REDIS_PORT=6379
REDIS_PASSWORD=<optional_password>
# ========== 缓冲与去重配置 ==========
HEARTBEAT_BUFFER_SIZE_MAX=5000 # 缓冲最大条数
HEARTBEAT_BUFFER_WINDOW_MS=5000 # 缓冲时间窗口（毫秒）
HEARTBEAT_WRITE_COOLDOWN_MS=30000 # 写入冷却期（毫秒）
# ========== 日志与调试 ==========
LOG_LEVEL=info # debug | info | warn | error
NODE_ENV=production # development | production
2. 启动流程
2.1 开发环境启动
# 1. 安装依赖
npm install
# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 填入真实的数据库、Kafka、Redis 地址
# 3. 运行开发服务
npm run dev
# 预期输出：
# ✓ Redis connected & heartbeat started
# ✓ PostgreSQL G5 connected
# ✓ Kafka consumer scaling resolved
# ✓ Started 6 Kafka consumer(s)
# ✓ bls-oldrcu-heartbeat-backend started
2.2 生产环境构建
# 1. 构建
npm run build
# 输出: dist/index.js (约 22KB)
# 2. 验证构建
node dist/index.js
# 3. 通过 Docker 部署（可选）
docker build -t bls-rcu-heartbeat:latest .
docker run -e POSTGRES_HOST_G5=... -e KAFKA_BROKERS=... bls-rcu-heartbeat:latest
3. 监控与告警
3.1 关键指标
消费健康度
指标: 消费速率 (msg/s)
目标: > 10,000 msg/s
警告阈值: < 5,000 msg/s
指标: 消息有效率 (%)
目标: > 95%
警告阈值: < 80%
正常值: 99.9%
缓冲健康度
指标: 缓冲大小 (条数)
目标: < 1,000（正常运行）
警告阈值: > 3,000（缓冲堆积）
指标: 冷却期覆盖率 (%)
说明: 被冷却期阻止的键百分比
目标: > 50%
4. 故障排查
4.1 消费速度慢
症状: 消费速率 < 5,000 msg/s
检查清单:
- Kafka 分区数与消费者数是否匹配？
- 网络连接是否正常？
- 数据库写入是否成为瓶颈？
- 是否有网络延迟或抖动？
4.2 消息验证失败率高
症状: invalidCount > 1% of totalMessages
检查清单:
- Kafka 消息结构是否改变？
- 验证规则是否过严？
- 数据源是否发送了垃圾数据？
4.3 数据库连接失败
症状: "PostgreSQL G5 connection failed" → exit(1)
检查清单:
- 数据库地址和端口是否正确？
- 网络连通性？
- 数据库用户名/密码是否正确？
- 数据库是否在线？
上次修订: 2026-03-11