UniFi Network Application trên Synology bằng Docker

UniFi Network Application là gì, dùng để làm gì?

UniFi Network Application — tên cũ quen thuộc hơn là UniFi Controller — là phần mềm quản lý tập trung cho cả dàn thiết bị mạng Ubiquiti UniFi: access point, switch PoE, gateway. Nói nôm na, nhà có 2-3 con AP UniFi mà cứ phải đăng nhập vào từng cái để chỉnh SSID, xem client thì mệt lắm. Controller này gom hết về một dashboard, khỏi phải nhảy qua nhảy lại.

Bốn việc nó làm tốt nhất:

• Quản lý topology, băng thông, danh sách client của cả hệ thống AP/switch/gateway từ một web dashboard duy nhất.
• Adopt (nhận diện và cấu hình) AP mới chỉ bằng vài click, không cần config tay từng con.
• Tạo guest network riêng có captive portal, giới hạn băng thông, cô lập VLAN cho khách ra vào.
• Theo dõi real-time: client đang kết nối, cường độ tín hiệu, traffic, cảnh báo khi thiết bị rớt mạng.

Case thực tế thì dễ gặp nhất là nhà nhiều tầng dùng 2-3 AP UniFi, cần quản lý roaming và band steering tập trung thay vì lọ mọ qua app di động từng lần. Hoặc bạn vừa nâng cấp từ router WiFi tiêu dùng lên hệ sinh thái UniFi (AP + switch PoE), giờ cần một nơi "luôn on" để chạy controller — NAS đang chạy 24/7 sẵn rồi, hợp lý hơn nhiều so với để một con máy tính bàn cắm điện suốt ngày chỉ để hầu controller. Cũng không ít người chọn tự host vì không muốn phụ thuộc UniFi Cloud (console.ui.com), hoặc đơn giản là tiếc tiền mua thêm Cloud Key/Dream Machine.

So với Cloud Key hay Dream Machine — thiết bị chuyên dụng phải mua thêm — tự host trên Synology không tốn phần cứng mới, dữ liệu nằm trong nhà bạn luôn. Đánh đổi là bạn phải tự lo update, tự lo backup, không có ai làm hộ.

Vì sao chọn Docker (Container Manager) chứ không phải Virtual Machine Manager

Trên DSM có hai đường để chạy UniFi Network Application: dựng một VM Ubuntu qua Virtual Machine Manager, hoặc chạy container qua Container Manager. Với NAS phổ thông tầm DS223, DS224+, DS923+ chỉ có 2-4GB RAM, VM là lựa chọn tốn kém không cần thiết — phải cấp cố định vCPU và RAM riêng cho cả một hệ điều hành, trong khi controller thật ra chỉ là một app Java chạy trên nền Ubuntu bên trong đó.

Container nhẹ hơn nhiều vì chia sẻ kernel DSM, không cần dựng cả một OS riêng. VM chỉ đáng dùng khi NAS không có Container Manager (mấy model ARM cũ như DS218j), hoặc khi cần cách ly hệ điều hành hoàn toàn vì lý do khác. Với đa số NAS Synology đời gần đây, Docker là lựa chọn hợp lý hơn hẳn.

Container Manager có từ DSM 7.2 trở lên, thay cho package "Docker" cũ trên DSM 7.1 và trước. Kiểm tra bằng cách vào Package Center gõ "Container Manager" — không thấy thì model NAS của bạn có thể không hỗ trợ Docker, thường rơi vào dòng ARM đời cũ hoặc J-series.

Chọn image nào: linuxserver hay jacobalberty

Trên mạng lưu hành hai dòng image UniFi controller, và đây là chỗ dễ lẫn nhất khi bạn copy compose từ nguồn khác nhau. Image jacobalberty/unifi từng rất phổ biến vì gộp sẵn MongoDB bên trong, chỉ cần 1 container là chạy. Nhưng Ubiquiti đã bỏ MongoDB nhúng từ UniFi Network App bản 8 trở đi, nên image này giờ gần như đứng bánh — dùng nó dễ bị kẹt ở version cũ, thiếu tính năng, có khi không tương thích AP đời mới.

Bài này dùng linuxserver/unifi-network-application, cập nhật đều và bám sát các bản UniFi mới nhất (8.x đến 10.x). Đánh đổi là bạn phải chạy thêm một container MongoDB riêng — cồng kềnh hơn image gộp sẵn một chút, nhưng đổi lại được cập nhật lâu dài, không lo bị bỏ rơi giữa đường.

Chuẩn bị trước khi cài

• DSM 7.2 trở lên với Container Manager, hoặc package Docker nếu DSM cũ hơn.
• Theo yêu cầu chính thức của Ubiquiti: tối thiểu 2 CPU core và 2GB RAM rảnh cho controller. NAS tổng RAM ≥4GB là an toàn nếu còn chạy thêm dịch vụ khác.
• Truy cập DSM qua File Station hoặc SSH để tạo thư mục.
• Biết IP tĩnh (hoặc đặt DHCP reservation) cho NAS — cần dùng ở bước cấu hình sau.

Bước 1: Tạo shared folder

Vào File Station, tạo shared folder docker nếu chưa có, rồi tạo thêm 2 thư mục con bên trong đường dẫn /volume1/docker/unifi:

• /volume1/docker/unifi/data — nơi lưu dữ liệu, cấu hình của app.
• /volume1/docker/unifi/db — nơi lưu database MongoDB.

Bước 2: Viết docker-compose.yml

Mở Container Manager > Project > Create, chọn "Create docker-compose.yml", dán nội dung sau:

version: "3.8"
services:
  mongo:
    image: mongo:4.4
    container_name: unifi-db
    restart: unless-stopped
    volumes:
      - /volume1/docker/unifi/db:/data/db
    environment:
      - TZ=Asia/Ho_Chi_Minh

  unifi-network-application:
    image: lscr.io/linuxserver/unifi-network-application:latest
    container_name: unifi-network-application
    restart: unless-stopped
    depends_on:
      - mongo
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Ho_Chi_Minh
      - MONGO_HOST=mongo
      - MONGO_PORT=27017
      - MONGO_DBNAME=unifi
      - MONGO_USER=unifiuser
      - MONGO_PASS=doi-mat-khau-nay
      - MEM_LIMIT=1024
      - MEM_STARTUP=1024
    volumes:
      - /volume1/docker/unifi/data:/config
    ports:
      - 8443:8443
      - 8080:8080
      - 3478:3478/udp
      - 10001:10001/udp
      - 8843:8843
      - 8880:8880
      - 6789:6789
      - 5514:5514/udp
    network_mode: bridge

Bốn port bắt buộc phải mở: 8443 là web admin, 8080 để AP inform/adoption, 3478/udp cho STUN, 10001/udp để AP discovery. Thiếu một trong bốn cái này là controller và AP coi như "cạch mặt" nhau, không nói chuyện được. Còn 8843/8880 (guest portal), 6789 (speed test), 5514/udp (remote syslog) là tùy chọn — không dùng guest portal thì bỏ luôn cho gọn.

Container mongo không cần map port ra ngoài — nó chỉ nói chuyện nội bộ với container app qua tên service mongo, không có lý do gì mở 27017 ra bridge network cho rước rủi ro vào người.

PUID/PGID là ID user trên NAS, SSH vào gõ id là ra ngay. Ai chưa biết số này thì bình thường thôi, cứ để 1000 cũng chạy tốt với hầu hết máy dùng user mặc định.

Bước 3: Deploy project

Đặt tên project (ví dụ unifi), bấm Next rồi Done. Container Manager sẽ pull cả 2 image và khởi động. Lần đầu pull image linuxserver + mongo có thể mất vài phút tùy tốc độ mạng — cứ để nó chạy, đừng sốt ruột bấm lại làm gì.

Vào tab Container kiểm tra cả 2 container đang ở trạng thái Running. Container app cứ restart liên tục thì xem log trước — thường là do chưa kết nối được mongo (đợi thêm chút vì mongo cần thời gian khởi tạo trước) hoặc sai biến môi trường.

Bước 4: Setup wizard lần đầu

Mở browser, vào https://[IP-NAS]:8443. Trình duyệt sẽ cảnh báo chứng chỉ không an toàn — bình thường, vì đây là self-signed certificate, bấm "Advanced" > "Proceed anyway" là qua.

Làm theo setup wizard: đặt tên site, tạo tài khoản admin, bỏ qua bước liên kết UniFi Cloud account nếu bạn chủ đích tự host offline.

Bước 5: Đặt Override inform host

Đây là bước hay bị bỏ quên nhất, và cũng là thủ phạm số 1 khiến AP tự dưng "quên" controller sau một thời gian. Vào Settings > System > Controller Settings, tìm mục "Override inform host", điền IP tĩnh của NAS.

Lý do phải làm: mặc định controller tự lấy IP hiện tại của nó để báo cho AP biết "gửi report về đây". NAS đổi IP (do DHCP cấp lại, do đổi router...) là AP vẫn nhớ IP cũ, tìm không ra controller nữa. Đặt IP tĩnh + override sẵn giúp tránh trọn vấn đề này.

Bước 6: Adopt access point

AP cùng subnet với NAS thường tự hiện lên trên dashboard, bấm "Adopt" là xong. Không tự thấy thì SSH vào AP (thường qua Ubiquiti Discovery Tool để tìm IP) và chạy:

set-inform http://[IP-NAS]:8080/informLệnh này ép AP báo cáo trực tiếp về controller theo địa chỉ chỉ định, bỏ qua bước tự dò tìm qua broadcast — hữu ích khi AP nằm ở VLAN khác hoặc mạng có chặn discovery.

Bước 7: Cấu hình Guest Network (tùy chọn)

Vào Settings > Guest Control, bật Guest Network, chọn SSID riêng, cấu hình captive portal (splash page trước khi vào mạng), giới hạn băng thông download/upload cho khách, và cô lập VLAN riêng để khách không mò được vào mạng nội bộ nhà bạn.

Bước 8: Bật auto-restart

Compose file trên đã có restart: unless-stopped cho cả 2 container — NAS reboot hoặc update DSM xong, app và database tự bật lại, không cần bạn vào bấm tay. Deploy qua UI thay vì compose thì vào Container Manager > Container > Settings kiểm tra lại cho chắc tùy chọn này đang bật.

Lỗi hay gặp và cách xử lý

• MongoDB ngốn RAM tăng dần theo thời gian: WiredTiger cache của MongoDB có xu hướng chiếm dần RAM rảnh, trên NAS yếu có thể gây cảnh báo thiếu RAM. Có case thực tế NAS 8GB bị cảnh báo, restart container xong RAM tụt về khoảng 23% ngay. Xử lý: theo dõi qua Resource Monitor thường xuyên, đặt giới hạn memory cho container nếu NAS RAM ≤4GB.
• Dùng mongo:7 trên CPU không hỗ trợ AVX: nhiều NAS chip Realtek hoặc ARM giá rẻ không có AVX, chạy mongo:7 sẽ crash-loop ngay từ lúc khởi động. Cứ dùng mongo:4.4 như compose trên cho an toàn, chỉ đổi bản mới hơn khi chắc CPU NAS hỗ trợ.
• AP không adopt được dù cùng mạng: thường do thiếu bước Override inform host ở trên, hoặc firewall DSM/router chặn port 8080. Kiểm tra Control Panel > Security > Firewall trên DSM, đảm bảo port 8080, 8443, 3478/udp, 10001/udp không bị block.
• Lẫn cấu trúc volume giữa 2 dòng image: copy compose từ nguồn dùng jacobalberty/unifi (volume /unifi/data, /unifi/log, /unifi/cert) rồi ghép vào cấu hình linuxserver (volume /config) là sai bét — container lên nhưng dữ liệu không đúng chỗ. Bám đúng một dòng image, đừng trộn.
• Dùng tag latest cho mongo: nghe tiện nhưng Container Manager có thể tự pull lên major version mới lúc nào không hay, mà MongoDB không tự nâng cấp dữ liệu giữa các major version — hậu quả là container không khởi động lại được. Luôn pin version cụ thể như mongo:4.4, đừng ham latest.

Bảo mật và bảo trì

Đừng expose port 8443 hay mongo thẳng ra Internet. Cần truy cập từ xa thì dùng UniFi Cloud remote access có sẵn trong app, hoặc chạy qua VPN — Synology VPN Server hoặc Tailscale đều được. Tuyệt đối không port-forward 8443 ra ngoài router.

Đặt MONGO_USER/MONGO_PASS riêng ngay từ đầu, đừng để mặc định hay để trống. Mongo tuy không lộ ra ngoài nhưng cẩn tắc vô áy náy.

Trước khi update lên version lớn (ví dụ từ 8.x lên 9.x), backup thư mục data và db qua Hyper Backup. UniFi Network App có thể migrate schema database khi lên version mới, và bước này không rollback lại được — hỏng giữa đường là mất luôn cấu hình, không có đường quay đầu. Backup đi, ổ cứng nào rồi cũng có ngày dở chứng, chỉ là nó chọn đúng lúc bạn chưa backup hay không mà thôi.

Theo dõi RAM/CPU định kỳ qua Resource Monitor, đặc biệt nếu NAS tổng RAM chỉ 4GB trở xuống. MongoDB không phải loại chạy êm rồi để đấy quên luôn được.