王绍宏
1c07acc01d
一、增加现场原始日志采集功能
1. 新增按设备采集原始日志的API：
- 指定设备ID；
- 采集时长最长10分钟；
- 单次最多返回50条样本。
2. 样本选择策略：
- 优先保留时间窗口内最早到达的N条日志；
- 后续出现JSON解析异常、非标、规则执行异常、InfluxDB/达梦写入异常或Retry/DLT时，
使用异常日志逐条替换最早的正常样本；
- 异常样本同样遵循先到先得。
3. 支持三个syslog-consumer-rule实例联合采集：
- 采集请求只需发送到任意一个实例；
- 三个实例通过公共Redis同步采集任务并汇总候选样本；
- 不需要配置其他实例IP；
- Redis只保存有界候选集，不保存时间窗口内的全部日志。
4. 生命周期和资源控制：
- 采集到期后自动停止接收新日志；
- 默认进入30秒DRAINING阶段，等待异步处理异常完成样本替换；
- 最终结果默认保留30分钟，之后自动删除；
- 单实例、单会话最多保留“前N条+前N条异常”；
- Redis故障不阻断Kafka主消费链路。
5. 返回规则解析和非标表截断之前的完整原始报文，不受
HB_XDR_TRUNCATED字段截断影响。
6. 原始日志采集和多实例汇聚默认启用：
SYSLOG_RAW_CAPTURE_ENABLED=true
SYSLOG_RAW_CAPTURE_CLUSTER_ENABLED=true
二、修复天眼/微步JSON规则匹配问题
1. JSON规则配置了cropper时，先判断原始报文是否包含对应head_key；
不匹配的规则不再将当前报文误判为非法JSON。
2. 同一设备绑定多条规则时，单条不适用或解析失败的JSON规则不再立即终止整个规则链，
程序会继续匹配后续适用规则。
3. 只有全部适用JSON规则均解析失败、且没有其他规则成功处理时，才写入
“JSON解析异常”非标记录。
4. 对cropper截取后仍包含Syslog或设备前缀的内容，在JSON专用路径中重新收敛到
第一个“{”至最后一个“}”，确保交给Jackson的是完整外层JSON。
5. 修复以下现场场景：
- 天眼规则129截取结果仍带有alarm前缀；
- 微步设备同时绑定固定偏移规则和Threatbook/TDP JSON规则；
- 不适用的固定偏移规则抢先产生JSON解析异常；
- Syslog头加JSON正文不能继续匹配后续适用规则。
三、增加现场采集工具及运维说明
新增upgrade-doc/v5：
- README.md：升级、配置、生命周期和故障排查说明；
- capture-device-raw-logs.sh：一键创建采集会话、等待完成并自动落盘。
脚本输出：
- result.json：完整采集结果；
- samples.jsonl：每行一条样本及处理状态；
- raw/*.log：每条未截断原始报文；
- summary.txt：采集数量、异常数量和替换数量；
- latest.json：中断或超时时的最后有效快照。
四、兼容性与升级范围
- 兼容JDK 8；
- 无需新增或修改达梦数据库表；
- 无需创建新的Kafka Topic；
- 需要滚动升级全部syslog-consumer-rule实例；
- 三个实例必须连接相同的Redis；
- 本次提交不包含syslog-serve的高内存、WAL或JVM参数调整。
v2 增量升级说明
升级内容
v2 对应提交 b61ec2e 之后的改动，执行前默认现场已经完成 v1。
这次主要增加：
- NDRServer API 拉取；
- TCP、UDP、API 三种接入方式独立开关；
- Kafka 消息中的
receive_time、event_time和point_time_ns； - API 拉取任务的窗口拆分和调度优先级；
- 迟到告警的规则重放；
- 同设备多条泛化规则的选择逻辑；
- 独立的 InfluxDB V2 Bucket。
Kafka 不需要新建 Topic，也不要调整消费组 offset。达梦只需要执行本目录的 API 拉取和迟到重放脚本。
文中几个常用词：
| 名称 | 含义 |
|---|---|
| checkpoint | 任务已经成功处理到的时间位置 |
| lag | Kafka 中还没有消费的消息数量 |
| WAL | syslog-serve 写入 Kafka 前保存在本地磁盘的数据 |
| Bucket | InfluxDB 中保存一组数据的存储空间 |
先确认从哪里开始
现场分两种情况：
- 已经执行过
upgrade-doc/v1：从本文“升级前”开始，只执行 v2。 - 从未执行过
upgrade-doc/v1：先完成 v1，再回来执行 v2。
如果不确定，先让 DBA 执行 v1 的 database/04-verify.sql。不要用“再执行一次 v1”来试，因为其中包含建表和初始化数据。
人员分工
| 人员 | 负责内容 |
|---|---|
| DBA | 数据库备份，执行 database 目录中的 SQL |
| 运维 | InfluxDB、环境变量、证书、容器和 JAR 升级 |
| 开发 | 设备接口适配和上线后的字段核对 |
文件说明
| 文件 | 用途 |
|---|---|
config/接入方式开关说明.md |
TCP、UDP、API 拉取的启停组合、任务开关和生效检查 |
database/README.md |
数据库脚本执行顺序、注意事项和成功判断方法 |
database/01-device-api-pull-precheck.sql |
检查 API 拉取建表条件 |
database/02-device-api-pull-upgrade.sql |
创建凭据、任务、checkpoint、运行记录四张表 |
database/03-device-api-pull-verify.sql |
验证 API 拉取表、约束和索引 |
database/04-fairness-late-replay-precheck.sql |
检查调度优先级和迟到重放建表条件 |
database/05-fairness-late-replay-upgrade.sql |
增加调度优先级和两张重放表 |
database/06-fairness-late-replay-verify.sql |
验证调度优先级和重放表 |
database/80-late-replay-backfill-template.sql |
可选的历史告警补录模板 |
database/90-device-api-pull-rollback-audit.sql |
回滚时只读检查 API 拉取数据 |
database/91-fairness-late-replay-rollback-audit.sql |
回滚时只读检查迟到重放数据 |
80、90、91 不在正常升级流程中执行。
升级前
- 备份达梦数据库，保留旧 JAR、配置和镜像。
- 确认 v1 的
database/04-verify.sql已执行成功。 - 记录 Kafka Topic、消费组 offset 和 lag。
- 记录 InfluxDB 的组织、Bucket 和 Token 配置。
- 暂停现有 API 拉取任务。
- 停止
syslog-serve，等主消费组 lag 降到 0 后再停止两个消费者。
不要清空 Kafka，也不要删除历史数据。
执行达梦脚本
第一次执行前，先阅读 database/README.md。其中说明了哪些脚本只读、哪些脚本会修改数据库，以及脚本已经执行过时应如何判断。
按下面顺序执行：
01-device-api-pull-precheck.sql
02-device-api-pull-upgrade.sql
03-device-api-pull-verify.sql
04-fairness-late-replay-precheck.sql
05-fairness-late-replay-upgrade.sql
06-fairness-late-replay-verify.sql
每个文件单独执行。上一个文件结果正常后，再执行下一个文件。
检查结果：
01最后一组查询应当为空，表示四张 API 表还没有创建；03第一组查询应返回四张DEVICE_COLLECT_API_*表；04前两组查询应当为空，第三组应返回ANALYSIS_CHECKPOINT；06应返回SCHEDULER_PRIORITY、两张重放表以及对应索引；- 查询结果中的约束应为
ENABLED，索引应为VALID。
脚本中途报错时不要整份重跑，先查询已经创建的对象。
设备凭据和任务不使用 SQL 插入。服务启动后，通过 /api/api-pull-credentials 和 /api/api-pull-tasks 创建。示例见 api/NDRServer任务配置示例.md。
InfluxDB
当前配置使用：
V1 Bucket = yelangbucket
V2 Bucket = yelangbucket_v2
写入格式 = V2
读取模式 = V1_V2
如果还没有 V2 Bucket，可以执行：
export INFLUX_CONTAINER=<InfluxDB容器名>
export INFLUX_ORG=<组织名>
export V2_BUCKET=yelangbucket_v2
export RETENTION=720h
export SHARD_GROUP_DURATION=24h
bash upgrade-doc/v2/influxdb/01-ensure-v2-bucket.sh
脚本发现同名 Bucket 时只显示现有配置，不会修改。还要确认应用 Token 对这个 Bucket 有读写权限。
命令返回 401 Unauthorized 表示当前 Influx CLI 配置没有管理权限，需要运维换用管理员配置后再执行。
配置
三个服务的新增环境变量分别放在 config/ 下。
TCP、UDP 和 API 拉取的打开、关闭及验证方法见 config/接入方式开关说明.md。
| 配置文件 | 放到哪个服务 |
|---|---|
config/syslog-serve.env.example |
syslog-serve |
config/syslog-consumer-rule.env.example |
syslog-consumer-rule |
config/syslog-consumer.env.example |
syslog-consumer |
示例文件不能直接作为正式配置使用。先复制需要的项目，再把尖括号中的内容换成现场值。
部署时注意：
SYSLOG_SERVER_ENABLED同时控制 TCP 和 UDP，当前版本不能分别开关；SYSLOG_SERVER_ENABLED和DEVICE_API_ENABLED可以独立设置或同时打开；- API 拉取还需要单独恢复具体任务，打开全局开关不会自动恢复暂停任务；
DEVICE_API_ALLOWED_HOSTS只填写现场设备地址；- AppKey 和 AppSecret 通过管理接口保存，不写进配置文件；
- 自签名证书导入 Java truststore；
- 证书使用域名时，在 Compose 中配置固定映射。
Compose 示例：
services:
syslog-serve:
extra_hosts:
- "<设备证书域名>:<设备IP>"
发布顺序
升级 syslog-consumer-rule 前，先在 Kafka 集群执行一次
upgrade-doc/v1/kafka/03-create-stats-materialize-topic.sh，确认已经创建：
agent-01-syslog-topic.STATS.MATERIALIZE
实际前缀以现场 spring.kafka.consumer.topic 为准。统计 Topic 的分区数、副本数会沿用原始 Topic；
三个 syslog-consumer-rule 实例必须使用相同的 STATS_MATERIALIZATION_TOPIC 和
STATS_MATERIALIZATION_GROUP_ID。
三个 JAR 一起升级：
syslog-consumersyslog-consumer-rulesyslog-serve
先启动 syslog-consumer，再启动一台 syslog-consumer-rule。确认启动和写库正常后，启动其余实例，最后启动 syslog-serve。
API 任务先执行 validate。先启用告警任务，确认数量、时间和字段正确后，再启用流量日志任务。
任务创建和启用命令见 NDRServer任务配置示例。新建任务默认是暂停状态，不会在创建完成后立即拉取。
升级后检查
- 三个服务启动正常；
- Kafka lag 能回到 0，Retry/DLT 没有持续增长；
- 统计物化 Topic 没有持续积压，日志持续出现
统计物化批次完成； /api/syslog/stats/direct/status中物化发布、消费、对账均无持续失败；- WAL checkpoint 能追上 durable sequence；
- API validate 的配置、DNS、TLS、认证和最小查询全部通过；
- API run 中
recordsFetched与recordsDurable一致，recordsQuarantined=0； - 标准化数据按
event_time进入正确日期分区； - 两张迟到重放表没有记录长期停在
RUNNING； - InfluxDB V2 Bucket 有新数据。
回滚
先暂停 API 任务并停止新入口，然后回滚三个 JAR 和配置。
新增表、字段和索引保留，不删除 API checkpoint、迟到重放记录、Kafka Topic 或消费组 offset。需要核对时执行 90、91 两个只读脚本。