From 805814fcdfd86e6a66502425f3851aeecd5885e6 Mon Sep 17 00:00:00 2001 From: tian <11429339@qq.com> Date: Wed, 29 Jul 2026 21:52:10 +0800 Subject: [PATCH] docs: simplify debug guide, clean multi-line commands --- docs/debug-third-party-api.md | 124 +++++++++++++--------------------- 1 file changed, 47 insertions(+), 77 deletions(-) diff --git a/docs/debug-third-party-api.md b/docs/debug-third-party-api.md index 100edad..164fddf 100644 --- a/docs/debug-third-party-api.md +++ b/docs/debug-third-party-api.md @@ -2,53 +2,40 @@ ## 接口清单 -| 接口 | 地址 | 用途 | -|------|------|------| -| Token | `POST http://180.51.12.2/api/appsys/sso/httpheader/login/v1?username_=szls` | 获取认证令牌 | -| 告警推送 | `POST http://180.51.12.2/api/edge/edgecallmanages/vi-alarm/v1` | 推送告警消息 | -| MinIO | `http://180.51.12.2:9000` | 告警截图/视频存储 | +| 接口 | 地址 | +|------|------| +| Token | `POST http://180.51.12.2/api/appsys/sso/httpheader/login/v1?username_=szls` | +| 告警推送 | `POST http://180.51.12.2/api/edge/edgecallmanages/vi-alarm/v1` | +| MinIO | `http://180.51.12.2:9000` | --- ## 第一步：确认三个接口可达 -在能访问 `180.51.12.2` 的机器上执行： +在能访问 `180.51.12.2` 的机器上执行。 -### 1. Token 接口（注意：POST，不是 GET） +### 1. Token 接口 ```bash -curl -s -X POST "http://180.51.12.2/api/appsys/sso/httpheader/login/v1?username_=szls" | python3 -m json.tool +curl -s -X POST \ + "http://180.51.12.2/api/appsys/sso/httpheader/login/v1?username_=szls" ``` -**预期**：返回 JSON，其中 `responseBody.token` 有值。 +预期返回 JSON，`responseBody.token` 有值。 -**异常处理**： +### 2. 告警推送接口 -| 现象 | 原因 | 对策 | -|------|------|------| -| 返回 500 | SSO 服务异常 | 联系客户排查 SSO | -| 返回 200 但无 token | 字段路径变了 | 检查 JSON 结构，可能需要改 `token_json_path` | -| 连接拒绝 | IP 不通 / 服务未启动 | 检查网络、确认服务已部署 | -| 返回 401/403 | 账号权限问题 | `username_=szls` 可能失效，找客户确认 | - -### 2. 告警推送接口（拿到 token 后） +把上一步拿到的 token 替换 `TOKEN_VALUE`： ```bash -TOKEN="从上一步拿到的 token" -curl -s -X POST "http://180.51.12.2/api/edge/edgecallmanages/vi-alarm/v1" \ +curl -s -X POST \ + "http://180.51.12.2/api/edge/edgecallmanages/vi-alarm/v1" \ -H "Content-Type: application/json" \ - -H "X-Access-Token: $TOKEN" \ - -d '{ - "tenantCode": "32", - "channelNo": "test", - "alarmContent": "test", - "alarmTime": "2026-01-01 00:00:00", - "picInfo": [], - "videoInfo": [] - }' + -H "X-Access-Token: TOKEN_VALUE" \ + -d '{"tenantCode":"32","channelNo":"test","alarmContent":"test","alarmTime":"2026-01-01 00:00:00","picInfo":[],"videoInfo":[]}' ``` -**预期**：200 OK。 +预期返回 200。 ### 3. MinIO 存储 @@ -56,80 +43,74 @@ curl -s -X POST "http://180.51.12.2/api/edge/edgecallmanages/vi-alarm/v1" \ curl -s "http://180.51.12.2:9000" ``` -**预期**：返回 MinIO XML 响应（非 404 / 拒绝连接）。 +预期返回 MinIO XML 响应。 --- ## 第二步：查看 Edge-Server 日志 -在 Edge 设备上执行： +在 Edge 设备上执行。 -### 查看启动加载的配置 +### 查看启动时加载的第三方地址 ```bash -journalctl -u safesight-edge-server --no-pager | grep -E "ExternalApiAction initialized|HttpAction initialized" +journalctl -u safesight-edge-server --no-pager \ + | grep -E "ExternalApiAction initialized|HttpAction initialized" ``` -**预期输出**： +预期看到 `token_url=http://180.51.12.2/...` 和 `msg_url=http://180.51.12.2/...`。 -``` -[ExternalApiAction] initialized, token_url=http://180.51.12.2/... msg_url=http://180.51.12.2/... -[HttpAction] initialized, url=http://127.0.0.1:9100/v1/alarms/report, method=POST -``` +如果 IP 不是 `180.51.12.2`，说明管理端下发的配置未更新。 -> 如果 URL 里的 IP 不是 `180.51.12.2`，说明管理端下发的配置未更新，需要在管理端修改集成服务配置后重新下发。 - -### 实时跟踪告警和第三方调用 +### 实时跟踪告警和接口调用 ```bash -journalctl -u safesight-edge-server -f | grep -E "alarm.*trigger|ExternalApi|token|send|minio" +journalctl -u safesight-edge-server -f \ + | grep -E "alarm.*trigger|ExternalApi|token|send ok|send failed" ``` --- ## 第三步：触发告警，观察完整链路 -找一个人走到摄像头前触发告警，或使用测试视频源，观察日志输出。 +找人走到摄像头前触发告警，观察日志。 -### 正常流程 +正常流程： ``` [alarm] trigger event_id=xxx rule=unknown_face [ExternalApiAction] token fetched successfully -[ExternalApiAction] send ok http=200 event_id=xxx alarm_content=unknown_face pic_url=... video_url=... +[ExternalApiAction] send ok http=200 event_id=xxx ``` -### 异常诊断 +异常对照： -| 日志 | 含义 | 对策 | -|------|------|------| -| 没有 `[alarm] trigger` | 告警未触发 | 检查阈值是否过高、摄像头是否在线、RTSP 是否正常 | -| `token fetched successfully` 不出现 | token 获取失败 | 回到第一步验证 token 接口 | -| `send failed http=401` | token 过期或被拒 | 检查 token 有效期、SSO 账号权限 | -| `send failed http=403` | 无推送权限 | 联系客户开通推送权限 | -| `send failed http=500` | 第三方推送接口内部错误 | 第三方问题，找客户排查他们日志 | -| `send ok http=200` 但客户说没收到 | 第三方内部处理失败 | 客户查他们自己的系统日志 | -| 日志里完全没有 `ExternalApiAction` | 配置未启用 external_api | 检查管理端「集成服务」配置 | -| `minio upload failed` | 截图/视频上传失败 | 检查 MinIO 凭据、bucket 是否存在 | -| `curl_easy_perform` 错误 | 网络不通 | 检查 Edge 设备到 `180.51.12.2` 的网络 | +| 日志 | 对策 | +|------|------| +| 没有 `[alarm] trigger` | 检查阈值、摄像头、RTSP | +| 无 `token fetched successfully` | 回到第一步验证 token 接口 | +| `send failed http=401` | token 过期，检查 SSO 账号 | +| `send failed http=500` | 第三方内部错误，找客户排查 | +| 日志里完全没有 `ExternalApiAction` | 管理端集成服务未启用 external_api | +| `minio upload failed` | 检查 MinIO 凭据和 bucket | +| `curl_easy_perform` 错误 | Edge 到 180.51.12.2 网络不通 | --- ## 第四步：验证 Agent 本地告警 -Edge-Server 同时会推送告警到本地 Agent（`127.0.0.1:9100`），Agent 再上报管理端。 - ```bash -# 查看 Agent 是否收到告警 -journalctl -u safesight-edge-agent --no-pager -n 200 | grep -i "alarm\|report" +journalctl -u safesight-edge-agent --no-pager -n 200 \ + | grep -i "alarm\|report" ``` --- -## 快速诊断（一条命令） +## 快速诊断 ```bash -journalctl -u safesight-edge-server --no-pager -n 500 | grep -E "ExternalApi|HttpAction|alarm.*trigger|token|send ok|send failed" +journalctl -u safesight-edge-server --no-pager -n 500 \ + | grep -E "ExternalApi|HttpAction|alarm.*trigger|token|send ok|send failed" ``` --- @@ -137,16 +118,5 @@ journalctl -u safesight-edge-server --no-pager -n 500 | grep -E "ExternalApi|Htt ## 管理端配置检查 1. 登录管理端 → 资产管理 → 第三方服务 -2. 确认告警服务和对象存储的地址为 `180.51.12.2` -3. 如有修改，保存后在「运行看板」中对设备重新下发配置 - ---- - -## 相关代码 - -| 文件 | 说明 | -|------|------| -| `plugins/alarm/actions/external_api_action.cpp` | Token 获取 + 告警推送逻辑 | -| `plugins/alarm/actions/http_action.cpp` | 本地 Agent 推送逻辑 | -| `plugins/alarm/alarm_node.cpp` | 告警触发和 action 调度 | -| `internal/service/auto_config.go` | 管理端注入集成服务配置 | +2. 确认告警服务和对象存储地址为 `180.51.12.2` +3. 如有修改，保存后重新下发设备配置