configuring-unifi-network-remote-management-in-docker

При переносе UniFi Network Application (UNMS) с локального сервера Windows/Java на выделенный Linux‑хост в Docker можно столкнуться с проблемой: точки доступа (AP) продолжают «званивать» на старый контроллер, остаются в состоянии Disconnected/Adoption Required и не управляются. Руководство описывает надёжную методику миграции, включает проверки контейнера, firewall, set‑inform, а также применяет best practices по security hardening и disaster recovery.

Исходная архитектура и минимальные требования

Компонент	Значение / версия
Linux‑дистрибутив (хост)	Ubuntu 20.04 LTS / Debian 12
Docker Engine	24.x или новее
Образ UniFi	`ghcr.io/jacobalberty/unifi:latest`
Сеть Docker	`network_mode: host` (желательно)
Внешний IP сервера	Статический / Elastic
Проброшенные порты (TCP/UDP)	8080 TCP, 8443 TCP, 3478 UDP, 10001 UDP
Резервная копия	`.unf` или auto‑backup на локальном Win‑контроллере

Важно: режим host избавляет от NAT внутри Docker, упрощает STUN и discovery. Если по соображениям безопасности нужен bridge‑режим, дополнительно настройте --net=bridge + --publish каждого порта.

Проверяем жизнеспособность контейнера

Статус и автозапуск

docker ps --filter "name=unifi"

если OFFLINE:

docker restart unifi

Онлайн‑лог в реальном времени

docker logs -f --tail=200 unifi

Ключевые ошибки:

inform error — AP не может достучаться до контроллера.
Unable to open DB connection — повреждён том ./data.
port binding failed — конфликт портов (часто 8080/8443).

Сетевые порты и firewall

Порт	Протокол	Назначение
8080	TCP	set‑inform (adoption)
8443	TCP	GUI UniFi Network
3478	UDP	STUN (NAT‑транзит)
10001	UDP	Layer‑2 discovery / adoption
1900	UDP	SSDP (иногда требуется для U‑LTM)

Проверяем LISTEN на хосте

ss -tuln | grep -E '8080|8443|3478|10001'

Открываем нужные порты (UFW‑пример)

ufw allow 8080/tcp
ufw allow 8443/tcp
ufw allow 3478/udp
ufw allow 10001/udp

Совет по безопасности: ограничьте 8443 по IP‑white list, особенно если GUI доступен напрямую из интернета.

Подготовка Docker Compose (production‑вариант)

services:
  unifi:
    image: ghcr.io/jacobalberty/unifi:latest
    container_name: unifi
    restart: unless-stopped
    network_mode: host      # direct access to the host stack
    volumes:
      - ./data:/unifi       # config, backups, db
      - /etc/localtime:/etc/localtime:ro
    environment:
      TZ: "Europe/Kyiv"
      RUNAS_UID0: "false"   # drop root inside the container
      UNIFI_UID: 1000       # host system user uid
      UNIFI_GID: 1000

После изменения docker‑compose.yml перезапустите стек:

docker compose down && docker compose up -d

Настройка Override Inform Hostname/IP

Откройте веб‑интерфейс https://PUBLIC_IP:8443.
Settings → System → Network Application Hostname/IP.
Впишите публичный IP или FQDN сервера.
Активируйте чекбокс Override Inform Host.
Нажмите Apply Changes.

Контроллер будет автоматически раздавать новый адрес AP‑устройствам при следующем подключении.

Принудительный set‑inform на точке доступа

Подключаемся по SSH

ssh ubnt@AP_IP
# пароль по дефолту: ubnt / ubnt, либо ваш собственный

Проверяем текущее состояние:

info

Пример вывода проблемы:

Inform Error: Timeout (http://192.168.50.198:8080/inform)

Меняем контроллер:

set-inform http://PUBLIC_IP:8080/inform

Ожидаем Adopting → Provisioning → Connected.

Если AP не меняет статус

syswrapper.sh restore-default
reboot
# после ребута повторяем set-inform дважды (стандарт UniFi)

Типичные ловушки и их обход

Симптом	Причина	Лечение
Контейнер стартует, GUI недоступен на :8443	SELinux/AppArmor блокирует	audit2why / setenforce 0 (тест)
GUI доступен, AP «Disconnected»	Не включён Override, неверный DNS	Включите Override Host Inform
Ошибка `java.lang.OutOfMemoryError: Java heap`	Недостаточно RAM, default Xmx 1024 МБ	`UNIFI_JVM_EXTRA_OPTS=-Xmx2048M`
STUN работает частично, AP за NAT	3478 UDP закрыт	Откройте 3478 UDP или настройте NAT 1:1
Docker bridge, порты проброшены, AP не видит L2	10001 UDP не проброшен	`-p 10001:10001/udp` или host‑mode

Резервное копирование и откат

Настройте Auto‑Backup в UniFi → Settings → System → Backup.
Храните .unf в S3/MinIO (rclone copy ./data/backup ...).
Для disaster recovery достаточно:

docker cp backup.unf unifi:/unifi/data/data/backup/autobackup
docker restart unifi

Через GUI → Restore Backup выберите нужный файл.

Безопасность и hardening

TLS offload: поставьте Nginx reverse‑proxy, перенаправляйте 443→8443, подключите Let’s Encrypt.
Geo‑fencing: ограничьте доступ к GUI по GeoIP.
Fail2Ban: фильтр по /unifi/logs/server.log на 8443.
Актуализация: обновляйте образ раз в месяц (watchtower или CI‑pipeline).

Быстрый чек‑лист перед сдачей в прод

Контейнер unifi online, порты LISTEN = ✅.
Override Inform Host = ✅ (IP/FQDN актуальны).
AP прошли процесс Adoption = ✅.
Firewall правил DROP не мешает = ✅.
Auto‑Backup → внешнее хранилище = ✅.
Документирован пароль ubnt поменян = ✅.

Заключение

Перенос UniFi Network в Docker — отличный способ централизации управления и изоляции окружения. Главный камень преткновения — set‑inform и корректное пробрасывание портов. Следуя приведённым шагам, вы сократите время миграции до 15–20 минут, минимизируете даунтайм Wi‑Fi‑сети и получите прогнозируемую, легко масштабируемую инфраструктуру.

Помните: backup, test, repeat — три кита надёжной инфраструктуры.

Настройка удалённого управления UniFi Network в Docker