Skip to main content

Cloud Storage Retention

云存档位​

PlanHistoryAccess Window
LocalNo cloud historyN/A
Starter (Daily Backup)24-hour cloud historycloudPlaybackQuota = 1
Standard7-day cloud historycloudPlaybackQuota = 7
Premium30-day cloud historycloudPlaybackQuota = 30

AWS KVS Physical Retention 策略​

所有设备的 KVS stream 统一使用 720 hours (30 days) 作为 physical retention。

为什么统一 720h​

  • Premium 需要 30-day history；
  • 如果底层只保留 24h/48h，用户升级到 Standard/Premium 后无法访问更长历史；
  • 当前样机/首批验证阶段优先保证产品能力闭环；
  • 应用层继续通过 entitlement.quota 控制用户实际可访问 1/7/30 天；

不作 per-device retention​

当前阶段的统一策略：

  • AWS KVS physical retention 统一 720h；
  • App 层通过 assertDeviceServiceAccess + validateCloudPlaybackWindow 控制访问窗口；
  • 先不做按设备/按订阅动态调整 stream retention；
  • 成本优化后续再做 per-device 或冷存储策略。

默认值变更​

  • lib/env.ts：kvsDataRetentionHours 默认值从 48 改为 720
  • .env.example：KVS_DATA_RETENTION_HOURS 从 "48" 改为 "720"

注意：如果生产 VM 的 .env.production 显式设置了 KVS_DATA_RETENTION_HOURS=48，需要人工或 SOP 安全更新为 720。

管理工具​

reconcile CLI 默认目标​

reconcile CLI 的默认目标是 720h (30 days)，来源于 TARGET_KVS_RETENTION_HOURS 常量。 它不依赖 NEXT_PUBLIC_APP_URL / DATABASE_URL / AUTH_SECRET 等环境变量。

单 stream 模式（无需 DB）​

# 检查单个 stream，默认 720h
npm run kvs:retention:check -- --stream aovis-stream-aovis-n4k-000001

# 临时覆盖目标值，例如 168h (7 days)
npm run kvs:retention:check -- --stream aovis-stream-aovis-n4k-000001 --target-hours 168

# 实际修改
npm run kvs:retention:apply -- --stream aovis-stream-aovis-n4k-000001

全量模式（需要 DATABASE_URL）​

# 检查所有有 stream 的设备
npm run kvs:retention:check -- --all-devices

# 修改所有设备
npm run kvs:retention:apply -- --all-devices

--all-devices 才会加载 Prisma 连接数据库，此时需要 DATABASE_URL 环境变量。

Options​

OptionDescription
--stream <name>单个 KVS stream
--all-devices从 DB 读取所有有 stream 的设备
--apply实际修改 AWS（默认 dry-run）
--target-hours <n>目标 retention 小时数（默认 720）

重要：

  • 没有 --apply 时不会修改 AWS。
  • --target-hours 必须是正整数，非法值会报错退出。
  • 生产环境的 KVS_DATA_RETENTION_HOURS 环境变量不影响 reconcile CLI 的默认目标值。
  • 生产 .env.production 如果仍有 KVS_DATA_RETENTION_HOURS=48，应人工更新为 720，以保证未来新建 stream 默认正确。
  • 所有命令必须先 dry-run 确认，再 apply。

代码架构​

lib/cloud-storage-retention.ts     ← 常量 + computeKvsRetentionChange
lib/cloud-storage-plans.ts         ← 套餐定义
lib/cloud-access-window.ts         ← 应用层 window 验证
lib/aws/kvs-retention.ts           ← describe/update AWS retention
scripts/kvs-retention-reconcile.ts ← CLI dry-run/apply 入口

当前状态​

  • 这仍只是云存储架构准备，不代表真实视频上传/历史列表已经完成。
  • AWS KVS physical retention 需要手动或通过脚本从 48h 升级到 720h。