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
@@ -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": {}
+}