cleanup-smartcam-data 部署说明

文件结构

cleanup-smartcam-data/
├── README.md
├── assets/
│   └── cleanup-smartcam-data-flow.png
├── bin/
│   └── cleanup-smartcam-data
├── systemd/
│   ├── cleanup-smartcam-data.service
│   ├── cleanup-smartcam-data-resume.timer
│   └── cleanup-smartcam-data.timer
└── scripts/
    ├── install.sh
    └── uninstall.sh

RK3588 安装位置

项目文件	设备安装位置
bin/cleanup-smartcam-data	/usr/local/sbin/cleanup-smartcam-data
systemd/cleanup-smartcam-data.service	/etc/systemd/system/cleanup-smartcam-data.service
systemd/cleanup-smartcam-data.timer	/etc/systemd/system/cleanup-smartcam-data.timer
systemd/cleanup-smartcam-data-resume.timer	/etc/systemd/system/cleanup-smartcam-data-resume.timer

运行状态目录由程序自动创建：

/var/lib/cleanup-smartcam-data/
/run/cleanup-smartcam-data.lock
/userdata/data/.recording-paused-low-disk

环境要求

• smart-cam 容器名：smart-cam
• 数据目录：/userdata/data
• 容器内成功记录：/smart-cam/kafka_sender/processed_files.log
• 强校验回执：/userdata/data/upload_completed_types.json
• scan 强校验回执：/userdata/data/upload_completed_scans.json
• 容器必须通过 --hostname "$(hostname)" 继承宿主机设备编号；config.json 的 device.id 可留空自动使用该主机名，显式填写时必须与主机名一致
• smart_camera 支持读取 /smart-cam/data/.recording-paused-low-disk （与宿主机 /userdata/data/.recording-paused-low-disk 是同一挂载文件）
• 宿主机使用 Docker 和 systemd

安装

将整个目录复制到目标设备，例如：

/home/zhangw/cleanup-smartcam-data

执行：

cd /home/zhangw/cleanup-smartcam-data
sudo ./scripts/install.sh

安装脚本会：

1. 校验清理脚本语法；
2. 安装程序和 systemd unit；
3. 启用 cleanup-smartcam-data.timer；
4. 删除旧名称 userdata-video-cleanup 的安装文件；
5. 不停止或重启 smart-cam Docker。

清理规则

• 开机2分钟后首次检查；
• 之后每60分钟检查一次；
• 每次定时检查都会安全清理已确认上传成功的数据，不以空闲空间阈值作为清理条件；
• 只清理 processed_files.log 与 upload_completed_types.json 同时确认、且超过60分钟的数据；
• 每条回执必须同时满足：当前启用的上传类型全部成功、回执 device_id 等于当前 有效设备号、回执 remote_base 等于当前配置计算出的后台目录；有效设备号优先取 非空 config.json device.id，否则取容器主机名；显式设备号与主机名不一致、旧式无 设备号回执、设备号不一致或目标目录不一致时一律不删除；
• 同时删除同一任务的：

/userdata/data/videos/<base>_annotated.mp4
/userdata/data/videos_raw/<base>_raw.mp4
/userdata/data/annotations/<base>.xml

• 不再自动删除未获得强校验上传回执的零字节、残缺三件套或 .part 残留；这些文件 即使看起来无效，也优先保留供人工审计，避免把上传故障误判为可清理数据；
• 已确认上传的正常清理在删除前会再次要求raw、annotated和XML三者齐全，缺一项整组跳过；
• scan 以一次扫描目录为原子单位；只有全部小图、meta.json 和可选 patrol_plan.json 均通过 SFTP 大小校验、Kafka 消息确认成功，并写入同时包含当前 设备号、远端路径、Kafka topic、图片数和文件数的 /userdata/data/upload_completed_scans.json 强回执后才允许清理；
• upload_processed_scans.log 只是队列索引，旧版只有 scan_id 的记录不能单独证明 上传目标正确，不再触发删除；
• 已强确认的 scan 还必须超过60分钟、meta.json状态为completed且目录内 没有文件被进程打开，随后才会整目录删除；
• 空闲低于3GiB时只创建“禁止录像”标记，立即结束正在生成的录像，并停止产生新的 videos、videos_raw、annotations；持续检测、推理、RTSP/公网直播、scan和 Producer上传均不暂停；
• 禁止录像期间每2分钟检查一次；
• 清理使空闲恢复到5GiB后删除标记并自动允许录像；持续检测一直运行，之后达到 15/25鸟类确认门控即可重新产生三件套，并停止2分钟快速检查；
• 从旧版本升级时，如果发现旧的 capture-paused 状态，程序会先向 smart_camera 发送一次 SIGCONT 并删除旧状态，之后不再使用 SIGSTOP/SIGCONT 控制整个进程；
• 无法读取成功记录时不删除数据。

验证

sudo bash -n /usr/local/sbin/cleanup-smartcam-data

systemctl status cleanup-smartcam-data.timer
systemctl list-timers --all | grep cleanup-smartcam-data

sudo systemctl start cleanup-smartcam-data.service
systemctl status cleanup-smartcam-data.service

journalctl -u cleanup-smartcam-data.service -n 100 --no-pager

确认成功记录与强校验回执均可读：

docker exec smart-cam \
  test -r /smart-cam/kafka_sender/processed_files.log

test -r /userdata/data/upload_processed_scans.log
test -r /userdata/data/upload_completed_types.json

确认 Docker 未重启：

docker inspect smart-cam --format \
  'running={{.State.Running}} restart={{.RestartCount}} started={{.State.StartedAt}}'

查看日志

journalctl -u cleanup-smartcam-data.service -f
docker logs -f -t --tail 200 smart-cam

日志标识：

[DISK_GUARD][INFO]
[DISK_GUARD][WARNING]
[DISK_GUARD][CRITICAL]
[DISK_GUARD][RECOVERED]

升级

在目标设备进入新版目录后重新执行：

cd /home/zhangw/cleanup-smartcam-data
sudo ./scripts/install.sh

卸载

cd /home/zhangw/cleanup-smartcam-data
sudo ./scripts/uninstall.sh

卸载不会自动删除当前的录像禁止标记；如需立即恢复录像，请确认空间充足后删除：

/userdata/data/.recording-paused-low-disk