Przechowywanie danych#

vCLU przechowuje wszystkie dane w plikach na dysku urządzenia. Nie ma bazy danych – konfiguracja to JSON, automatyzacje to pliki Lua, a historia czujników to kompaktowe pliki binarne.

Struktura katalogów#

vclu/
├── .vclu.json              Główna konfiguracja (centrum prawdy)
│
├── modules/                Twoje automatyzacje
│   ├── init.lua            Ładowany jako pierwszy
│   ├── lights.lua          Kolejne pliki (alfabetycznie)
│   └── scenes/             Podkatalogi (require ręcznie)
│
├── plugins/                Zainstalowane pluginy
│   ├── vclu--weather/      Katalog pluginu
│   │   ├── plugin.json     Manifest (opis, wersja)
│   │   └── init.lua        Kod pluginu
│   └── vclu--salda/
│
├── kv/                     Dane pluginów (przetrwają restart)
│   ├── vclu--weather.json  Dane pluginu weather
│   └── vclu--salda.json    Dane pluginu salda
│
├── metrics/                Historia czujników (wykresy)
│   ├── temp_salon.bin      Ostatnie 24h, co sekundę
│   └── power_total.bin
│
└── backups/                Kopie zapasowe
    ├── 2026-03-07_120000_auto.tar.gz
    └── 2026-03-08_draft_promote.tar.gz

Główna konfiguracja (.vclu.json)#

Plik .vclu.json to jedyne źródło prawdy o konfiguracji systemu. Przechowuje ustawienia wszystkich podsystemów:

Konfigurację edytuj przez panel webowy. Ręczna edycja pliku JSON jest możliwa, ale niezalecana – łatwo o literówkę, która zepsuje konfigurację.

Twój kod (modules/)#

Katalog modules/ to miejsce na Twoje automatyzacje. Pliki .lua z głównego poziomu katalogu ładują się automatycznie przy starcie:

• init.lua – ładowany jako pierwszy (idealne do konfiguracji MQTT, zmiennych globalnych)
• Pozostałe pliki – ładowane alfabetycznie
• Podkatalogi – nie są ładowane automatycznie, wymagają require()

Edycja plików w modules/ jest możliwa przez:

• Panel webowy – edytor kodu z podświetlaniem składni
• Agent AI (MCP) – agent pisze i testuje kod w sandboxie
• SSH – bezpośrednia edycja plików na urządzeniu

Pluginy (plugins/)#

Pluginy instalujesz z repozytorium przez panel webowy. Każdy plugin ma swój katalog z manifestem (plugin.json) i kodem (init.lua).

Nie edytuj plików pluginów ręcznie – aktualizacje nadpiszą Twoje zmiany. Pluginy konfiguruje się przez panel webowy.

Dane pluginów (kv/)#

Każdy plugin ma własny plik JSON do przechowywania danych, które muszą przetrwać restart systemu. Przykłady: tokeny API, ostatni odczyt czujnika, ustawienia użytkownika.

Dane są izolowane – plugin widzi tylko swoje dane, nie ma dostępu do danych innych pluginów.

Historia czujników (metrics/)#

vCLU zbiera dane z czujników co sekundę i przechowuje ostatnie 24 godziny. Dane są zapisywane w kompaktowych plikach binarnych (ring buffer) – stały rozmiar na dysku, bez konieczności czyszczenia.

Dane z metryk są używane przez:

• Wykresy na dashboardzie – temperatura, wilgotność, zużycie energii
• Agenta AI – analiza trendów, wykrywanie anomalii

Kopie zapasowe (backups/)#

vCLU tworzy kopie zapasowe automatycznie w dwóch sytuacjach:

1. Przed wdrożeniem kodu – gdy promujesz zmiany z sandboxa, poprzednia wersja jest zapisywana.
2. Harmonogram – domyślnie co 24 godziny.

Konfiguracja kopii zapasowych:

{
  "backup": {
    "autoEnabled": true,
    "intervalH": 24,
    "maxBackups": 7
  }
}

System automatycznie usuwa najstarsze kopie, gdy przekroczony zostanie limit (domyślnie 7). Format: skompresowane archiwum .tar.gz z datą i godziną w nazwie.

Co edytować, a czego nie ruszać#

Agent AI#

Agent AI zapisuje dane przez bezpieczne API – nigdy nie modyfikuje plików bezpośrednio. Wszystkie zmiany kodu przechodzą przez sandbox (testowanie) i promote (wdrożenie z automatycznym backupem). Dzięki temu historia zmian jest zachowana, a Twój działający kod jest chroniony.