Files

T

王绍宏 00c0a1fb7f feat: 新增设备 API 拉取采集及配套处理能力

- 接入 NDRServer 告警和流量日志，支持凭据与任务管理
- 支持分页拉取、窗口拆分、调度优先级及 WAL 持久化后推进断点
- 增加迟到告警规则重放，优化多条泛化规则选择和事件时间处理
- 补充回归测试、数据库升级脚本及部署文档

2026-09-06 16:46:21 +08:00

5.2 KiB

Raw Blame History

NDRServer API 拉取配置示例

以下命令在 syslog-serve 启动、v2 数据库脚本验证通过后执行。示例中的地址、设备 ID 和凭据需要替换为现场值。

先说明两个概念：

凭据：设备提供的 AppKey 和 AppSecret，一台设备的两个任务可以共用一份凭据；
任务：具体拉取哪一类日志。告警和流量日志是两个任务，各自记录已经拉到的时间。
configVersion：任务每修改一次都会增加，用于防止两个人同时覆盖配置。调用修改、暂停或恢复接口时使用查询结果中的最新值。

1. 准备变量

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. 创建凭据

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. 创建告警任务

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：

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，执行验证：

curl -fsS -X POST \
  "${SERVE_API}/api/api-pull-tasks/<taskId>/validate" \
  -H 'Content-Type: application/json' \
  --data-binary '{"configVersion":<当前版本>}'

验证返回 valid=true 后恢复任务：

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`	有数据被隔离，需要查看服务日志

查询任务进度：

curl -fsS "${SERVE_API}/api/api-pull-tasks/<taskId>/runtime"

committedWindowEnd 表示已经完整处理到的时间。它持续向后变化，说明任务正在推进。

5.2 KiB Raw Blame History