feat: 新增设备 API 拉取采集及配套处理能力
- 接入 NDRServer 告警和流量日志，支持凭据与任务管理 - 支持分页拉取、窗口拆分、调度优先级及 WAL 持久化后推进断点 - 增加迟到告警规则重放，优化多条泛化规则选择和事件时间处理 - 补充回归测试、数据库升级脚本及部署文档
This commit is contained in:
王绍宏
@@ -0,0 +1,192 @@
|
||||
# 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` 两个只读脚本。
|
||||
Reference in New Issue
Block a user