Моніторинг UniFi Docker має сенс тоді, коли стандартної панелі контролера вже мало. Цей стек дає історію метрик, графіки по точках доступу, комутаторах, клієнтах і шлюзах, а також нормальну базу для розбору плаваючих проблем. Нижче – практичний сценарій розгортання Unpoller, Prometheus і Grafana в одному Docker Compose без ручного кліканя по UI.
Підхід добре лягає на homelab і невелику інфраструктуру. Він закриває просту задачу: регулярно тягнути метрики з UniFi API, складати їх у часові ряди й дивитися в Grafana не лише поточний стан, а й зміну поведінки мережі з часом.
Що саме дає цей стек
Схема проста. Unpoller підключається до контролера UniFi й віддає метрики у форматі, який розуміє Prometheus. Prometheus опитує endpoint Unpoller, зберігає метрики й дозволяє будувати історію. Далі Grafana піднімає поверх цього дашборди.
Практична користь тут не в самому факті збору даних. Користь у тому, що стає видно базову норму. Скільки клієнтів висить на AP ввечері. Як змінюється навантаження по портах комутатора. Чи є аномалії у конкретного бездротового клієнта. Чи співпадає момент деградації з піком трафіку, стрибком по радіо або проблемним пристроєм.
Де цей підхід доречний, а де вже ні
Для домашньої мережі, лабораторії, маленького офісу або окремого полігону це нормальний варіант. Усе можна запустити одним стеком. Конфігурація прозора. Відлагодження теж просте, бо ланцюжок короткий.
Але є межа. Якщо потрібні складні алерти, централізована багатосайтова модель, довге зберігання великих обсягів метрик або жорсткі вимоги до надійності, одного Compose вже мало. Там логічніше дивитися на окреме рознесення сервісів, нормальне резервування й продумане зберігання даних Prometheus.
Як працює моніторинг UniFi Docker
У потоці даних є три головні вузли. UniFi контролер віддає дані через API. Unpoller читає їх і публікує метрики на власному endpoint. Prometheus опитує цей endpoint, зазвичай по внутрішньому імені сервісу в Docker network. Grafana підключається до Prometheus як до джерела даних і показує дашборди.
Тут важливий один момент. Unpoller не замінює Prometheus і не зберігає історію сам по собі. Якщо Prometheus не пише дані на диск, після перезапуску історія зникне. Тому монтування каталогу для даних Prometheus – не дрібниця, а обов’язкова частина схеми.
Що підготувати перед запуском
Потрібен працюючий Docker host, доступ до контролера UniFi і окремий обліковий запис для читання метрик. Повні адміністраторські права тут не потрібні. Достатньо локального користувача з read-only доступом до мережевого контролера, якщо цього вистачає для автентифікації Unpoller.
Також заздалегідь варто визначити, де лежатимуть bind-mounted каталоги. Якщо UID і GID контейнерів не збігаються з правами на хості, перша проблема буде дуже приземлена – Prometheus або Grafana просто не зможуть писати дані.
Покрокове налаштування моніторингу UniFi Docker
- Створіть каталоги для даних Prometheus і Grafana, а також для provisioning Grafana.
- Підготуйте Docker Compose стек з Unpoller, Prometheus, Grafana і, за потреби, допоміжним переглядом логів.
- Винесіть параметри Unpoller в окремий env-файл. Там мають бути URL контролера UniFi, логін, пароль і назва сайту.
- У UniFi створіть окремого користувача лише для читання.
- У конфігурації Prometheus додайте scrape job, який опитує Unpoller на порту 9130 за ім’ям сервісу Docker.
- У Grafana налаштуйте provisioning джерела даних і дашбордів, щоб після старту нічого не імпортувати руками.
- Запустіть стек через
docker compose up -d
- Дайте стеку кілька хвилин на появу перших метрик.
Ідея такого розгортання в тому, щоб не збирати систему по шматках. Якщо Compose вже зшиває сервіси, Prometheus бачить Unpoller по service name, а Grafana підтягує все через provisioning, старт стає передбачуваним.
Які параметри в Unpoller критичні
На практиці критичних змінних небагато: адреса контролера, облікові дані, сайт і параметр перевірки SSL. Якщо контролер працює на self-signed сертифікаті, перевірка SSL часто стає причиною мовчазного провалу автентифікації або підключення.
Другий частий збій – неправильна назва сайту. У багатьох інсталяціях це default, але покладатися на здогадки не варто. Якщо дашборди порожні, а логін правильний, перевіряють саме URL, сайт і SSL.
Що має бути в Prometheus
У конфігурації Prometheus важливий scrape job для Unpoller. Сенс простий: Prometheus має регулярно ходити на endpoint метрик Unpoller на 9130 порту. Якщо тут помилка в імені сервісу, мережі Compose або самому порту, даних у Grafana не буде, навіть якщо UniFi і Unpoller між собою вже спілкуються.
У невеликому стеку зручно використовувати саме Docker service name. Це прибирає ручне керування IP-адресами. Для homelab це один із найменш болючих варіантів.
Що дивитися в Grafana після запуску
Першими зазвичай відкривають дашборди по access point. Там видно кількість клієнтів, активність по 2.4, 5 і 6 ГГц, а головне – тренд за часом. Це вже дає відповідь на просте питання: проблема стабільна чи епізодична.
Далі корисно дивитися комутатори. По портах видно передачу й прийом, а на PoE-комутаторах – ще й електричні параметри навантаження. Якщо раптом якийсь пристрій починає поводитись дивно, історія по конкретному порту часто пояснює більше, ніж загальний стан у контролері.
Окрема сильна точка – клієнтські метрики. Можна дивитися розподіл по каналах, типи пристроїв, а також групувати схожі девайси. Наприклад, камери або мобільні пристрої. Це зручно, коли треба відловити не абстрактне «мережа гальмує», а конкретний клас клієнтів, який забиває радіоефір або канал.
Типові проблеми: де цей стек ламається найчастіше
Перше місце – права на каталоги. Якщо дані не переживають перезапуск або Grafana не тримає стан, дивляться ownership bind-mounted директорій. Один UID/GID на всі контейнери часто зменшує шум, але не виправляє криво підготовлений host path.
Друге місце – автентифікація Unpoller в UniFi. Зламаний логін, пароль, URL контролера або назва сайту дають дуже схожий симптом: Prometheus живий, Grafana відкривається, а метрик немає.
Третє – SSL. Якщо контролер на self-signed сертифікаті, перевірка сертифіката може завадити з’єднанню. У lab-сценарії відключення verify виглядає прагматично. У більш жорсткому середовищі краще вже нормально розібратись із сертифікатами.
Четверта проблема – очікування миттєвого результату. Після старту стеку метрики не завжди з’являються одразу. Краще дати системі трохи часу, а не починати відлагодження через десять секунд після
docker compose up -d
.
Як перевірити, що моніторинг UniFi Docker реально працює
Найшвидша перевірка – відкрити веб-інтерфейс Prometheus на 9090 і переконатися, що ціль Unpoller доступна. Якщо target в статусі up, половина ланцюжка вже жива.
Далі відкривають Grafana на 3000 і перевіряють дві речі: чи з’явилось джерело даних Prometheus, і чи доступні дашборди без ручного імпорту. Якщо provisioning спрацював, це видно відразу.
Потім дивляться на предметні метрики. Наприклад, клієнти на AP, трафік по порту комутатора або аномалії окремого пристрою. Якщо на графіках є рух за обраний часовий проміжок, стек уже не просто запущений, а дає корисну історію.
Коли варто шукати інший підхід
Якщо потрібна лише швидка перевірка стану, стандартного інтерфейсу UniFi часто вистачає. Піднімати Prometheus і Grafana заради разового погляду на клієнтів – зайва вага.
Якщо ж потрібен серйозніший observability-контур, цей стек теж має межу. Він добрий як практичний і прозорий варіант для homelab. Але коли з’являється багато сайтів, довгі retention-періоди, складні правила сповіщень і вимога до безвідмовності, архітектуру доведеться розносити й ускладнювати.
Для домашньої інфраструктури цього зазвичай достатньо. Отримуєте історію, нормальну видимість по мережі й зрозумілий шлях від симптома до метрики. Саме це й робить моніторинг UniFi Docker корисним: не красиві графіки, а менше здогадок, коли мережа поводиться не так, як учора.