first commit

README.md

@@ -0,0 +1,152 @@
+# cleanup-smartcam-data 部署说明
+
+![cleanup-smartcam-data 自动清理策略](assets/cleanup-smartcam-data-flow.png)
+
+## 文件结构
+
+```text
+cleanup-smartcam-data/
+├── README.md
+├── assets/
+│   └── cleanup-smartcam-data-flow.png
+├── bin/
+│   └── cleanup-smartcam-data
+├── systemd/
+│   ├── cleanup-smartcam-data.service
+│   └── 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` |
+
+运行状态目录由程序自动创建：
+
+```text
+/var/lib/cleanup-smartcam-data/
+/run/cleanup-smartcam-data.lock
+```
+
+## 环境要求
+
+- smart-cam 容器名：`smart-cam`
+- 数据目录：`/userdata/data`
+- 容器内成功记录：`/smart-cam/kafka_sender/processed_files.log`
+- 采集进程命令包含：`build/bin/smart_camera`
+- 宿主机使用 Docker 和 systemd
+
+## 安装
+
+将整个目录复制到目标设备，例如：
+
+```text
+/home/zhangw/cleanup-smartcam-data
+```
+
+执行：
+
+```bash
+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分钟后首次检查；
+- 之后每5分钟检查一次；
+- `/userdata` 低于15GiB时开始安全清理；
+- 只清理 `processed_files.log` 中确认成功、且超过60分钟的数据；
+- 同时删除同一任务的：
+
+```text
+/userdata/data/videos/<base>_annotated.mp4
+/userdata/data/videos_raw/<base>_raw.mp4
+/userdata/data/annotations/<base>.xml
+```
+
+- 超过60分钟的0字节 raw，如果未被进程占用，也会按上述三件套删除；
+- 低于8GiB时暂停采集，Producer继续上传；
+- 恢复到15GiB后自动恢复采集；
+- 低于5GiB时输出 CRITICAL 告警；
+- 无法读取成功记录时不删除数据。
+
+## 验证
+
+```bash
+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
+```
+
+确认成功记录可读：
+
+```bash
+docker exec smart-cam \
+  test -r /smart-cam/kafka_sender/processed_files.log
+```
+
+确认 Docker 未重启：
+
+```bash
+docker inspect smart-cam --format \
+  'running={{.State.Running}} restart={{.RestartCount}} started={{.State.StartedAt}}'
+```
+
+## 查看日志
+
+```bash
+journalctl -u cleanup-smartcam-data.service -f
+docker logs -f -t --tail 200 smart-cam
+```
+
+日志标识：
+
+```text
+[DISK_GUARD][INFO]
+[DISK_GUARD][WARNING]
+[DISK_GUARD][CRITICAL]
+[DISK_GUARD][RECOVERED]
+```
+
+## 升级
+
+在目标设备进入新版目录后重新执行：
+
+```bash
+cd /home/zhangw/cleanup-smartcam-data
+sudo ./scripts/install.sh
+```
+
+## 卸载
+
+```bash
+cd /home/zhangw/cleanup-smartcam-data
+sudo ./scripts/uninstall.sh
+```
+
+卸载后检查采集是否处于暂停状态，再决定是否删除：
+
+```text
+/var/lib/cleanup-smartcam-data/
+```