From 78427b2e33bae3845c23a97c1be6b341305fa3fd Mon Sep 17 00:00:00 2001
From: master <727475183@qq.com>
Date: Fri, 8 May 2026 17:12:36 +0800
Subject: [PATCH] docs: add deployment guide for edge agent

- Prerequisites (hardware, software, versions)
- Step-by-step deployment instructions
- Configuration examples
- Troubleshooting table
- OTA update workflow
---
 DEPLOYMENT.md | 199 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 199 insertions(+)
 create mode 100644 DEPLOYMENT.md

diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
new file mode 100644
index 0000000..647b163
--- /dev/null
+++ b/DEPLOYMENT.md
@@ -0,0 +1,199 @@
+# AI-tianyan 边缘部署操作指南
+
+## 前置条件
+
+| 项目 | 要求 |
+|---|---|
+| 硬件 | Atlas 200I DK2 (Ascend 310B4) 或 Ascend 310B4 设备 |
+| OS | Ubuntu 22.04 aarch64 |
+| Go | 1.18+ |
+| Python | 3.9+ |
+| CANN | 6.2.RC2 (Ascend Toolkit) |
+| 云端 | 101.36.73.102 (API/MQTT/InfluxDB/OTA/ZLMediaKit) |
+
+---
+
+## 步骤 1: 拉取代码
+
+```bash
+git clone http://101.36.73.102:3112/fyah/AI-tianyan.git
+cd AI-tianyan
+```
+
+---
+
+## 步骤 2: 转换 YOLO 模型 (.onnx → .om)
+
+```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
+```
+
+---
+
+## 步骤 3: 编译 Go 边缘代理
+
+```bash
+# 设置 Go 代理（国内环境）
+export GOPROXY=https://goproxy.cn,direct
+
+# 构建
+bash scripts/build.sh
+# 或使用 make build
+# 输出: build/edge-agent
+```
+
+---
+
+## 步骤 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
+```
+
+关键配置项:
+
+```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 消息
+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
+```
+
+---
+
+## 步骤 6: 启动服务
+
+### 方式 A: systemd (推荐)
+
+```bash
+# 启动推理服务
+sudo systemctl start edge-infer
+
+# 启动边缘代理
+sudo systemctl start edge-agent
+
+# 设置开机自启
+sudo systemctl enable edge-infer edge-agent
+
+# 查看状态
+sudo systemctl status edge-agent edge-infer
+sudo journalctl -u edge-agent -f
+```
+
+### 方式 B: 手动启动
+
+```bash
+# 启动推理服务
+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' &
+
+# 启动边缘代理
+./build/edge-agent -config config/edge.yaml
+```
+
+### 方式 C: 一键脚本
+
+```bash
+bash start.sh
+```
+
+---
+
+## 步骤 7: 验证运行
+
+```bash
+# 检查进程
+ps aux | grep -E 'edge-agent|infer_server|ffmpeg'
+
+# 检查网络连接
+ss -tunp | grep 101.36.73.102
+
+# 检查 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
+```
+
+---
+
+## 步骤 8: 配置 Telegraf 指标上报 (可选)
+
+```bash
+# Telegraf 已安装 (v1.21.4)
+# 配置文件: /etc/telegraf/telegraf.conf
+# 已配置上报到 InfluxDB (101.36.73.102:18086)
+
+# 重启 Telegraf 使配置生效
+sudo systemctl restart telegraf
+sudo systemctl status telegraf
+```
+
+---
+
+## 常见问题排查
+
+| 问题 | 解决方法 |
+|---|---|
+| `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` |
+
+---
+
+## 更新部署 (OTA)
+
+```bash
+# 云端推送新版本后，edge-agent 自动检测并下载
+# 也可手动更新:
+git pull
+make build
+make install
+sudo systemctl restart edge-agent edge-infer
+```