Техническа документация за компонента за съхранение на файлове

Какво е файловото хранилище?

Файловото хранилище — това е нов компонент на софтуерния комплекс Kickidler, предназначен за съхранение на двоични данни (видео и аудио), събрани от агентите, извън централната база данни. Хранилището работи на локален диск и значително подобрява стабилността и производителността на системата.

Файловото хранилище осигурява:

съхранение на всички видео и аудио файлове, записани от агента Kickidler,
разтоварване на PostgreSQL от обемни двоични данни,
подобрена мащабируемост при работа с голям брой агенти.

Типове съхранявани данни:

screen/ — видеозаписи на екрана,
audio/ — аудиозаписи от микрофона.

Структура на съхранение

Данните се запазват според следната структура:

година/месец/ден/тип/

Такъв подход осигурява гъвкавост и улеснява административните задачи.

Изтриване на данни

Системата автоматично изтрива остарели данни:

проверка се извършва на всеки 10 минути,
изтриването се извършва по дневни папки,
срокът на задържане се настройва чрез интерфейса на централния възел.

Какво се случва при инсталация и ъпдейт

При нова инсталация:

потребителят указва пътя до хранилището,

При актуализация:

съществуващите данни в базата остават,
новите видео и аудио файлове се записват във външното хранилище,
осигурява се обратно съвместимост: системата продължава да чете старите данни от базата.

Особености и ограничения

поддържат се повече от 1000 агенти едновременно,
няма ограничение за размер на .blob (до 9 GB),
повторно изпращане при загуба на връзка,
уникални ключове предотвратяват дублиране,
сигурността се осигурява чрез права на операционната система (файловете не се криптират).

Местоположение на хранилището (по подразбиране)

Windows:

C:\ProgramData\ki-data

Linux:

/var/opt/ki

Важно: Папките се създават автоматично след инсталация на сървъра.

Промяна на пътя към хранилището

Пътят може да се промени чрез конфигурационния файл node.ini.

Инструкция за промяна на пътя:

Спрете услугата KickidlerNode (nns):

чрез "Услуги" на Windows (services.msc) или командния ред:
```
net stop nns
```
за Linux:
```
systemctl stop kickidlernode
```
Отворете конфигурационния файл:

Windows:
```
C:\Program Files\KickidlerNode\config\
```
Linux:
```
/opt/KickidlerNode/
```
Отворете node.ini с текстов редактор (Notepad, Notepad++, Vim, Nano и др.).
Задайте нов път:

Намерете реда
```
fileStoragePath=
```
Ако редът съществува: променете стойността след = на абсолютен път до новата директория.

Ако редът липсва: добавете накрая на файла:
```
fileStoragePath=<Нов_Път>
```
Формат на пътя:

Използвайте наклонена черта / (Unix стил), дори в Windows.

Пример за Windows:
```
fileStoragePath=D:/KickidlerData/ o E:/Monitoring/Records/
```
Пример за Linux:
```
fileStoragePath=/mnt/storage/kickidler_data/
```
Уверете се, че пътят завършва с /.
Запазете node.ini.

Windows

net start nns

Linux

systemctl start kickidlernode

Прехвърляне на съществуващи данни

Ако имате записи в старата папка (C:\ProgramData\ki-data или /var/opt/ki), копирайте или преместете ръчно цялото съдържание във новата папка, указана в fileStoragePath=, след стартиране на услугата с новите настройки.

Уверете се, че структурата вътре в новата папка съответства на стария модел (Година/Месец/Ден/screen/, Година/Месец/Ден/audio/).

Ключови предупреждения при промяна на пътя:

Права за достъп: Уверете се, че акаунтът, под който работи nns услугата (KickidlerNode), има пълни права (четене/запис/промяна) върху новата целева директория и всички поддиректории.

Свободно пространство: Новият диск трябва да разполага с достатъчно място за записите.

Спиране на услугата: Промяната изисква задължително спиране на услугата. Промяна "на живо" не се поддържа и може да доведе до грешки.

Структура на данните в хранилището

Данните са организирани йерархично по дата:

Година (YYYY)/

Месец (MM)/

Ден (DD)/

screen/ (папка с видео файлове)

audio/ (папка с аудио файлове)

Формати на файлове (в screen/ и audio/):

<Число>.lock
<Число>.blob
<Число>.key

Retention management and data deletion

Automatic deletion: Since May 2025, a feature has been added to automatically remove video (and related audio) data after the retention period expires.

Configuring the retention period:

Open the Kickidler Administrator web interface.
Go to Configuration → Components & Coordination → Server
Find the parameter Video Retention Period.
Set the desired number of days for which recordings should be stored on the Node (e.g., 7, 14, 30).
Save the server configuration changes.

How it works:

Once the set "Video Retention Period" expires (counted from the recording date):

Recordings are deleted from the central server database
Corresponding files (.lock, .blob, .key) in the local storage on the Node are automatically deleted.

Manual deletion of files from storage folders is no longer required or recommended, as files deleted manually before the retention period expires will make recordings unavailable in the Viewer, and files left after expiry will be deleted automatically.

Manual data deletion

Not recommended for routine management, since automatic deletion now covers this task.

Use only if:

You need to immediately free up disk space right now.
You need to delete data for a specific period that has not yet expired according to the "Video Retention Period" setting.

How to delete manually:

Stop the KickidlerNode service (nns) (see section 3.1).
Navigate to the local storage folder (default or changed).
Delete the corresponding subfolders (Year/Month/Day) whose data you want to erase.
Start the KickidlerNode service (nns).

Manually deleting folders/files directly will make the corresponding recordings unavailable in Kickidler Viewer. Data in the server database is not deleted automatically and may become broken (referencing missing files).

Administrator Summary:

Storage path:

Configured in node.ini → fileStoragePath (Unix-style) after stopping the service. Check permissions!
Structure:

Year/Month/Day/screen|audio/ with .lock, .blob, .key files. Do not modify manually unless necessary.
Cleanup:

Set the Video Retention Period in the web interface (Configuration → Components & Coordination → Server). Automatic deletion of files and DB records is active. Manual cleanup is a last resort.

← Централен сървър

↑ Ръководство за потребителя на Kickidler

Вюър →

Съхранение на файлове