fix: 修复6个边缘侧问题 + 单元测试

1. 删除 ConfigAgent (与 MQTT 配置更新重叠且未启用) 2. OTA 完整安装流程: 解压tar.gz -> 校验ELF -> 替换二进制 -> systemctl重启 3. StreamManager stopAll 添加 Wait() 防止僵尸进程 4. InferClient socket 读写添加 timeout 防止永久阻塞 5. Heartbeat 集成 NPU 监控 (npu-smi + fallback 脚本) 6. 配置更新时动态重启 ffmpeg 以应用新 fps
2026-05-08 23:58:08 +08:00
parent 88b2e71a77
commit 97a77d4745
11 changed files with 843 additions and 186 deletions
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -1,197 +1,286 @@
 # AI-tianyan 边缘部署操作指南

-## 前置条件
+## 系统环境

 | 项目 | 要求 |
 |---|---|
-| 硬件 | Atlas 200I DK2 (Ascend 310B4) 或 Ascend 310B4 设备 |
+| 硬件 | Atlas 200I A2 (Ascend 310B4) 或同系列设备 |
 | OS | Ubuntu 22.04 aarch64 |
-| Go | 1.18+ |
-| Python | 3.9+ |
-| CANN | 6.2.RC2 (Ascend Toolkit) |
+| Python | 3.9.x (Miniconda 或系统自带) |
+| CANN | 6.2.RC2 (Ascend Toolkit V100R003C11) |
+| Go | 1.18+ (仅编译时需要) |
 | 云端 | 101.36.73.102 (API/MQTT/InfluxDB/OTA/ZLMediaKit) |

+> 如果目标设备环境完全一致（同镜像版本），可直接复用已编译的 Go 二进制和 .om 模型，无需重新编译。
+
 ---

-## 步骤 1: 拉取代码
+## 部署方式
+
+### 方式一：离线包部署（推荐，最快）
+
+适用于环境一致的设备，所有构建产物已包含在内。
+
+#### 1. 在源设备打包
+
+```bash
+cd /root
+tar czf ai-tianyan.tar.gz --exclude='.git' --exclude='__pycache__' --exclude='*.pyc' AI-tianyan/
+```
+
+#### 2. 传输到目标设备
+
+```bash
+# 网络传输
+scp ai-tianyan.tar.gz root@目标IP:/root/
+
+# 或 U盘拷贝
+```
+
+#### 3. 目标设备上安装
+
+```bash
+# 确保 pip 存在
+python3 -m pip --version || apt update && apt install -y python3-pip
+
+# 解压
+cd /root
+tar xzf ai-tianyan.tar.gz
+cd AI-tianyan
+
+# 一键安装（部署文件 + Python依赖 + systemd服务 + 自动启动）
+bash scripts/install.sh
+```
+
+#### 4. 修改配置
+
+```bash
+# 生成新的设备 UUID
+NEW_UUID=$(cat /proc/sys/kernel/random/uuid | tr -d '-')
+
+# 更新配置
+sudo sed -i "s/device_uuid:.*/device_uuid: $NEW_UUID/" /opt/tianyan-edge/config/edge.yaml
+sudo sed -i "s/edge_id:.*/edge_id: edge-demo-002/" /opt/tianyan-edge/config/edge.yaml
+
+# 如有不同的摄像头流地址
+sudo vi /opt/tianyan-edge/config/edge.yaml
+```
+
+#### 5. 验证
+
+```bash
+sudo systemctl status edge-agent edge-infer
+journalctl -u edge-agent -n 50 --no-pager
+```
+
+---
+
+### 方式二：Git 源码部署
+
+适用于需要自定义代码或环境有差异的设备。
+
+#### 1. 拉取代码

 ```bash
 git clone http://101.36.73.102:3112/fyah/AI-tianyan.git
 cd AI-tianyan
 ```

---
-
-## 步骤 2: 转换 YOLO 模型 (.onnx → .om)
+#### 2. 编译 Go 边缘代理
+
+```bash
+export GOPROXY=https://goproxy.cn,direct
+bash scripts/build.sh
+# 输出: build/edge-agent
+```
+
+#### 3. 转换模型（仅 ATC 版本不同时需要）

 ```bash
-# 在 CANN 环境设备上执行
 source /usr/local/Ascend/ascend-toolkit/set_env.sh
-
-# 执行 ATC 转换
 bash scripts/atc_convert.sh
-
-# 或手动转换
+# 或手动:
 atc --model=yolov8n.onnx \
    --framework=5 \
    --output=model/model.om \
    --soc_version=Ascend310B4 \
    --input_format=NCHW \
-    --input_shape="images:1,3,640,640"
-
-# 复制模型到指定位置
-cp yolov8n.om model/model.om
+    --input_shape="images:1,3,640,640" \
+    --output_type=FP16
 ```

---
-
-## 步骤 3: 编译 Go 边缘代理
+#### 4. 安装部署

 ```bash
-# 设置 Go 代理（国内环境）
-export GOPROXY=https://goproxy.cn,direct
+# 确保 pip 存在
+python3 -m pip --version || apt update && apt install -y python3-pip

-# 构建
-bash scripts/build.sh
-# 或使用 make build
-# 输出: build/edge-agent
-```
+# 安装 Python 依赖
+python3 -m pip install opencv-python-headless numpy

---
-
-## 步骤 4: 安装部署
-
-```bash
 # 一键安装
 bash scripts/install.sh
-# 或 make install
-
-# 安装脚本会:
-# 1. 创建 /opt/tianyan-edge/{bin,python,config,systemd,staging,model}
-# 2. 复制 edge-agent 到 /opt/tianyan-edge/bin/
-# 3. 复制 infer_server.py 到 /opt/tianyan-edge/python/
-# 4. 安装 Python 依赖 (opencv-python-headless, numpy)
-# 5. 安装 systemd 服务文件
-# 6. 启用并启动服务
 ```

 ---

-## 步骤 5: 配置 edge.yaml
+## 安装脚本说明

-```bash
-sudo vi /opt/tianyan-edge/config/edge.yaml
+`scripts/install.sh` 会自动执行以下操作：
+
+```
+1. 创建目录: /opt/tianyan-edge/{bin,python,config,systemd,staging,model}
+2. 复制 edge-agent -> /opt/tianyan-edge/bin/edge-agent
+3. 复制 infer_server.py -> /opt/tianyan-edge/python/
+4. 复制 edge.yaml.template -> /opt/tianyan-edge/config/edge.yaml (仅在不存在时)
+5. 安装 Python 依赖 (opencv-python-headless, numpy)
+6. 安装 systemd 服务文件
+7. daemon-reload + enable + restart 服务
 ```

-关键配置项:
+---
+
+## 配置文件说明
+
+安装后配置位于 `/opt/tianyan-edge/config/edge.yaml`：

 ```yaml
-device_uuid: 8541db9f77826e39605ef2c032f8fb93  # 设备唯一标识
-edge_id: edge-demo-001
-cloud_url: http://101.36.73.102:8004             # 云端 API
-mqtt_broker: tcp://101.36.73.102:1883            # MQTT 消息
+device_uuid: 8541db9f77826e39605ef2c032f8fb93   # 设备唯一标识，每台设备必须不同
+edge_id: edge-demo-001                             # 设备名称，便于识别
+cloud_url: http://101.36.73.102:8004               # 云端 API 地址
+mqtt_broker: tcp://101.36.73.102:1883              # MQTT Broker
+mqtt_user: ""                                      # MQTT 认证用户名
+mqtt_pass: ""                                      # MQTT 认证密码
+edge_token: ""                                     # 设备认证 Token
 rtsp_urls:
-  - http://101.36.73.102:8080/rtp/34020000002000000003_34020000001310000001.live.flv
-infer_socket: /tmp/edge-infer.sock
-infer_fps: 2                                     # 推理帧率
-conf_threshold: 0.2                              # 检测阈值
-ota_url: http://101.36.73.102:8087               # OTA 更新地址
-version: 1.0.0
+  - http://101.36.73.102:8080/rtp/xxx.live.flv     # 视频流地址 (支持多路)
+infer_socket: /tmp/edge-infer.sock                 # Go与Python通信的Unix Socket
+infer_fps: 2                                       # 推理帧率 (每秒抽样数)
+infer_workers: 3                                   # 并发推理 worker 数
+conf_threshold: 0.2                                # 检测置信度阈值
+dedup_window_sec: 30                               # 事件去重窗口 (秒)
+ota_url: http://101.36.73.102:8087                 # OTA 自动更新地址
+version: 1.0.0                                     # 固件版本号
 ```

+> 新设备部署时 **必须修改**: `device_uuid`、`edge_id`、`rtsp_urls`
+
 ---

-## 步骤 6: 启动服务
+## 服务管理

-### 方式 A: systemd (推荐)
+### 启动/停止/重启

 ```bash
-# 启动推理服务
-sudo systemctl start edge-infer
+sudo systemctl start edge-infer          # 启动 NPU 推理服务
+sudo systemctl start edge-agent          # 启动边缘代理
+sudo systemctl stop edge-infer edge-agent
+sudo systemctl restart edge-infer edge-agent
+```

-# 启动边缘代理
-sudo systemctl start edge-agent
+### 开机自启

-# 设置开机自启
+```bash
 sudo systemctl enable edge-infer edge-agent
+```

-# 查看状态
+### 查看状态
+
+```bash
 sudo systemctl status edge-agent edge-infer
-sudo journalctl -u edge-agent -f
+sudo journalctl -u edge-agent -f         # 实时查看边缘代理日志
+sudo journalctl -u edge-infer -f         # 实时查看推理服务日志
 ```

-### 方式 B: 手动启动
+### 手动调试模式

 ```bash
-# 启动推理服务
+# 停止 systemd 服务
+sudo systemctl stop edge-agent edge-infer
+
+# 手动启动推理服务
 bash -lc 'source /usr/local/Ascend/ascend-toolkit/set_env.sh && \
-  NAMES_FILE=/root/AI-tianyan/model/names.txt \
-  CONF_THRESHOLD=0.15 \
-  python3 python/infer_server.py' &
+  NAMES_FILE=/opt/tianyan-edge/model/names.txt \
+  OM_MODEL=/opt/tianyan-edge/model/model.om \
+  CONF_THRESHOLD=0.2 \
+  OUTPUT_FORMAT=raw \
+  python3 /opt/tianyan-edge/python/infer_server.py'

-# 启动边缘代理
-./build/edge-agent -config config/edge.yaml
-```
-
-### 方式 C: 一键脚本
-
-```bash
-bash start.sh
+# 另一个终端启动边缘代理
+/opt/tianyan-edge/bin/edge-agent -config /opt/tianyan-edge/config/edge.yaml
 ```

 ---

-## 步骤 7: 验证运行
+## 运行验证

 ```bash
 # 检查进程
-ps aux | grep -E 'edge-agent|infer_server|ffmpeg'
-
-# 检查网络连接
-ss -tunp | grep 101.36.73.102
+ps aux | grep -E 'edge-agent|infer_server'

 # 检查 NPU 状态
 npu-smi info

-# 检查日志
-sudo journalctl -u edge-agent -n 50
-sudo journalctl -u edge-infer -n 50
-tail -f logs/agent.log logs/infer.log
+# 检查网络连接 (应看到连接到 101.36.73.102)
+ss -tunp | grep 101.36.73.102
+
+# 检查 Unix Socket
+ls -la /tmp/edge-infer.sock
+
+# 检查模型文件
+ls -lh /opt/tianyan-edge/model/model.om /opt/tianyan-edge/model/names.txt
+
+# 查看系统日志
+tail -f /opt/tianyan-edge/logs/agent.log 2>/dev/null
+tail -f /opt/tianyan-edge/logs/infer.log 2>/dev/null
 ```

 ---

-## 步骤 8: 配置 Telegraf 指标上报 (可选)
+## Docker 部署（可选）

 ```bash
-# Telegraf 已安装 (v1.21.4)
-# 配置文件: /etc/telegraf/telegraf.conf
-# 已配置上报到 InfluxDB (101.36.73.102:18086)
-
-# 重启 Telegraf 使配置生效
-sudo systemctl restart telegraf
-sudo systemctl status telegraf
+cd AI-tianyan
+docker compose up -d
+docker compose logs -f tianyan-edge
 ```

+要求：Docker 已安装，CANN 驱动已就绪，NPU 设备节点 `/dev/davinci0` 等存在。
+
 ---

-## 常见问题排查
+## 常见问题

 | 问题 | 解决方法 |
 |---|---|
-| `acl.init failed` | 确认 `set_env.sh` 已执行，检查 `LD_LIBRARY_PATH` |
-| `model.om not found` | 重新执行 ATC 转换，确认路径正确 |
-| 无法连接 MQTT | 检查 `mqtt_broker` 地址和 `edge_token` |
-| 拉流失败 | 确认 ZLMediaKit 端口 8080 可达 |
-| 编译失败 | `GOPROXY=https://goproxy.cn,direct go mod download` |
+| `acl.init failed` | 确认 `source set_env.sh` 已执行，检查 `LD_LIBRARY_PATH` 包含 CANN 路径 |
+| `model.om not found` | 确认 `/opt/tianyan-edge/model/model.om` 存在，重新执行 ATC 转换 |
+| `python3 -m pip: command not found` | `apt install -y python3-pip` |
+| `opencv-python-headless 安装失败` | `apt install -y python3-dev gcc g++ libgl1-mesa-glx` 后再 pip install |
+| 无法连接 MQTT | 检查 `mqtt_broker` 地址是否正确，确认网络可达 |
+| 拉流失败 | 确认 ZLMediaKit 端口 8080 可达，流地址正确 |
+| Go 编译失败 | `export GOPROXY=https://goproxy.cn,direct && go mod download` |
+| systemd 启动后立即退出 | `journalctl -u edge-agent -n 100` 查看详细错误 |
+| 多设备 UUID 冲突 | 每台设备必须有不同的 `device_uuid`，用 `cat /proc/sys/kernel/random/uuid` 生成 |

 ---

-## 更新部署 (OTA)
+## 卸载

 ```bash
-# 云端推送新版本后，edge-agent 自动检测并下载
-# 也可手动更新:
+bash scripts/uninstall.sh
+# 或 make uninstall
+```
+
+---
+
+## OTA 远程更新
+
+云端推送新版本后，edge-agent 会自动检测并下载更新到 staging 目录。
+也可手动更新：
+
+```bash
+cd /root/AI-tianyan
 git pull
 make build
 make install