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,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 和防火墙中关闭不需要的入口。