# 部署与运维规范 (Deployment & Operations Specification)

## 1. 环境配置

### 1.1 环境变量总表

```bash
# ========== 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 开发环境启动

```bash
# 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 生产环境构建

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

**检查清单**:
1. Kafka 分区数与消费者数是否匹配？
2. 网络连接是否正常？
3. 数据库写入是否成为瓶颈？
4. 是否有网络延迟或抖动？

### 4.2 消息验证失败率高

**症状**: invalidCount > 1% of totalMessages

**检查清单**:
1. Kafka 消息结构是否改变？
2. 验证规则是否过严？
3. 数据源是否发送了垃圾数据？

### 4.3 数据库连接失败

**症状**: "PostgreSQL G5 connection failed" → exit(1)

**检查清单**:
1. 数据库地址和端口是否正确？
2. 网络连通性？
3. 数据库用户名/密码是否正确？
4. 数据库是否在线？

---

**上次修订**: 2026-03-11