Ana içeriğe geç

ADR-004: MQTT Topic Hiyerarsisi Tasarimi

DurumKabul Edildi
Tarih2025-11
Karar VerenGüçlü Ceyhan

Baglam​

Zeus 2.0'da MQTT topic yapisi su gereksinimleri karsilamalidir:

  • Multi-tenant izolasyon: Her organizasyonun verileri birbirinden topic seviyesinde ayrilmali
  • Gateway bazli gruplama: Bir ESP32 gateway birden fazla Modbus cihaz okur
  • Farkli veri tipleri: Telemetri, durum, komut, OTA, bootstrap gibi farkli mesaj turleri
  • ACL uyumlulugu: EMQX ACL kurallari ile topic bazli erisim kontrolu
  • Wildcard subscription: Backend'in tenant veya gateway bazli toplu dinleme yapabilmesi

Karar​

Asagidaki hiyerarsik topic yapisi benimsendi:

# Telemetri verileri
tenant/{tenant_id}/gw/{gateway_id}/data/{group}/timeseries

# Cihaz durum bilgisi
tenant/{tenant_id}/gw/{gateway_id}/status

# Komut gondermek (backend → cihaz)
tenant/{tenant_id}/gw/{gateway_id}/cmd/{command_type}

# OTA guncellemeleri
tenant/{tenant_id}/gw/{gateway_id}/ota/{action}

# Bootstrap (tenant atanmadan once)
/bootstrap/{gateway_id}/hello

Topic Hiyerarsisi Semasi​

tenant/
  └── {tenant_id}/
       └── gw/
            └── {gateway_id}/
                 ├── data/
                 │    ├── inverter/timeseries
                 │    ├── meter/timeseries
                 │    └── weather/timeseries
                 ├── status
                 ├── cmd/
                 │    ├── restart
                 │    ├── config
                 │    └── modbus-scan
                 └── ota/
                      ├── notify
                      ├── progress
                      └── result

Alternatifler​

Duz topic yapisi​

devices/{mac_address}/data
  • Artilari: Basit, kolay anlasilir
  • Eksileri: Tenant izolasyonu yok, veri tipi ayirimi yok, ACL kurallari karmasik
  • Red nedeni: Multi-tenant gereksinimi karsilamaz

Cihaz bazli topic​

{tenant_id}/{device_id}/{data_type}
  • Artilari: Cihaz bazinda granul kontrol
  • Eksileri: Gateway kavrami kaybolur (bir gateway 10+ cihaz okuyor), topic sayisi patlak verir, ACL kurallari cihaz bazinda yazilmali
  • Red nedeni: Gateway bazli gruplama yapilamamasi, operasyonel karmasiklik

Serbest format (cihaz karar verir)​

  • Artilari: Esnek
  • Eksileri: Standart yok, ACL uygulanamaz, backend parsing karmasikligi
  • Red nedeni: Kontrolsuz, guvenlik riski

Gerekce​

Secilen topic yapisi su avantajlari saglar:

  1. Tenant izolasyonu topic seviyesinde: ACL kurali tenant/{tenant_id}/# ile tek satirda tum tenant verisi korunur
  2. Gateway bazli gruplama: Bir gateway birden fazla Modbus cihaz okuyor — gw/{gateway_id}/data/ altinda gruplar halinde yayinlar
  3. Grup bazli ayirim: Farkli cihaz turleri (inverter, meter, weather) farkli QoS ve interval gerektirebilir
  4. Wildcard subscription destegi:
    • Tum tenant verisi: tenant/{tid}/#
    • Belirli gateway: tenant/{tid}/gw/{gid}/#
    • Tum inverter verileri: tenant/{tid}/gw/+/data/inverter/timeseries
  5. Bootstrap akisi: Yeni cihaz ilk baglandiginda /bootstrap/{id}/hello topic'ine mesaj atar — backend cihazi tanir ve tenant atar

Sonuclar​

Olumlu​

  • EMQX ACL kurallari basit ve etkili — tenant/{tenant_id}/# ile tam izolasyon
  • Backend wildcard subscription ile tum telemetriyi tek baglanti ile dinleyebiliyor
  • Topic yapisi kendini acikliyor (self-documenting)
  • Yeni cihaz tipleri eklenmesi kolay — yeni bir data/{group} altinda topic acmak yeterli
  • OTA ve komut kanallari veri kanallarindan ayri — farkli QoS ve retention uygulanabilir

Olumsuz​

  • Topic uzunlugu artiyor (ortalama ~60 karakter) — ESP32'de daha fazla bellek kullanimi
  • Her yeni tenant/gateway icin ACL kurali guncellenmeli (HTTP ACL backend ile otomatis cozulmus)
  • Bootstrap → tenant atama gecisi ek state management gerektirir
  • Topic yapisi degisikligi tum cihazlarin firmware guncellemesini gerektirir