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（出厂带断电保护能力，但不启用保护）：

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. 出厂化清理（关键，否则每台设备身份相同）：

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 主机）

# 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，互不冲突。

阶段四：每台初始化

# 设备上电后（首次为 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）。

阶段五：验收

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，路径不变，现有部署脚本零改动。

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

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，不要在引导菜单改内核参数。用脚本一键切换：

# 进入维护模式（装软件/改系统配置）
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。

查看状态

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）

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 源码和编译环境）上：

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

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

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

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

# 已启用断电保护的设备：
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 不丢）；若升级脚本需要改写系统配置，母卡流程已天然覆盖。