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`。其中说明了哪些脚本只读、哪些脚本会修改数据库，以及脚本已经执行过时应如何判断。

按下面顺序执行：

```text
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](./api/NDRServer任务配置示例.md)。

## InfluxDB

当前配置使用：

```text
V1 Bucket = yelangbucket
V2 Bucket = yelangbucket_v2
写入格式 = V2
读取模式 = V1_V2
```

如果还没有 V2 Bucket，可以执行：

```bash
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/接入方式开关说明.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 示例：

```yaml
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任务配置示例](./api/NDRServer任务配置示例.md)。新建任务默认是暂停状态，不会在创建完成后立即拉取。

## 升级后检查

- 三个服务启动正常；
- 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` 两个只读脚本。