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. 在源设备打包

```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. 编译 Go 边缘代理

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

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

```bash
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. 安装部署

```bash
# 确保 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`：

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

---

## 服务管理

### 启动/停止/重启

```bash
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
```

### 开机自启

```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-infer -f         # 实时查看推理服务日志
```

### 手动调试模式

```bash
# 停止 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
```

---

## 运行验证

```bash
# 检查进程
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 部署（可选）

```bash
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
bash scripts/uninstall.sh
# 或 make uninstall
```

---

## OTA 远程更新

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

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