AI-tianyan/DEPLOYMENT.md

AI-tianyan 边缘部署操作指南

系统环境

项目	要求
硬件	Atlas 200I A2 (Ascend 310B4) 或同系列设备
OS	Ubuntu 22.04 aarch64
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. 在源设备打包

cd /root
tar czf ai-tianyan.tar.gz --exclude='.git' --exclude='__pycache__' --exclude='*.pyc' AI-tianyan/

2. 传输到目标设备

# 网络传输
scp ai-tianyan.tar.gz root@目标IP:/root/

# 或 U盘拷贝

3. 目标设备上安装

# 确保 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. 修改配置

# 生成新的设备 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. 验证

sudo systemctl status edge-agent edge-infer
journalctl -u edge-agent -n 50 --no-pager

---

方式二：Git 源码部署

适用于需要自定义代码或环境有差异的设备。

1. 拉取代码

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

2. 编译 Go 边缘代理

export GOPROXY=https://goproxy.cn,direct
bash scripts/build.sh
# 输出: build/edge-agent

3. 转换模型（仅 ATC 版本不同时需要）

source /usr/local/Ascend/ascend-toolkit/set_env.sh
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" \
    --output_type=FP16

4. 安装部署

# 确保 pip 存在
python3 -m pip --version || apt update && apt install -y python3-pip

# 安装 Python 依赖
python3 -m pip install opencv-python-headless numpy

# 一键安装
bash scripts/install.sh

---

安装脚本说明

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：

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/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

---

服务管理

启动/停止/重启

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 enable edge-infer edge-agent

查看状态

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

手动调试模式

# 停止 systemd 服务
sudo systemctl stop edge-agent edge-infer

# 手动启动推理服务
bash -lc 'source /usr/local/Ascend/ascend-toolkit/set_env.sh && \
  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'

# 另一个终端启动边缘代理
/opt/tianyan-edge/bin/edge-agent -config /opt/tianyan-edge/config/edge.yaml

---

运行验证

# 检查进程
ps aux | grep -E 'edge-agent|infer_server'

# 检查 NPU 状态
npu-smi info

# 检查网络连接 (应看到连接到 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

---

Docker 部署（可选）

cd AI-tianyan
docker compose up -d
docker compose logs -f tianyan-edge

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

---

常见问题

问题	解决方法
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 生成

---

卸载

bash scripts/uninstall.sh
# 或 make uninstall

---

OTA 远程更新

云端推送新版本后，edge-agent 会自动检测并下载更新到 staging 目录。 也可手动更新：

cd /root/AI-tianyan
git pull
make build
make install
sudo systemctl restart edge-agent edge-infer