ai-security-xdr/haobang-security-dm/upgrade-doc/v3/config/01-new-environment-variables.md

# v3 新增变量配置

应用侧只需要修改两个 Docker Compose 文件。变量放到对应服务的 `environment:` 下，不要修改 JAR 中的
`application.properties`；Kafka Broker 参数单独按第 4 节核对。

## 1. syslog-serve

配置文件：

```text
syslog-serve/docker-compose/docker-compose-serve-prod.yaml
```

在 `services.syslog-serve.environment` 中增加：

```yaml
      # 开启 Syslog TCP/UDP 监听，字符集按现场设备实际编码调整。
      - SYSLOG_SERVER_ENABLED=true
      - SYSLOG_CHARSET=UTF-8

      # 单条最多接收 6 MiB，达到 128 KiB 时发送到大日志 Topic。
      - SYSLOG_MAX_FRAME_LENGTH=6291456
      - SYSLOG_MESSAGE_MAX_BYTES=6291456
      - SYSLOG_LARGE_MESSAGE_THRESHOLD_BYTES=131072

      # 200KiB/条容量基线；2GiB 字节预算在 70% 时约 7,300 条、1.4GiB 触发背压。
      - SYSLOG_WAL_QUEUE_CAPACITY=20000
      - SYSLOG_WAL_MAX_PENDING_BYTES=2147483648
      - SYSLOG_WAL_HIGH_WATERMARK_PERCENT=70
      - SYSLOG_WAL_LOW_WATERMARK_PERCENT=40
      - SYSLOG_WAL_FLUSH_RECORDS=200
      - SYSLOG_WAL_FLUSH_INTERVAL_MS=100
      - SYSLOG_WAL_SEGMENT_MAX_BYTES=2147483648

      # Kafka 投递限制正文最多 1GiB 在途，并增加加密后的 Producer 缓冲。
      - SYSLOG_DISPATCH_WORKER_THREADS=8
      - SYSLOG_DISPATCH_MAX_INFLIGHT=5000
      - SYSLOG_DISPATCH_MAX_INFLIGHT_BYTES=1073741824
      # 性能优先：无效设备正文不进 WAL，仅按设备缓存周期打印来源 IP。
      - SYSLOG_DISPATCH_TERMINAL_RECORD_ENABLED=false
      - SPRING_KAFKA_PRODUCER_PROPERTIES_BUFFER_MEMORY=536870912

      # Dockerfile 不展开 JAVA_OPTS，使用 JVM 自动读取的 JAVA_TOOL_OPTIONS。
      - JAVA_TOOL_OPTIONS=-Xms8g -Xmx24g -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -XX:MaxDirectMemorySize=8g -XX:+ExitOnOutOfMemoryError

      # 大日志 Kafka Topic 及 Producer 请求上限。
      - KAFKA_PRODUCER_LARGE_TOPIC=agent-01-syslog-topic.large
      - KAFKA_PRODUCER_MAX_REQUEST_SIZE=33554432
```

其中：

- `SYSLOG_MAX_FRAME_LENGTH`：TCP 单帧最大长度；
- `SYSLOG_MESSAGE_MAX_BYTES`：所有来源的单条日志硬上限，超过后拒绝；
- `SYSLOG_LARGE_MESSAGE_THRESHOLD_BYTES`：达到该值后走大日志 Topic；
- `SYSLOG_WAL_QUEUE_CAPACITY`、`SYSLOG_WAL_MAX_PENDING_BYTES`：共同限制 WAL 接入条数和原文字节量；
- `SYSLOG_DISPATCH_MAX_INFLIGHT_BYTES`：限制 Kafka Dispatcher 在途正文总量；
- `SYSLOG_DISPATCH_TERMINAL_RECORD_ENABLED`：`false` 在 WAL 前丢弃 Syslog 无效设备正文并按缓存周期打印 IP；`true` 写 WAL 并逐条保存 Terminal 审计文件；
- `JAVA_TOOL_OPTIONS`：设置实际 JVM 堆和直接内存上限，不能替换成当前 Dockerfile 不会展开的 `JAVA_OPTS`。

`SYSLOG_MAX_FRAME_LENGTH` 必须大于或等于 `SYSLOG_MESSAGE_MAX_BYTES`。如果设备发送 GBK，应将
`SYSLOG_CHARSET` 改为 `GBK`。无效设备判断只读取后台定时刷新的内存快照，不会在 Netty 网络线程访问 Redis 或达梦；
首次快照暂未就绪或刷新失败时，消息保守进入 WAL。

## 2. syslog-consumer-rule

配置文件：

```text
syslog-consumer-rule/docker-compose/docker-compose-consumer-rule-prod.yaml
```

在 `services.syslog-consumer-rule.environment` 中增加；如果以后部署多实例，各实例保持一致：

```yaml
      # 大日志独立消费通道。
      - KAFKA_CONSUMER_LARGE_TOPIC=agent-01-syslog-topic.large
      - SYSLOG_LARGE_LISTENER_ENABLED=true
      - SYSLOG_LARGE_LISTENER_CONCURRENCY=1
      - SYSLOG_LARGE_LISTENER_MAX_POLL_RECORDS=5
      - SYSLOG_LARGE_LISTENER_MAX_PARTITION_FETCH_BYTES=33554432
      - SYSLOG_LARGE_LISTENER_FETCH_MAX_BYTES=67108864

      # 大日志规则处理批次和独立线程池。
      - SYSLOG_LARGE_PROCESSING_BATCH_MAX_BYTES=8388608
      - SYSLOG_LARGE_PROCESSOR_CORE_POOL_SIZE=1
      - SYSLOG_LARGE_PROCESSOR_MAX_POOL_SIZE=2
      - SYSLOG_LARGE_PROCESSOR_QUEUE_CAPACITY=10

      # Retry、DLT、Replay 也允许传输大日志。
      - KAFKA_RELIABILITY_MAX_REQUEST_SIZE=33554432

      # 连续性优先：特殊异常即使无法写入 DLT，也记录告警并继续消费。
      - SYSLOG_FAILURE_CONTINUITY_ENABLED=true
      - SYSLOG_FAILURE_CONTINUITY_DLT_PUBLISH_TIMEOUT_MS=1000

      # InfluxDB 原文最多保存 256 KiB，单批写入最多 8 MiB。
      - INFLUXDB_RAW_MESSAGE_MAX_UTF8_BYTES=262144
      - INFLUXDB_RAW_WRITE_BATCH_MAX_BYTES=8388608

      # 达梦正常日志大字段和非标日志原文最多保存 256 KiB。
      - DM_NORMAL_LARGE_FIELD_MAX_UTF8_BYTES=262144
      - DM_NON_NORMAL_LARGE_FIELD_MAX_UTF8_BYTES=262144
```

被截断的数据会以以下标记结尾：

```text
...[HB_XDR_TRUNCATED original_utf8_bytes=原始字节数]
```

以下三个存储上限配置为 `0` 时表示不截断：

```text
INFLUXDB_RAW_MESSAGE_MAX_UTF8_BYTES
DM_NORMAL_LARGE_FIELD_MAX_UTF8_BYTES
DM_NON_NORMAL_LARGE_FIELD_MAX_UTF8_BYTES
```

规则解析始终使用完整原文，只在写入 InfluxDB 或达梦时截断。

`SYSLOG_FAILURE_CONTINUITY_ENABLED=true` 时：

- InfluxDB 原文写入失败，会先尝试把原消息写入普通/大日志 DLT，再继续规则解析和达梦写入；
- 其他无法完成的特殊异常，会先尝试写 DLT，然后提交原 Kafka offset，避免阻塞整个分区；
- 如果 DLT 也不可用，仍会输出 `[SYSLOG_CONTINUITY_LOSS]` 日志并提交 offset。此时消息可能无法重放，
  但不会阻塞后续新消息。

DLT 首次写入失败最多等待 `SYSLOG_FAILURE_CONTINUITY_DLT_PUBLISH_TIMEOUT_MS` 毫秒；随后不再逐条等待，
整批记录一次后立即放行。

设置为 `false` 可恢复原来的失败保留 offset 行为。

## 3. 日统计投影

日统计投影默认开启，一般不需要新增配置。只需确认现场没有配置：

```text
STATS_PROJECTION_ASYNC_ENABLED=false
```

如果现场需要显式写明，可以在 `syslog-consumer-rule` 的 `environment` 中配置：

```yaml
      - STATS_PROJECTION_ASYNC_ENABLED=true
      - STATS_PROJECTION_TOPIC=agent-01-syslog-topic.STATS.PROJECTION
      - STATS_PROJECTION_GROUP_ID=agent-01-syslog-group-dm-stats-projection
```

## 4. Kafka 配置

每个 Kafka Broker 的 `replica.fetch.max.bytes` 必须不小于 32 MiB：

```properties
replica.fetch.max.bytes=33554432
```

然后执行：

```bash
bash upgrade-doc/v3/kafka/02-create-large-log-topics.sh
```

生产者和消费者的大日志 Topic 名称必须完全相同：

```text
KAFKA_PRODUCER_LARGE_TOPIC=agent-01-syslog-topic.large
KAFKA_CONSUMER_LARGE_TOPIC=agent-01-syslog-topic.large
```

## 5. 使配置生效

在现场对应的部署目录先检查 Compose，再重建容器：

```bash
docker compose -f docker-compose-serve-prod.yaml config
docker compose -f docker-compose-serve-prod.yaml up -d --force-recreate syslog-serve

docker compose -f docker-compose-consumer-rule-prod.yaml config
docker compose -f docker-compose-consumer-rule-prod.yaml up -d --force-recreate syslog-consumer-rule
```

建议先升级 `syslog-consumer-rule`，确认大日志消费者正常后，再升级 `syslog-serve`。