safesight/docs/deployment.md

# Edge 设备部署指南

> **本文件是 Edge 设备的唯一操作手册。** 现场部署时配合 `docs/客户现场部署检查表.md` 逐项打勾。
> 仓库导航/版本机制说明见 `docs/README.md`，管理端部署见 `docs/control-deployment.md`。
>
> **推荐流程（新项目）**：`产品镜像批量生产`（第 2 章）——16G 母卡制作产品镜像 → Etcher 批量烧录 → 每台脚本初始化。
> 旧版"克隆卡"方式不再使用。
>
> **仅部署 1~2 台**：可跳过镜像，直接在设备上执行 `deploy.sh install` 后用第 3 章启用断电保护。

---

## 1. 涉及的工具与脚本

| 脚本（安装于 `/opt/safesight-edge-server/scripts/`） | 作用 | 在哪个阶段使用 |
|---|---|---|
| `install_deps.sh` | 安装运行环境（MPP / RKNN / ffmpeg-rockchip） | 母卡制作 |
| `package-offline.sh` | 编译并打包离线部署包 | 母卡制作 |
| `deploy.sh` | 安装/升级 safesight 程序与服务 | 母卡制作 |
| `setup-overlayroot.sh` | 断电保护：建 /data 分区 + overlayroot | 母卡制作 / 每台初始化 |
| `prepare-image.sh` | 出厂化清理（打镜像前必跑） | 母卡制作 |
| `init-device.sh` | 每台初始化（IP/主机名/扩 /data/启用保护） | 批量烧录后每台 |
| `ops.sh` | 运维（状态/日志/断电保护切换） | 日常 |

---

## 2. 产品镜像批量生产（推荐主流程）

> **核心思路：用一张 16G 小卡做母卡，镜像体积 = 官方镜像级别**（gzip 后约 1~2GB）。
> 镜像结构上仍是标准整卡镜像（官方也是）：分区表 + U-Boot + 分区内容。它小的原因是**母卡容量小**，
> 而不是特殊打包。烧到 64G 产品卡后，`/data` 分区由 init-device.sh 首次启动时自动 growpart 扩满整卡，
> 存储不浪费。未使用空间是零块，gzip 压缩后几乎不占体积，Etcher 直接支持 `.img.gz`。

### 阶段一：母卡制作（16G 开发卡，插在 Orange Pi 上）

1. Etcher 烧录官方镜像（如 `Orangepi5_1.2.2_ubuntu_jammy_server_linux5.10.160.img`）→ **16G SD 卡**，启动。
2. 安装运行环境：`sudo bash scripts/install_deps.sh`（MPP / RKNN / ffmpeg-rockchip）。
3. 编译并打离线包：`bash scripts/build.sh -m -j4 && bash scripts/package-offline.sh`。
4. 部署并验证：`sudo AGENT_TOKEN=<主钥匙> ./deploy.sh install`；导入模型/人脸库/RTSP，验证推流与算法。
5. 创建 /data 分区与 fstab（出厂带断电保护能力，但**不启用保护**）：

```bash
sudo /opt/safesight-edge-server/scripts/setup-overlayroot.sh install --yes   # 建 /data 分区 + fstab + 装 overlayroot
sudo /opt/safesight-edge-server/scripts/setup-overlayroot.sh disable         # 保持可写！镜像出厂不启用保护
```

> `install` 会创建 /data 分区、写入 fstab、安装 overlayroot 但**不重启**（当前会话仍可写）；
> 随后 `disable` 把 overlayroot 置空，保证出厂镜像首次启动处于可写状态，
> 机器 ID 才能固化、init-device.sh 才能改配置。

6. **出厂化清理**（关键，否则每台设备身份相同）：

```bash
sudo /opt/safesight-edge-server/scripts/prepare-image.sh
sudo poweroff   # 确保文件系统一致后摘卡
```

> `prepare-image.sh` 清除 machine-id / SSH 密钥 / device_id / hostname / 全部日志与告警数据，保留程序、依赖、`/data` 分区与 fstab。
> 若脚本提示"overlayroot 已启用"，说明第 5 步的 `disable` 未生效，先补跑再执行。

### 阶段二：生成镜像文件（Windows / Linux 主机）

```bash
# Linux（推荐，边读边压缩，16G 卡约 2~4 分钟）:
sudo dd if=/dev/sdX bs=4M status=progress conv=fsync | gzip > safesight-product-$(date +%Y%m%d).img.gz
# Windows: 用 Win32DiskImager "读取"生成 .img（16G 卡很快），再用 7-Zip 转 .gz
```

> 为什么还是整卡 dd？香橙派 U-Boot 引导写在 SD 卡非文件系统区域，分区级打包会丢引导、无法启动；
> 官方镜像同样如此。只是**源卡用 16G**，镜像就是官方那种体积，不再有 64G 整卡 dump 的问题。
> （若坚持从 64G 卡做小镜像：Linux 上用 `bmaptool` 只复制已使用块，效果相同且更慢，不推荐。）

### 阶段三：批量烧录

- 用 Balena Etcher 批量烧录 `.img.gz` 到 **64G 产品卡**（写入 + 自动校验）。
- 每台烧录后**首次启动会自动生成唯一** machine-id / SSH 主机密钥 / device_id，互不冲突。

### 阶段四：每台初始化

```bash
# 设备上电后（首次为 DHCP，用 IP 扫描找到设备后 SSH 登录）
sudo /opt/safesight-edge-server/scripts/init-device.sh \
    --hostname safesight-01 --ip 10.0.0.83/24 --gw 10.0.0.1 --dns 10.0.0.1
sudo reboot
```

脚本自动完成：主机名 → 静态 IP(netplan) → 身份验证 → **/data 自动扩容到整卡剩余空间**
（growpart + resize2fs，64G 卡 /data ≈ 55G）→ 服务验证 → **启用断电保护** → 提示重启。
可选参数：`--hls-ram`（HLS 放内存）、`--dhcp`（保持 DHCP）、`--no-overlay`、`--token <主钥匙>`（轮换 token）。

### 阶段五：验收

```bash
sudo /opt/safesight-edge-server/scripts/setup-overlayroot.sh verify   # 断电保护验证（全部 ✓）
df -h /data                                                           # 应为 ~55G
systemctl status safesight-edge-server safesight-edge-agent           # 服务正常
# 管理端：发现设备 → 设置别名 → 导入摄像头/模型 → 下发配置 → 验证推流与算法
```

### 为什么出厂镜像不启用 overlayroot？

- overlayroot 启用后根分区只读，`/etc/machine-id` 无法在首次启动时固化（tmpfs 重启即丢）→ 每次重启设备 ID 漂移，管理端会不断看到"新设备"。
- 每台改 IP/主机名也需先进维护模式，批量初始化多一次重启。
- 因此：**镜像保持可写出厂状态，overlayroot 由 init-device.sh 在每台初始化最后统一启用**，每台只重启一次即进入保护。

---

## 3. 断电保护（overlayroot + /data 分区）参考

> 解决 SD 卡断电重启导致根文件系统损坏、无法启动的问题。
> **启用后根分区只读，修改系统配置需先进入维护模式。**

### 原理

- 用 Ubuntu 官方 `overlayroot` 把根文件系统置于 tmpfs overlay 之上：根分区永久只读，一切写入进入内存，重启即丢，**断电不再损坏根分区**。
- 在 SD 卡剩余空间划分独立读写分区 `/data`（ext4），保存日志、告警图片/视频、设备 ID 等必须持久化的数据。
- `safesight` 的运行目录（`/var/lib/safesight-edge-server/*`、`/var/lib/safesight-edge-agent`）通过 fstab bind 挂载到 `/data`，**路径不变**，现有部署脚本零改动。

### 单台启用（未走镜像流程时）

```bash
sudo /opt/safesight-edge-server/scripts/setup-overlayroot.sh install
sudo reboot
sudo /opt/safesight-edge-server/scripts/setup-overlayroot.sh verify   # 全部 ✓ 即为生效
```

脚本自动完成：检测空闲空间建 /data（ext4）→ 写 fstab（/data + bind，均 `nofail`）→ 迁移存量数据
→ journald 内存日志（64M 上限）→ 安装并配置 overlayroot → 重建 initramfs。

### 可选参数

| 参数 | 说明 |
|---|---|
| `--yes` | 跳过分区确认（无人值守） |
| `--hls-ram` | HLS 分片放内存 tmpfs（512M），减小 SD 卡写入；重启后直播画面需重新拉流 |
| `--journal-data` | 系统日志持久化到 /data（默认放内存，重启即丢） |

### 日常维护（临时进入可写模式）

> 香橙派使用 U-Boot + extlinux 引导，**没有 GRUB**，不要在引导菜单改内核参数。用脚本一键切换：

```bash
# 进入维护模式（装软件/改系统配置）
sudo /opt/safesight-edge-server/scripts/setup-overlayroot.sh disable
sudo reboot

# 维护完成，恢复保护
sudo /opt/safesight-edge-server/scripts/setup-overlayroot.sh enable
sudo reboot
```

或使用运维脚本：`sudo /opt/safesight-edge-server/scripts/ops.sh overlay-disable` / `overlay-enable`。

### 查看状态

```bash
sudo /opt/safesight-edge-server/scripts/ops.sh overlay-status
# 或
sudo /opt/safesight-edge-server/scripts/setup-overlayroot.sh status
```

### 重要注意事项

- **启用前**确认：静态 IP、主机名、SSH 密钥、设备 ID 均已配置完成（启用后根分区只读，改动需维护模式）。
- **维护模式期间**断电仍有损坏风险，维护完成后务必 `enable` 恢复保护。
- HLS 分片写入量较大（与码率、路数、保留天数相关），默认落 `/data`；若 SD 写入寿命紧张可加 `--hls-ram`。
- 若 SD 卡无剩余空间（根分区已占满），需重新烧录含 `/data` 分区的母卡镜像后再执行本方案。

---

## 4. 更新部署（软件升级）

### 4.1 单台升级（目标设备可访问 git）

```bash
cd ~/apps/safesight-edge
git pull
bash scripts/build.sh -m -j4
cd agent && go build -o safesight-edge-agent ./cmd/safesight-agent && cd ..
sudo ./scripts/deploy.sh upgrade
```

### 4.2 离线升级包（无 git 环境）

在开发机（已安装 safesight-edge 源码和编译环境）上：

```bash
cd ~/apps/safesight-edge
git pull && bash scripts/package-offline.sh
```

将生成的包传到目标设备：

```bash
scp safesight-upgrade-*.tar.gz orangepi@<目标IP>:/tmp/
```

在目标设备上（**已启用断电保护的设备需先进入维护模式**）：

```bash
# 已启用断电保护的设备：
sudo /opt/safesight-edge-server/scripts/setup-overlayroot.sh disable && sudo reboot

# 升级：
cd /tmp && tar -xzf safesight-upgrade-*.tar.gz
cd safesight-upgrade-*
sudo AGENT_TOKEN=<管理端token> ./deploy.sh install   # 或 ./deploy.sh upgrade 保留配置

# 恢复保护：
sudo /opt/safesight-edge-server/scripts/setup-overlayroot.sh enable && sudo reboot
```

### 4.3 升级产品镜像（批量设备升级）

重新走第 2 章：母卡 `git pull` → 编译 → `deploy.sh upgrade` → `prepare-image.sh` → 打镜像 → 批量烧录 → 每台初始化。

> 提示：程序升级通常不动 `/data`（设备 ID 不丢）；若升级脚本需要改写系统配置，母卡流程已天然覆盖。