王绍宏
3b6c9e4714
- 支持设备头字段值包含空格，避免 WAF 等名称被误拆为无效键值对 - 将空字符串 cropper offset 按未配置处理，兼容历史标准化规则 - 增加设备头解析和空 offset 回归测试 - 增加统计物化 Topic 创建脚本 - 增加容器内 JAR 热替换脚本及操作说明
206 lines
8.0 KiB
Markdown
206 lines
8.0 KiB
Markdown
# 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>"
|
||
```
|
||
|
||
## 发布顺序
|
||
|
||
升级 `syslog-consumer-rule` 前，先在 Kafka 集群执行一次
|
||
`upgrade-doc/v1/kafka/03-create-stats-materialize-topic.sh`，确认已经创建：
|
||
|
||
```text
|
||
agent-01-syslog-topic.STATS.MATERIALIZE
|
||
```
|
||
|
||
实际前缀以现场 `spring.kafka.consumer.topic` 为准。统计 Topic 的分区数、副本数会沿用原始 Topic；
|
||
三个 `syslog-consumer-rule` 实例必须使用相同的 `STATS_MATERIALIZATION_TOPIC` 和
|
||
`STATS_MATERIALIZATION_GROUP_ID`。
|
||
|
||
三个 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 没有持续增长；
|
||
- 统计物化 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` 两个只读脚本。
|