feat(syslog): 为三个生产模块增加启动版本标识

- syslog-serve 增加 SYSLOG_BUILD_READY 启动日志 - syslog-consumer 增加 SYSLOG_BUILD_READY 启动日志 - 更新 syslog-consumer-rule 代码修订标识至 v63 - 输出模块名、代码修订号、运行环境及关键非敏感配置 - 支持通过容器日志快速确认实际部署的 JAR 版本 - 补充 syslog-serve 和 syslog-consumer 启动日志测试 - 不输出数据库密码、API 凭据等敏感信息 - 不修改 Maven POM 配置
2026-09-17 18:47:25 +08:00
parent 8f1a8b6283
commit 2d297eb996
67 changed files with 3132 additions and 88 deletions
@@ -9,9 +9,10 @@
 | `v3/` | 日统计异步投影，以及大日志独立 Kafka 通道、字节背压和存储截断升级资料 |
 | `v4/` | Kafka 积压分级采样、告警优先落库和 InfluxDB 非阻塞旁路升级资料 |
 | `v5/` | 按设备短时采集未截断原始日志，并将异常样本优先落盘的现场诊断工具 |
+| `v6/` | 设备级采集模式：为 `device_device` 增加 `collection_mode`，支持 SYSLOG_ONLY、API_ONLY、BOTH |

 新环境按 v1、v2、v3、v4、v5 的顺序执行；已经完成 v4 的现场只需升级应用并执行 v5。已经执行过早期
-v3 日统计升级的现场，只需补做 v3 中的大日志 Topic、应用升级和验证步骤，再执行 v4、v5；不要重复执行
+v3 日统计升级的现场，只需补做 v3 中的大日志 Topic、应用升级和验证步骤，再执行 v4、v5、v6；不要重复执行
 数据库升级脚本。

 数据库脚本不要重复执行。执行过程中有报错时，先确认已经落库的对象，再决定从哪里继续。
@@ -20,3 +21,4 @@ v2 的执行步骤见 [v2/README.md](./v2/README.md)。
 v3 的执行步骤见 [v3/README.md](./v3/README.md)。
 v4 的执行步骤见 [v4/README.md](./v4/README.md)。
 v5 的执行步骤见 [v5/README.md](./v5/README.md)。
+v6 的执行步骤见 [v6/README.md](./v6/README.md)。
@@ -0,0 +1,59 @@
+# v6 设备级采集模式增量升级说明
+
+## 默认采集总开关
+
+新版默认同时开启 Syslog 服务和设备 API 拉取调度：
+
+```text
+SYSLOG_SERVER_ENABLED=true
+DEVICE_API_ENABLED=true
+```
+
+`DEVICE_DEVICE.COLLECTION_MODE` 默认 `BOTH`，因此既有设备升级后同时允许 Syslog 和 API。具体 API
+任务仍需完成校验并通过 `resume` 启用；全局开关为 true 不会自动启动暂停任务。
+
+## 必须执行的数据库脚本
+
+新版 `syslog-serve` 会直接查询 `device_device.collection_mode`。因此必须在启动新版 JAR 前，由 DBA 使用 `syslog-serve` 实际连接的 Schema 按顺序执行：
+
+```text
+database/01-device-collection-mode-precheck.sql
+database/02-device-collection-mode-upgrade.sql
+database/03-device-collection-mode-verify.sql
+```
+
+执行规则：
+
+1. 先备份 `DEVICE_DEVICE`，保存预检结果。
+2. `01` 中字段和约束查询首次升级时必须返回 0 行。
+3. `02` 只能成功执行一次；中途报错时不要整份重跑，应先检查已落库对象。
+4. `03` 必须确认字段为 `VARCHAR2(16) DEFAULT 'BOTH' NOT NULL`、约束已启用、非法数据数为 0。
+5. `03` 验证完成后即可启动新版 JAR。先配置下游微步 API JSON 泛化规则，再写入微步凭据、创建并验证 `WEIBU_LOG` 新任务；确认规则已关联设备后才能恢复任务并设置具体设备模式。
+
+默认 `BOTH` 用于兼容现有设备；升级 SQL 不硬编码任何设备 ID。
+
+本次 v6 强制数据库结构变更只有 `DEVICE_DEVICE.COLLECTION_MODE`。微步 API 复用现有
+`DEVICE_COLLECT_API_*` 基础表，不在本次升级中新增或修改这些表。新版微步适配器只支持
+`WEIBU_LOG`（`/api/v1/log/searchBySql`）；开发阶段的 `WEIBU_INCIDENT` 从未作为现场版本发布，因此不需要现场数据迁移脚本。
+
+## 现场设置示例
+
+```bash
+docker exec syslog-serve-dm curl -fsS -X PUT \
+  'http://127.0.0.1:8189/syslogserve/api/devices/40/collection-mode' \
+  -H 'Content-Type: application/json' \
+  -d '{"collectionMode":"API_ONLY"}'
+
+docker exec syslog-serve-dm curl -fsS \
+  'http://127.0.0.1:8189/syslogserve/api/devices/40'
+```
+
+GET 响应必须包含 `"collectionMode":"API_ONLY"`。设置后，设备 40 的微步 API 拉取任务继续运行，IP `10.56.171.164` 的 TCP/UDP Syslog 不得进入 WAL。
+
+多实例部署时，收到 PUT 请求的实例立即清理三层缓存并刷新入站快照；其他实例最迟在现有设备快照 TTL 后生效。
+
+微步凭据与任务、设备 `API_ONLY`、缓存清理、验收和回退已合并为一份现场手册：
+
+- [api/README.md](./api/README.md)
+
+按现场要求，[api/weibu-40-credential.json](./api/weibu-40-credential.json) 已填写设备 40 的真实微步 ApiKey/Secret；[api/weibu-40-task.json](./api/weibu-40-task.json) 已填写设备、地址和拉取参数，首次采集时间由现场命令生成。凭据文件包含明文生产秘密，必须限制整个 v6 目录的权限和分发范围；禁止把文件内容复制到工单、聊天或执行日志。
@@ -0,0 +1,149 @@
+# v6 API 现场操作
+
+API 相关升级只看本页。示例设备：`deviceId=40`、`IP=10.56.171.164`、微步 TDP。
+生产环境不映射管理端口，所有 API 命令都通过容器执行：
+
+- `syslog-serve-dm`：`8189`
+- `syslog-consumer-rule-dm`：`8289`
+
+## 1. 发布顺序
+
+1. 先按 `upgrade-doc/v6/README.md` 执行 3 个数据库脚本。
+2. 确认启动配置：
+
+   ```text
+   SYSLOG_SERVER_ENABLED=true
+   DEVICE_API_ENABLED=true
+   DEVICE_API_TLS_VERIFY_ENABLED=false
+   DEVICE_API_HOST_ALLOWLIST_ENABLED=false
+   ```
+
+3. 更换并启动新 JAR。新版 JAR 不能在数据库字段升级前启动。
+4. 检查启动日志：
+
+   ```bash
+   docker logs syslog-serve-dm 2>&1 | grep '\[SYSLOG_BUILD_READY\]' | tail -n 1
+   ```
+
+   必须看到 `apiPullEnabled=true`。内网默认 `apiTlsVerifyEnabled=false`。
+
+## 2. 配置微步 API 任务
+
+真实 Key/Secret 已保存在 `weibu-40-credential.json`，该文件必须按生产密钥管理。
+
+```bash
+chmod 600 upgrade-doc/v6/api/weibu-40-credential.json
+
+docker exec -i syslog-serve-dm curl -fsS -X POST \
+  'http://127.0.0.1:8189/syslogserve/api/api-pull-credentials' \
+  -H 'Content-Type: application/json' \
+  --data-binary '@-' \
+  < upgrade-doc/v6/api/weibu-40-credential.json
+```
+
+如果凭据已存在，不要重复创建。任务已存在时也直接复用。首次接入时，v6 目录已提供设备 40 的完整任务 JSON；执行前只把首次采集时间设为服务器当前时间减 2 分钟：
+
+```bash
+INITIAL_START_TIME=$(date -d '2 minutes ago' --iso-8601=seconds)
+sed "s|__INITIAL_START_TIME__|${INITIAL_START_TIME}|" \
+  upgrade-doc/v6/api/weibu-40-task.json \
+  > /tmp/weibu-40-task.json
+```
+
+执行前检查生成结果：
+
+```bash
+cat /tmp/weibu-40-task.json
+```
+
+必须确认 `deviceId=40`、`baseUrl=https://10.56.171.164`，且 `initialStartTime` 已经是真实时间，不再包含 `__INITIAL_START_TIME__`。
+
+```bash
+docker exec -i syslog-serve-dm curl -fsS -X POST \
+  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks' \
+  -H 'Content-Type: application/json' \
+  --data-binary '@-' \
+  < /tmp/weibu-40-task.json
+```
+
+记录返回的 `taskId` 和 `configVersion`。任务创建后默认暂停，先验证：
+
+```bash
+docker exec syslog-serve-dm curl -fsS -X POST \
+  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/<TASK_ID>/validate' \
+  -H 'Content-Type: application/json' \
+  -d '{"configVersion":<CONFIG_VERSION>}'
+```
+
+所有检查为 `PASS` 后，先在管理系统中给设备 40 关联能解析微步单条 JSON 的泛化规则，然后恢复任务：
+
+```bash
+docker exec syslog-serve-dm curl -fsS -X POST \
+  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/<TASK_ID>/resume' \
+  -H 'Content-Type: application/json' \
+  -d '{"configVersion":<CONFIG_VERSION>}'
+```
+
+## 3. 将设备 40 设为仅 API 采集
+
+禁止直接改数据库，必须调用 API，让三层设备缓存同时失效。
+
+```bash
+docker exec syslog-serve-dm curl -fsS -X PUT \
+  'http://127.0.0.1:8189/syslogserve/api/devices/40/collection-mode' \
+  -H 'Content-Type: application/json' \
+  -d '{"collectionMode":"API_ONLY"}'
+
+docker exec syslog-serve-dm curl -fsS \
+  'http://127.0.0.1:8189/syslogserve/api/devices/40'
+```
+
+GET 必须返回 `collectionMode=API_ONLY`。此后 `10.56.171.164` 的 TCP/UDP Syslog 被丢弃，API 任务继续运行。
+
+## 4. 验收
+
+```bash
+docker exec syslog-serve-dm curl -fsS \
+  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/<TASK_ID>/runtime'
+docker exec syslog-serve-dm curl -fsS \
+  'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/<TASK_ID>/runs?page=1&pageSize=5'
+```
+
+必须确认：
+
+- `health=HEALTHY`，最新 `SCHEDULED` 为 `SUCCESS`，HTTP 状态为 200。
+- checkpoint 持续推进；设备当时无日志时 `recordsFetched=0` 也是正常成功。
+- Kafka 中每条消息是一条微步 JSON，下游按设备 40 关联的泛化规则标准化。
+- 来自 `10.56.171.164` 的 Syslog 不进入 WAL/Kafka，其他默认 `BOTH` 设备不受影响。
+
+## 5. 缓存清理
+
+```bash
+# syslog-serve：指定设备 / 全部设备
+docker exec syslog-serve-dm curl -fsS -X DELETE \
+  'http://127.0.0.1:8189/syslogserve/api/devices/40/cache'
+docker exec syslog-serve-dm curl -fsS -X DELETE \
+  'http://127.0.0.1:8189/syslogserve/api/devices/cache'
+
+# syslog-consumer-rule：指定设备规则 / 全部规则
+docker exec syslog-consumer-rule-dm curl -fsS -X DELETE \
+  'http://127.0.0.1:8289/xdrrule/api/syslog/normalization/cache/devices/40'
+docker exec syslog-consumer-rule-dm curl -fsS -X DELETE \
+  'http://127.0.0.1:8289/xdrrule/api/syslog/normalization/cache'
+```
+
+规则缓存清理会通知所有正常订阅 Redis 消息的 `syslog-consumer-rule` 实例。不要使用旧的 `DELETE /api/cache/all`。
+
+## 6. 快速回退
+
+1. 暂停微步 API 任务。
+2. 将设备改回 `BOTH`：
+
+   ```bash
+   docker exec syslog-serve-dm curl -fsS -X PUT \
+     'http://127.0.0.1:8189/syslogserve/api/devices/40/collection-mode' \
+     -H 'Content-Type: application/json' \
+     -d '{"collectionMode":"BOTH"}'
+   ```
+
+3. 恢复原泛化规则关联和旧 JAR。不删除 `COLLECTION_MODE` 字段，不删除任务、凭据或 checkpoint。
@@ -0,0 +1,8 @@
+{
+  "credentialRef": "weibu-40",
+  "deviceId": 40,
+  "adapterType": "WEIBU_V1",
+  "credentialVersion": "v1",
+  "appKey": "57d8fb2b556a471ea36b8b4441fa1c0c",
+  "appSecret": "9d967876f51d4e16bbf8bde069d12a9b"
+}
@@ -0,0 +1,20 @@
+{
+  "deviceId": 40,
+  "taskName": "微步逐条日志拉取",
+  "adapterType": "WEIBU_V1",
+  "streamKey": "WEIBU_LOG",
+  "baseUrl": "https://10.56.171.164",
+  "credentialRef": "weibu-40",
+  "pollIntervalSeconds": 30,
+  "pageSize": 1000,
+  "maxPagesPerRun": 1,
+  "schedulerPriority": 0,
+  "connectTimeoutMs": 5000,
+  "requestTimeoutMs": 30000,
+  "windowSizeSeconds": 300,
+  "safetyDelaySeconds": 120,
+  "lookbackSeconds": 300,
+  "maxResponseBytes": 16777216,
+  "initialStartTime": "__INITIAL_START_TIME__",
+  "extraConfig": {}
+}
@@ -0,0 +1,33 @@
+-- v6 设备级采集模式：达梦数据库升级前检查
+-- 本脚本只读。必须先完成检查，再执行 02-device-collection-mode-upgrade.sql。
+-- 新版 syslog-serve JAR 启动前必须完成字段升级和验证。
+
+-- 1. 确认当前用户和 DEVICE_DEVICE 表存在。
+SELECT USER AS CURRENT_SCHEMA FROM DUAL;
+
+SELECT TABLE_NAME
+FROM USER_TABLES
+WHERE TABLE_NAME = 'DEVICE_DEVICE';
+
+-- 2. 记录升级前设备总数、有效设备数，供升级后核对。
+SELECT COUNT(*) AS DEVICE_TOTAL
+FROM DEVICE_DEVICE;
+
+SELECT COUNT(*) AS ACTIVE_DEVICE_TOTAL
+FROM DEVICE_DEVICE
+WHERE DELETED_AT IS NULL
+  AND (DEL_FLAG IS NULL OR DEL_FLAG = '0');
+
+-- 3. 目标字段应不存在。首次升级时预期返回 0 行；若已有记录，停止执行升级脚本并先核实。
+SELECT COLUMN_NAME, DATA_TYPE, DATA_LENGTH, NULLABLE, DATA_DEFAULT
+FROM USER_TAB_COLUMNS
+WHERE TABLE_NAME = 'DEVICE_DEVICE'
+  AND COLUMN_NAME = 'COLLECTION_MODE';
+
+-- 4. 约束名应未被占用。首次升级时预期返回 0 行。
+SELECT CONSTRAINT_NAME, CONSTRAINT_TYPE, STATUS
+FROM USER_CONSTRAINTS
+WHERE CONSTRAINT_NAME = 'CK_DEVICE_COLLECTION_MODE';
+
+-- 5. 执行 DDL 前必须完成 DEVICE_DEVICE 可恢复备份，并确认没有未结束的长事务或表锁。
+-- 数据库脚本不得写死现场 device_id；具体设备模式在新版 JAR 启动后通过管理 API 设置。
@@ -0,0 +1,25 @@
+-- v6 设备级采集模式：达梦数据库升级
+-- 强制顺序：停止/保持旧版应用 -> 备份 -> 01 预检 -> 本脚本 -> 03 验证 -> 启动新版 JAR。
+-- 新版 syslog-serve 的所有设备查询都会读取 COLLECTION_MODE，本脚本必须在新版 JAR 启动前执行。
+-- 本脚本不设置任何现场 device_id；所有既有设备统一回填 BOTH，避免误停原有 Syslog 或 API 任务。
+
+ALTER TABLE DEVICE_DEVICE
+  ADD COLLECTION_MODE VARCHAR2(16) DEFAULT 'BOTH';
+
+UPDATE DEVICE_DEVICE
+SET COLLECTION_MODE = 'BOTH'
+WHERE COLLECTION_MODE IS NULL;
+
+COMMIT;
+
+ALTER TABLE DEVICE_DEVICE
+  MODIFY COLLECTION_MODE VARCHAR2(16) DEFAULT 'BOTH' NOT NULL;
+
+ALTER TABLE DEVICE_DEVICE
+  ADD CONSTRAINT CK_DEVICE_COLLECTION_MODE
+  CHECK (COLLECTION_MODE IN ('SYSLOG_ONLY', 'API_ONLY', 'BOTH'));
+
+COMMENT ON COLUMN DEVICE_DEVICE.COLLECTION_MODE IS
+  '设备级采集模式：SYSLOG_ONLY、API_ONLY、BOTH；默认 BOTH';
+
+COMMIT;
@@ -0,0 +1,28 @@
+-- v6 设备级采集模式：达梦数据库升级后验证
+-- 本脚本只读。所有检查通过后才允许启动新版 syslog-serve JAR。
+
+-- 1. 预期 1 行：VARCHAR2(16)、NULLABLE=N、DATA_DEFAULT 包含 BOTH。
+SELECT COLUMN_NAME, DATA_TYPE, DATA_LENGTH, NULLABLE, DATA_DEFAULT
+FROM USER_TAB_COLUMNS
+WHERE TABLE_NAME = 'DEVICE_DEVICE'
+  AND COLUMN_NAME = 'COLLECTION_MODE';
+
+-- 2. 预期 1 行：CONSTRAINT_TYPE=C、STATUS=ENABLED。
+SELECT CONSTRAINT_NAME, CONSTRAINT_TYPE, STATUS
+FROM USER_CONSTRAINTS
+WHERE TABLE_NAME = 'DEVICE_DEVICE'
+  AND CONSTRAINT_NAME = 'CK_DEVICE_COLLECTION_MODE';
+
+-- 3. 预期 INVALID_MODE_TOTAL=0。
+SELECT COUNT(*) AS INVALID_MODE_TOTAL
+FROM DEVICE_DEVICE
+WHERE COLLECTION_MODE IS NULL
+   OR COLLECTION_MODE NOT IN ('SYSLOG_ONLY', 'API_ONLY', 'BOTH');
+
+-- 4. 首次升级且尚未调用管理 API 时，预期只有 BOTH，数量与预检 DEVICE_TOTAL 一致。
+SELECT COLLECTION_MODE, COUNT(*) AS DEVICE_TOTAL
+FROM DEVICE_DEVICE
+GROUP BY COLLECTION_MODE
+ORDER BY COLLECTION_MODE;
+
+-- 验证脚本不创建测试设备，也不绑定任何现场 device_id。