feat: 新增设备 API 拉取采集及配套处理能力

- 接入 NDRServer 告警和流量日志，支持凭据与任务管理 - 支持分页拉取、窗口拆分、调度优先级及 WAL 持久化后推进断点 - 增加迟到告警规则重放，优化多条泛化规则选择和事件时间处理 - 补充回归测试、数据库升级脚本及部署文档
2026-09-06 16:46:21 +08:00
parent b61ec2e37c
commit 00c0a1fb7f
141 changed files with 11318 additions and 467 deletions
@@ -0,0 +1,19 @@
+# 新消息写 V2；升级期间同时读取 V1/V2，避免切换窗口丢失旧点。
+INFLUXDB_RAW_WRITE_SCHEMA=V2
+INFLUXDB_RAW_READ_MODE=V1_V2
+INFLUXDB_RAW_V1_BUCKET=yelangbucket
+INFLUXDB_RAW_V2_BUCKET=yelangbucket_v2
+INFLUXDB_RAW_UUID_BUCKET_COUNT=4096
+INFLUXDB_RAW_LEGACY_POINT_TIME_FALLBACK_ENABLED=true
+INFLUXDB_RAW_QUERY_MAX_ROWS=10000
+
+# 标准化告警和迟到事实通知在同一个达梦事务中提交。
+ANALYSIS_LATE_REPLAY_OUTBOX_ENABLED=true
+
+# 同设备多条泛化规则只选择一个确定性胜出规则。
+NORMALIZATION_RULE_SELECTION_ENABLED=true
+NORMALIZATION_RULE_SELECTION_SHADOW_ENABLED=true
+NORMALIZATION_RULE_SELECTION_AMBIGUOUS_FALLBACK=LOWEST_RULE_ID
+NORMALIZATION_RULE_SELECTION_DETAIL_LOG_ENABLED=false
+NORMALIZATION_RULE_SELECTION_EXPLICIT_ENABLED=true
+NORMALIZATION_RULE_SELECTION_AUTOMATIC_FALLBACK_ENABLED=true
@@ -0,0 +1,16 @@
+# 与 syslog-consumer-rule 使用相同的 V1/V2 Bucket 契约。
+INFLUXDB_RAW_WRITE_SCHEMA=V2
+INFLUXDB_RAW_READ_MODE=V1_V2
+INFLUXDB_RAW_V1_BUCKET=yelangbucket
+INFLUXDB_RAW_V2_BUCKET=yelangbucket_v2
+INFLUXDB_RAW_UUID_BUCKET_COUNT=4096
+INFLUXDB_RAW_LEGACY_POINT_TIME_FALLBACK_ENABLED=true
+INFLUXDB_RAW_QUERY_MAX_ROWS=10000
+
+# 独立重放已经完成、但后来到达了告警事实的规则窗口。
+ANALYSIS_LATE_REPLAY_ENABLED=true
+ANALYSIS_LATE_REPLAY_SCAN_INTERVAL_MS=5000
+ANALYSIS_LATE_REPLAY_LEASE_SECONDS=1800
+ANALYSIS_LATE_REPLAY_MAX_BUCKETS_PER_SCAN=100
+ANALYSIS_LATE_REPLAY_MAX_WINDOWS_PER_SCAN=10
+ANALYSIS_LATE_REPLAY_RETRY_DELAY_SECONDS=30
@@ -0,0 +1,25 @@
+# TCP 和 UDP 当前共用一个网络监听开关；API 拉取使用另一个独立开关。
+# 组合方式和生效步骤见 config/接入方式开关说明.md。
+# 修改环境变量后需要重新创建容器，仅执行 docker restart 不会加载 Compose 新配置。
+SYSLOG_SERVER_ENABLED=true
+DEVICE_API_ENABLED=false
+
+# 只允许经过批准的设备域名或 IP，多个值使用英文逗号分隔。
+DEVICE_API_ALLOWED_HOSTS=<ndr.example.com>
+DEVICE_API_INSTANCE_ID=<当前实例稳定标识>
+DEVICE_API_SCAN_INTERVAL_MS=5000
+DEVICE_API_LEASE_SECONDS=120
+DEVICE_API_GLOBAL_CONCURRENCY=4
+DEVICE_API_PER_HOST_CONCURRENCY=1
+DEVICE_API_MAX_PAGES_PER_SLICE=20
+DEVICE_API_SLOW_PAGE_THRESHOLD_MS=1000
+DEVICE_API_BACKPRESSURE_TIMEOUT_MS=120000
+
+# 已完成并投递成功的 WAL 分段保留天数；按磁盘容量规划调整。
+SYSLOG_WAL_RETENTION_DAYS=2
+SYSLOG_WAL_DISK_HIGH_WATERMARK_PERCENT=90
+SYSLOG_WAL_MIN_FREE_BYTES=10737418240
+SYSLOG_POINT_TIME_WRITE_ENABLED=true
+
+# 自签名设备证书示例。路径必须通过 volume 挂载进入容器。
+JAVA_OPTS=-Djavax.net.ssl.trustStore=/app/ssl/syslog-serve-cacerts -Djavax.net.ssl.trustStorePassword=<PASSWORD>
@@ -0,0 +1,148 @@
+# TCP、UDP 和 API 拉取开关说明
+
+接入开关都配置在 `syslog-serve` 服务中。修改开关不会删除任务、凭据、checkpoint 或历史日志。
+
+## 1. 两个全局开关
+
+| 环境变量 | 控制内容 | `true` | `false` |
+| --- | --- | --- | --- |
+| `SYSLOG_SERVER_ENABLED` | 网络监听 | 同时打开 TCP 和 UDP Syslog 监听 | 同时关闭 TCP 和 UDP Syslog 监听 |
+| `DEVICE_API_ENABLED` | 设备 API 拉取调度器 | 允许调度已启用的 API 任务 | 停止调度所有 API 拉取任务 |
+
+当前版本的 TCP 和 UDP 共用 `SYSLOG_SERVER_ENABLED`，不能通过两个独立环境变量分别打开或关闭。
+
+`SYSLOG_SERVER_ENABLED` 与 `DEVICE_API_ENABLED` 互不排斥，可以同时打开，也可以只打开其中一种。
+
+## 2. 常用配置组合
+
+| 使用方式 | `SYSLOG_SERVER_ENABLED` | `DEVICE_API_ENABLED` |
+| --- | --- | --- |
+| 只接收 TCP/UDP 推送 | `true` | `false` |
+| 只使用 API 拉取 | `false` | `true` |
+| TCP/UDP 和 API 同时使用 | `true` | `true` |
+| 暂停所有日志接入 | `false` | `false` |
+
+例如，只使用 API 拉取：
+
+```yaml
+services:
+  syslog-serve:
+    environment:
+      - SYSLOG_SERVER_ENABLED=false
+      - DEVICE_API_ENABLED=true
+```
+
+例如，同时使用设备推送和 API 拉取：
+
+```yaml
+services:
+  syslog-serve:
+    environment:
+      - SYSLOG_SERVER_ENABLED=true
+      - DEVICE_API_ENABLED=true
+```
+
+## 3. 修改后如何生效
+
+环境变量在 `syslog-serve` 启动时读取。修改 Compose 文件后，需要重新创建容器：
+
+```bash
+docker compose -f <Compose文件路径> up -d --force-recreate syslog-serve
+```
+
+如果 Compose 中的服务名不是 `syslog-serve`，请换成现场实际服务名。
+
+只执行下面的命令不能加载刚修改的 Compose 环境变量：
+
+```bash
+docker restart syslog-serve-dm
+```
+
+`docker restart` 只重启原容器，仍会使用创建该容器时保存的旧环境变量。
+
+## 4. API 拉取有两层开关
+
+API 拉取必须同时满足：
+
+1. 全局开关 `DEVICE_API_ENABLED=true`；
+2. 具体任务的 `enabled=true`。
+
+因此，把全局开关改成 `true` 不会自动恢复已经暂停的任务。任务仍需通过管理接口恢复。
+
+查询任务当前版本：
+
+```bash
+export SYSLOG_SERVE_BASE_URL=http://127.0.0.1:8189/syslogserve
+
+curl -sS \
+  "${SYSLOG_SERVE_BASE_URL}/api/api-pull-tasks/<taskId>"
+```
+
+响应中的 `configVersion` 是任务当前版本。恢复任务：
+
+```bash
+curl -sS -X POST \
+  "${SYSLOG_SERVE_BASE_URL}/api/api-pull-tasks/<taskId>/resume" \
+  -H 'Content-Type: application/json' \
+  --data-binary '{"configVersion":<当前版本>}'
+```
+
+暂停任务：
+
+```bash
+curl -sS -X POST \
+  "${SYSLOG_SERVE_BASE_URL}/api/api-pull-tasks/<taskId>/pause" \
+  -H 'Content-Type: application/json' \
+  --data-binary '{"configVersion":<当前版本>}'
+```
+
+每次恢复或暂停成功后，`configVersion` 都会增加。再次操作前要重新查询任务，不能一直使用旧版本号。
+
+## 5. 检查配置是否生效
+
+先查看容器实际使用的环境变量：
+
+```bash
+docker inspect syslog-serve-dm \
+  --format '{{range .Config.Env}}{{println .}}{{end}}' \
+  | grep -E '^(SYSLOG_SERVER_ENABLED|DEVICE_API_ENABLED)='
+```
+
+再查看启动日志：
+
+```bash
+docker logs --since 5m syslog-serve-dm 2>&1 \
+  | grep -E 'TCP Syslog server started|UDP Syslog server started|Both TCP and UDP|设备 API 拉取调度器配置'
+```
+
+判断方法：
+
+- 出现 `TCP Syslog server started` 和 `UDP Syslog server started`，表示网络监听已打开；
+- 没有 TCP/UDP 启动记录，并且容器环境中 `SYSLOG_SERVER_ENABLED=false`，表示网络监听已关闭；
+- 出现 `设备 API 拉取调度器配置: enabled=true`，表示 API 全局开关已打开；
+- 出现 `设备 API 拉取调度器配置: enabled=false`，表示 API 全局开关已关闭。
+
+最后还要查询具体 API 任务：
+
+```bash
+curl -sS \
+  "${SYSLOG_SERVE_BASE_URL}/api/api-pull-tasks/<taskId>/runtime"
+```
+
+响应中的 `enabled=true` 表示该任务已启用；`committedWindowEnd` 持续向后变化，才表示任务正在正常推进。
+
+## 6. 端口配置注意事项
+
+当 `SYSLOG_SERVER_ENABLED=true` 时，Compose 还需要发布 TCP 和 UDP 端口，例如：
+
+```yaml
+ports:
+  - "514:514/tcp"
+  - "514:514/udp"
+```
+
+端口映射和程序开关是两件事：
+
+- 只有端口映射、但 `SYSLOG_SERVER_ENABLED=false`，程序不会监听 TCP/UDP；
+- `SYSLOG_SERVER_ENABLED=true`、但没有正确映射或开放端口，容器外设备仍无法连接；
+- 只使用 API 拉取时，可以保留端口映射，但建议同时从 Compose 和防火墙中关闭不需要的入口。