153 lines
4.8 KiB
Markdown
153 lines
4.8 KiB
Markdown
# 客户现场调试指南 — 第三方接口联调
|
||
|
||
## 接口清单
|
||
|
||
| 接口 | 地址 | 用途 |
|
||
|------|------|------|
|
||
| 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` 的机器上执行：
|
||
|
||
### 1. Token 接口（注意：POST，不是 GET）
|
||
|
||
```bash
|
||
curl -s -X POST "http://180.51.12.2/api/appsys/sso/httpheader/login/v1?username_=szls" | python3 -m json.tool
|
||
```
|
||
|
||
**预期**：返回 JSON，其中 `responseBody.token` 有值。
|
||
|
||
**异常处理**：
|
||
|
||
| 现象 | 原因 | 对策 |
|
||
|------|------|------|
|
||
| 返回 500 | SSO 服务异常 | 联系客户排查 SSO |
|
||
| 返回 200 但无 token | 字段路径变了 | 检查 JSON 结构，可能需要改 `token_json_path` |
|
||
| 连接拒绝 | IP 不通 / 服务未启动 | 检查网络、确认服务已部署 |
|
||
| 返回 401/403 | 账号权限问题 | `username_=szls` 可能失效，找客户确认 |
|
||
|
||
### 2. 告警推送接口（拿到 token 后）
|
||
|
||
```bash
|
||
TOKEN="从上一步拿到的 token"
|
||
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": []
|
||
}'
|
||
```
|
||
|
||
**预期**：200 OK。
|
||
|
||
### 3. MinIO 存储
|
||
|
||
```bash
|
||
curl -s "http://180.51.12.2:9000"
|
||
```
|
||
|
||
**预期**：返回 MinIO XML 响应（非 404 / 拒绝连接）。
|
||
|
||
---
|
||
|
||
## 第二步：查看 Edge-Server 日志
|
||
|
||
在 Edge 设备上执行：
|
||
|
||
### 查看启动加载的配置
|
||
|
||
```bash
|
||
journalctl -u safesight-edge-server --no-pager | grep -E "ExternalApiAction initialized|HttpAction initialized"
|
||
```
|
||
|
||
**预期输出**：
|
||
|
||
```
|
||
[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
|
||
```
|
||
|
||
> 如果 URL 里的 IP 不是 `180.51.12.2`，说明管理端下发的配置未更新，需要在管理端修改集成服务配置后重新下发。
|
||
|
||
### 实时跟踪告警和第三方调用
|
||
|
||
```bash
|
||
journalctl -u safesight-edge-server -f | grep -E "alarm.*trigger|ExternalApi|token|send|minio"
|
||
```
|
||
|
||
---
|
||
|
||
## 第三步：触发告警，观察完整链路
|
||
|
||
找一个人走到摄像头前触发告警，或使用测试视频源，观察日志输出。
|
||
|
||
### 正常流程
|
||
|
||
```
|
||
[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=...
|
||
```
|
||
|
||
### 异常诊断
|
||
|
||
| 日志 | 含义 | 对策 |
|
||
|------|------|------|
|
||
| 没有 `[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` 的网络 |
|
||
|
||
---
|
||
|
||
## 第四步：验证 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"
|
||
```
|
||
|
||
---
|
||
|
||
## 快速诊断（一条命令）
|
||
|
||
```bash
|
||
journalctl -u safesight-edge-server --no-pager -n 500 | grep -E "ExternalApi|HttpAction|alarm.*trigger|token|send ok|send failed"
|
||
```
|
||
|
||
---
|
||
|
||
## 管理端配置检查
|
||
|
||
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` | 管理端注入集成服务配置 |
|