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,154 @@
+# NDRServer API 拉取配置示例
+
+以下命令在 `syslog-serve` 启动、v2 数据库脚本验证通过后执行。示例中的地址、设备 ID 和凭据需要替换为现场值。
+
+先说明两个概念：
+
+- 凭据：设备提供的 AppKey 和 AppSecret，一台设备的两个任务可以共用一份凭据；
+- 任务：具体拉取哪一类日志。告警和流量日志是两个任务，各自记录已经拉到的时间。
+- `configVersion`：任务每修改一次都会增加，用于防止两个人同时覆盖配置。调用修改、暂停或恢复接口时使用查询结果中的最新值。
+
+## 1. 准备变量
+
+```bash
+export SERVE_API=http://127.0.0.1:8189/syslogserve
+export DEVICE_ID=<设备ID>
+export NDR_BASE_URL=https://<设备证书域名>/ndr/api
+export CREDENTIAL_REF=<凭据引用>
+export APP_KEY=<AppKey>
+export APP_SECRET=<AppSecret>
+export INITIAL_START_TIME=<YYYY-MM-DDTHH:mm:ss+08:00>
+```
+
+变量说明：
+
+| 变量 | 填写内容 | 示例格式 |
+| --- | --- | --- |
+| `SERVE_API` | `syslog-serve` 管理地址 | `http://127.0.0.1:8189/syslogserve` |
+| `DEVICE_ID` | 平台中的设备 ID | 整数 |
+| `NDR_BASE_URL` | NDR 接口根地址，结尾固定为 `/ndr/api` | `https://ndr.example.com/ndr/api` |
+| `CREDENTIAL_REF` | 本次凭据的名称 | `ndr-prod-01` |
+| `APP_KEY` | 设备提供的 AppKey | 字符串 |
+| `APP_SECRET` | 设备提供的 AppSecret | 字符串 |
+| `INITIAL_START_TIME` | 第一次从什么时间开始拉取 | `2026-09-06T00:00:00+08:00` |
+
+尖括号表示待填写内容，不能把 `<设备ID>` 这样的文字直接执行。
+
+凭据通过现场受控终端录入，不提交到代码库。
+
+## 2. 创建凭据
+
+```bash
+curl -fsS -X POST "${SERVE_API}/api/api-pull-credentials" \
+  -H 'Content-Type: application/json' \
+  --data-binary "{
+    \"credentialRef\":\"${CREDENTIAL_REF}\",
+    \"deviceId\":${DEVICE_ID},
+    \"adapterType\":\"NDRSERVER_V1\",
+    \"credentialVersion\":\"initial-v1\",
+    \"appKey\":\"${APP_KEY}\",
+    \"appSecret\":\"${APP_SECRET}\"
+  }"
+```
+
+接口响应不返回 AppKey、AppSecret 和 Token。
+
+创建成功时 HTTP 状态码为 `201`，响应中会有 `credentialRef` 和 `configVersion`。返回 `409` 一般表示同名凭据已经存在，此时先查询现有凭据，不要反复创建。
+
+## 3. 创建告警任务
+
+```bash
+curl -fsS -X POST "${SERVE_API}/api/api-pull-tasks" \
+  -H 'Content-Type: application/json' \
+  --data-binary "{
+    \"deviceId\":${DEVICE_ID},
+    \"taskName\":\"NDR-威胁告警-API拉取\",
+    \"adapterType\":\"NDRSERVER_V1\",
+    \"streamKey\":\"NDR_ALERT\",
+    \"baseUrl\":\"${NDR_BASE_URL}\",
+    \"credentialRef\":\"${CREDENTIAL_REF}\",
+    \"pollIntervalSeconds\":1,
+    \"pageSize\":100,
+    \"maxPagesPerRun\":1000,
+    \"schedulerPriority\":100,
+    \"connectTimeoutMs\":5000,
+    \"requestTimeoutMs\":30000,
+    \"windowSizeSeconds\":60,
+    \"safetyDelaySeconds\":120,
+    \"lookbackSeconds\":300,
+    \"maxResponseBytes\":16777216,
+    \"initialStartTime\":\"${INITIAL_START_TIME}\",
+    \"extraConfig\":{}
+  }"
+```
+
+## 4. 创建流量日志任务
+
+流量任务和告警任务分别维护 checkpoint：
+
+```bash
+curl -fsS -X POST "${SERVE_API}/api/api-pull-tasks" \
+  -H 'Content-Type: application/json' \
+  --data-binary "{
+    \"deviceId\":${DEVICE_ID},
+    \"taskName\":\"NDR-原始网络日志-API拉取\",
+    \"adapterType\":\"NDRSERVER_V1\",
+    \"streamKey\":\"NDR_FLOW_LOG\",
+    \"baseUrl\":\"${NDR_BASE_URL}\",
+    \"credentialRef\":\"${CREDENTIAL_REF}\",
+    \"pollIntervalSeconds\":1,
+    \"pageSize\":500,
+    \"maxPagesPerRun\":1000,
+    \"schedulerPriority\":10,
+    \"connectTimeoutMs\":5000,
+    \"requestTimeoutMs\":30000,
+    \"windowSizeSeconds\":60,
+    \"safetyDelaySeconds\":120,
+    \"lookbackSeconds\":0,
+    \"maxResponseBytes\":16777216,
+    \"initialStartTime\":\"${INITIAL_START_TIME}\",
+    \"extraConfig\":{}
+  }"
+```
+
+`pageSize=500` 是初始值，上线前根据响应大小、接口耗时和实际吞吐调整。
+
+## 5. 验证和启用
+
+任务创建后默认为暂停状态。记录响应中的 `taskId` 和 `configVersion`，执行验证：
+
+```bash
+curl -fsS -X POST \
+  "${SERVE_API}/api/api-pull-tasks/<taskId>/validate" \
+  -H 'Content-Type: application/json' \
+  --data-binary '{"configVersion":<当前版本>}'
+```
+
+验证返回 `valid=true` 后恢复任务：
+
+```bash
+curl -fsS -X POST \
+  "${SERVE_API}/api/api-pull-tasks/<taskId>/resume" \
+  -H 'Content-Type: application/json' \
+  --data-binary '{"configVersion":<当前版本>}'
+```
+
+上线时先启用告警任务，核对数量、事件时间和字段后，再启用流量日志任务。
+
+常见返回说明：
+
+| 返回内容 | 处理方式 |
+| --- | --- |
+| `valid=false` | 查看 `checks` 中状态为 `FAIL` 的项目，处理后重新验证 |
+| `CONFIG_VERSION_CONFLICT` | 重新查询任务，使用最新的 `configVersion` |
+| `enabled=true` | 任务已经开始调度 |
+| `recordsFetched=recordsDurable` | 本次拉取的数据已经写入 WAL |
+| `recordsQuarantined>0` | 有数据被隔离，需要查看服务日志 |
+
+查询任务进度：
+
+```bash
+curl -fsS "${SERVE_API}/api/api-pull-tasks/<taskId>/runtime"
+```
+
+`committedWindowEnd` 表示已经完整处理到的时间。它持续向后变化，说明任务正在推进。