ai-security-xdr/haobang-security-dm/upgrade-doc/v2/README.md

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 中保存一组数据的存储空间

先确认从哪里开始

现场分两种情况：

1. 已经执行过 upgrade-doc/v1：从本文“升级前”开始，只执行 v2。
2. 从未执行过 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 不在正常升级流程中执行。

升级前

1. 备份达梦数据库，保留旧 JAR、配置和镜像。
2. 确认 v1 的 database/04-verify.sql 已执行成功。
3. 记录 Kafka Topic、消费组 offset 和 lag。
4. 记录 InfluxDB 的组织、Bucket 和 Token 配置。
5. 暂停现有 API 拉取任务。
6. 停止 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>"

发布顺序

三个 JAR 一起升级：

1. syslog-consumer
2. syslog-consumer-rule
3. syslog-serve

先启动 syslog-consumer，再启动一台 syslog-consumer-rule。确认启动和写库正常后，启动其余实例，最后启动 syslog-serve。

API 任务先执行 validate。先启用告警任务，确认数量、时间和字段正确后，再启用流量日志任务。

任务创建和启用命令见 NDRServer任务配置示例。新建任务默认是暂停状态，不会在创建完成后立即拉取。

升级后检查

• 三个服务启动正常；
• Kafka lag 能回到 0，Retry/DLT 没有持续增长；
• 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 两个只读脚本。