# 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_SCHEDULER_SCAN_INTERVAL_MS=1000 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 ``` 必须看到 `codeRevision=WEIBU_5S_50000_512M_V20260917_71`、`apiPullEnabled=true`、 `apiSchedulerScanIntervalMs=1000`，并确认 `deviceCollectId` 与设备 40 的 `DEVICE_DEVICE.DEVICE_COLLECT_ID` 一致。内网默认 `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__`。 同时确认本次常规任务使用默认的 `lookbackSeconds=0`。只有现场确有迟到日志补偿需求并完成容量评估后， 才显式配置正数；微步接口没有已确认的分页游标，正数回看可能增加单个时间窗口的数据量。 还必须确认 `windowSizeSeconds=5`、`pageSize=50000`、`maxPagesPerRun=1`、 `pollIntervalSeconds=1` 和 `maxResponseBytes=536870912`。50000 条按每条最大 10 KiB 估算约为 488 MiB，响应上限取整为 512 MiB；超限时任务失败且不推进 checkpoint，不会截断后伪装成功。 生产容器必须使用 `JAVA_TOOL_OPTIONS=-Xms8g -Xmx24g ...`，不得使用只有 `-Xmx1g` 的开发配置。 ```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//validate' \ -H 'Content-Type: application/json' \ -d '{"configVersion":}' ``` 所有检查为 `PASS` 后，先在管理系统中给设备 40 关联能解析微步单条 JSON 的泛化规则，然后恢复任务： ```bash docker exec syslog-serve-dm curl -fsS -X POST \ 'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks//resume' \ -H 'Content-Type: application/json' \ -d '{"configVersion":}' ``` ## 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. 微步原始查询诊断 诊断接口复用任务中的设备地址、凭据、TLS 和超时配置，只把请求 JSON 原样发送给微步。 它不会写入 WAL/Kafka，不会推进 checkpoint，也不会在响应中返回 API Key、Secret 或签名 URL。 查询最近 5 秒，单次最多请求 50000 条： ```bash TIME_TO=$(date +%s) TIME_FROM=$((TIME_TO - 5)) docker exec syslog-serve-dm curl -fsS -X POST \ 'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/21/diagnostics/weibu-query' \ -H 'Content-Type: application/json' \ -d "{\"time_from\":${TIME_FROM},\"time_to\":${TIME_TO},\"sql\":\"\",\"assets_group\":[],\"columns\":[],\"size\":50000}" ``` 请求体不会限制微步字段，因此可以试验现场版本的页码和页大小字段。例如： ```bash docker exec syslog-serve-dm curl -fsS -X POST \ 'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks/21/diagnostics/weibu-query' \ -H 'Content-Type: application/json' \ -d "{\"time_from\":${TIME_FROM},\"time_to\":${TIME_TO},\"sql\":\"\",\"assets_group\":[],\"columns\":[],\"page\":2,\"pageSize\":100,\"size\":100}" ``` 微步当前文档只明确描述了查询条件，现场已有脚本确认 `size` 可用，但未确认真正的页码字段。 诊断接口会原样传递 `page`、`pageSize`、`cur_page`、`page_size` 等字段；应通过不同页返回的 `response.data.data` 和 `response.data.total` 判断设备是否接受，不能仅凭 HTTP 200 认定分页生效。 ## 5. 验收 ```bash docker exec syslog-serve-dm curl -fsS \ 'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks//runtime' docker exec syslog-serve-dm curl -fsS \ 'http://127.0.0.1:8189/syslogserve/api/api-pull-tasks//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` 设备不受影响。 ## 6. 缓存清理 ```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`。 ## 7. 快速回退 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。