Retention

Pengenalan

Rekaman DVR tumbuh sekitar 10 sampai 40 GB per kamera per hari tergantung bitrate. Retention adalah worker di dalam Liodra yang menghapus segmen lama sesuai kebijakan, sehingga disk tidak pernah penuh dan Anda tidak perlu cron job eksternal.

Kebijakan disimpan di retentions.yaml pada volume storage dan dapat diubah lewat API saat runtime tanpa restart. Ada satu kebijakan default yang berlaku untuk semua channel, dan kebijakan per channel yang menimpanya.

Cara Menggunakan

curl http://localhost:9080/api/v1/retention

curl -X PUT http://localhost:9080/api/v1/retention/default \
  -H 'Content-Type: application/json' \
  -d '{ "duration_days": 14, "disk_quota_mb": 2000000, "headroom_percent": 5 }'

curl -X PUT http://localhost:9080/api/v1/retention/schedule \
  -H 'Content-Type: application/json' \
  -d '{ "time": "02:30:00" }'

curl -X POST http://localhost:9080/api/v1/retention/policies \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "live/lobby",
    "retention": {
      "duration_days": 30,
      "time_of_day_start": "06:00:00",
      "time_of_day_end": "22:00:00"
    }
  }'

curl http://localhost:9080/api/v1/retention/usage            # disk sistem + I/O
curl http://localhost:9080/api/v1/retention/usage/live/lobby # ukuran satu channel
curl -X POST http://localhost:9080/api/v1/retention/cleanup/live/lobby  # jalankan sekarang

Fitur Utama

Tiga pass per channel

Setiap kali cleanup berjalan (terjadwal atau manual), tiap channel diproses dalam urutan tetap:

1. Umur: direktori hari yang seluruhnya lebih tua dari duration_days dihapus utuh (murah, satu rm -r per hari), lalu file individual yang tersisa diperiksa.
2. Jendela jam: untuk 24 jam sebelumnya, segmen di luar time_of_day_start..end dihapus. Hanya hari sebelumnya yang dipindai agar operasi tetap ringan, jadi kebijakan baru hanya berlaku ke depan.
3. Kuota: bila ukuran channel melampaui disk_quota_mb, file tertua dihapus satu per satu sampai berada di bawah quota × (100 - headroom_percent)%.

Channel ditemukan otomatis dari struktur direktori recordings/, termasuk channel bertingkat, jadi device baru langsung tercakup oleh kebijakan default.

Pengaman darurat (MAX_DISK_USAGE)

Terlepas dari jadwal, worker melakukan heartbeat tiap RETENTION_HEARTBEAT_INTERVAL (1 menit, minimum 30 detik). Bila pemakaian disk melewati MAX_DISK_USAGE (80%), Liodra menjalankan cleanup global darurat dengan tiga pengaman:

• hanya file yang lebih tua dari 1 jam yang boleh dihapus;
• paling banyak 20% dari total file per putaran;
• target turun ke MAX_DISK_USAGE - 5% (tidak pernah di bawah 50%).

Pengaman ini mencegah penghapusan massal akibat salah konfigurasi, tetapi juga berarti disk yang jauh terlalu kecil tidak akan "diselamatkan" seketika. Ukur kebutuhan disk dengan max_recommended_quota_mb.

Penyimpanan dan hot reload

Perubahan lewat API ditulis ke retentions.yaml (version, last_updated, cleanup_schedule) dan langsung berlaku. Mengedit file secara manual juga bisa, tetapi memerlukan restart container agar terbaca.

Statistik cleanup

POST /api/v1/retention/cleanup mengembalikan ringkasan yang sama dengan yang ditulis ke log [Retention]:

{
  "start_time": "2026-09-16T00:00:00Z",
  "end_time": "2026-09-16T00:00:04Z",
  "duration": "4.2s",
  "files_deleted": 2880,
  "bytes_freed": 25769803776,
  "channel_stats": [{ "channel": "live/lobby", "files_deleted": 2880, "bytes_freed": 25769803776 }],
  "errors": []
}

API Reference

Detail lengkap di API Reference: Retention.

Tips & Troubleshooting

Selanjutnya