对象存储冷备(S3 Offload)
适用于 MiBeeNvr v0.14.0 · 特性 issue #874,默认关闭
把合并完成(rolling 合并落盘)后的录像异步上传到 S3 兼容对象存储做冷备/归档:本地录像行为完全不变,上传成功并经远端 HeadObject 校验后,可选择逐出本地副本释放磁盘。适合:
- 家用宽带/NAS 磁盘有限,想把冷数据归档到便宜的对象存储(Cloudflare R2、B2 无出口流量费)
- 异地容灾——机器被偷/硬盘损坏后录像仍在云端
- 云端对象直接接入支持 S3 协议的回放/取证工具链(保留期交给 bucket lifecycle 管理)
支持的目标:AWS S3、MinIO、Cloudflare R2、Backblaze B2、阿里云 OSS、腾讯云 COS 等 S3 兼容存储(已用真实 MinIO 验证)。
工作原理
- 上传对象:rolling 合并产物——合并引擎已生成的按小时合并 MP4 文件(而非 30 秒碎片段)。一条录像 = 一个对象,对象数与请求数可控
- outbox 表持久化上传状态(
pending → uploading → uploaded → evicted,另有终态skipped):崩溃重启后自动重排队,不会丢也不会重复上传(覆盖写幂等) - 最小年龄宽限(默认 15 分钟):合并 debounce 与回填产物落地后才允许上传,绝不传一个还在增长的桶;万一迟到的增长漏网,size-compare 会触发幂等重传
- 上传确认:PUT 后以 HEAD 比对远端对象尺寸,一致才标记
uploaded——截断或假成功永远不会被当作已确认 - backlog 上限告警(默认 5000 行):上游带宽跟不上产能时停止入队并告警,而不是无限排队
- 上传使用进程级 I/O 预算(租户
offload),与录像/回放/合并共享调度,不挤占前台 - 远端对象永不删除——本地逐出前逐对象 Head 复核;远端清理交给 bucket lifecycle 策略
对象键布局:<prefix>/<camera>/<date>/<id>.<ext>(默认前缀 recordings)。
开启方式
配置文件 mibee-nvr.yaml 的 storage.remote 块(默认整体关闭):
storage:
remote:
enabled: true
endpoint_url: https://s3.example.com # 必填;AWS 填区域端点
region: auto # R2 用 auto;MinIO 可留默认
bucket: my-nvr-archive # 必填
path_style: true # MinIO/自建必须 true;AWS 虚拟主机桶设 false
access_key_id: ${S3_ACCESS_KEY} # 支持 ${VAR} 环境变量引用
secret_access_key: ${S3_SECRET_KEY} # 自动加密存储;绝不明文回写
prefix: recordings
upload:
max_concurrency: 1 # 家用上行是瓶颈,默认 1(上限 8)
scan_interval_s: 60 # 发现扫描周期(上限 3600)
min_age_s: 900 # 合并完成最小年龄(60–86400)
backlog_limit: 5000 # 待上传行数上限(0 = 不限)
evict:
after_days: 0 # 0 = 只上传不逐出(默认);30 = 上传确认 30 天后自动逐出
playback:
presigned: false # 302 直连回放(见「远端录像回放」)
endpoint_url: "" # 签名所用的浏览器可达端点覆写
ttl_s: 3600 # 签名 URL 有效期(秒)
改完用 mibee-nvr validate-config 校验,重启服务生效。Web 界面(设置 → 存储)提供同样的字段,并显示实时队列状态。
凭据与安全:
access_key_id/secret_access_key支持${VAR}环境变量引用——展开发生在客户端构造时,配置文件里只存引用,从 Web 设置页保存也不会把明文写回 YAMLsecret_access_key属于自动加密字段集:设置了NVR_ENCRYPTION_KEY(或NVR_ENCRYPTION_KEY_FILE)时落盘前自动加密,encrypt-config一致处理;${VAR}引用原样保留、不加密- 未设置的
${VAR}展开为空字符串,会在启动校验时报"凭证为空"——错误配置响亮失败而非带病运行
按相机路由
把指定相机路由到不同的桶和/或键前缀(与按相机存储根目录同语义):
storage:
remote:
camera_overrides:
front-door: { bucket: important-bucket, prefix: yard }
back-yard: { prefix: outdoor }
outbox 行在入队时钉死对象所在桶——之后的配置改动不会移动已上传的对象。指向未知相机的覆写会在校验时报错。
逐出本地副本
仅上传永远不会删除本地文件。上传确认后释放空间有两种方式:
- 自动——设置
evict.after_days: 30,后台周期清扫在上传确认满 30 天后删除本地副本;复用与 CLI 相同的逐出路径,每次删除前都经HeadObject复核,复核失败即拒绝逐出、保留本地文件 - 手动 CLI——默认 dry-run,先看报告再执行:
# 队列状态:pending/uploading/uploaded/evicted 计数与最老待传年龄
mibee-nvr offload status
# 逐出报告(dry-run,不动任何文件)
mibee-nvr offload evict --all-uploaded
# 只处理一路相机
mibee-nvr offload evict --camera front-door
# 确认无误后执行:每个对象先 HeadObject 复核远端存在,再删本地
mibee-nvr offload evict --all-uploaded --execute
- 逐出只删本地文件,远端对象永不删除;回滚冷备只需重新下载对象
- 可对运行中的服务执行(WAL 读并发安全);大批量建议在低峰执行
- 逐出前务必确认 bucket 的 lifecycle 策略不会过早删除对象
远端录像回放
被逐出的录像在 Web 界面仍然可见:录像页的"云端归档"区块按日期列出,可内联播放与下载。
- 默认(代理):回放经 NVR 提供(
GET /api/offload/objects/{id},支持 HTTP Range)。代理对浏览器拖动进度条产生的大量小范围请求做范围合并——按块对齐抓取 + 小型 LRU 缓存——不会打爆对象存储 - Presigned 直连(
playback.presigned: true):回放端点改为 302 到短时效签名 URL,视频字节从存储直达浏览器,NVR 零中转。仅在浏览器能访问存储端点时开启——若 NVR 通过 Docker 内网名访问 MinIO,请用playback.endpoint_url填浏览器可达地址。签名失败会静默回退代理
观测
除 mibee-nvr offload status 外,同样的计数以 Prometheus 指标暴露:nvr_offload_outbox_rows{status}(积压 = pending + uploading)与 nvr_offload_uploaded_bytes_total;/api/offload/status 供设置页使用。
与清理/保留期的关系
cleanup(本地保留期)照常运行——它只管本地文件;上传与否不影响本地清理决策- 需要冷数据长期保留时:本地
retention_days保持短周期(如 7 天),远端交给 bucket lifecycle(如 365 天) - 磁盘水位(
disk_threshold_percent)触发的紧急清理同样不区分是否已上传——想"已上传就先不删"请启用evict.after_days,或用逐出 CLI 主动腾空间
常见问题
| 问题 | 答案 |
|---|---|
| 上传会不会抢录像的磁盘 IO? | 不会——offload 是共享 I/O 预算的租户之一,与录像/回放/合并统一调度 |
| 上传一半崩溃了怎么办? | outbox 行停在 uploading,重启后自动重排队幂等覆盖 |
| 为什么某条录像一直不上传? | 看年龄是否小于 min_age_s(默认 15 分钟);再看 backlog 是否触顶告警 |
| 上行带宽跟不上录制怎么办? | 积压增长到 backlog_limit 后停止入队并告警(本地保留策略照常,数据不丢);可以调大上限、接受延迟,或减少录制内容 |
| 能否完全上云(不落本地盘)? | 不能,这是有意的设计——崩溃一致性、合并与回放都将依赖上行带宽;本地优先 + 异步上传是受支持的模型 |
| Web 界面能配置吗? | 设置页(设置 → 存储)可改字段并显示实时队列状态;逐出走 evict.after_days 或 CLI |
| R2 怎么配? | endpoint_url: https://<account>.r2.cloudflarestorage.com、region: auto、path_style: true |
| 付费存储成本如何? | 主要成本是出口流量与请求数——代理的范围合并、以及上传合并段而非碎片段,都是为了压低请求数 |