Deploy UpSnap trên Docker: Xây dựng Dashboard Wake-on-LAN thông minh cho HomeLab

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

Chạy HomeLab nghĩa là bạn có nhiều máy — NAS, media server, hay một máy trạm cũ chạy VM. Phần khó chịu nhất? Mỗi lần cần dùng lại phải đi đến tận nơi để bật nguồn. Wake-on-LAN (WoL) giải quyết được điều đó, nhưng công cụ CLI thuần túy khá lủng củng khi dùng hàng ngày. Đó là lý do UpSnap ra đời.

Tôi đã quản lý năm node trong home lab bằng UpSnap suốt vài tháng qua, và sự khác biệt trong quy trình làm việc rất rõ rệt. Hướng dẫn này sẽ giúp bạn chạy UpSnap trên Docker — bao gồm cả những vấn đề về network mà hầu hết mọi người đều vấp phải lần đầu tiên.

So sánh các phương án: Mọi người thường xử lý Wake-on-LAN như thế nào?

Trước khi chọn công cụ, hãy hiểu rõ các lựa chọn hiện có. Có ba cách phổ biến để quản lý WoL trong HomeLab:

1. Công cụ CLI thuần (etherwake / wakeonlan)

Nhanh và trực tiếp. Bạn SSH vào một máy trên cùng mạng rồi chạy:

wakeonlan AA:BB:CC:DD:EE:FF
# hoặc
etherwake -i eth0 AA:BB:CC:DD:EE:FF

Dùng được, nhưng có nhiều bất tiện: phải nhớ địa chỉ MAC, máy gửi packet phải cùng subnet, và không có phản hồi trạng thái nào cả. Bạn gửi magic packet xong rồi chỉ biết ngồi chờ máy khởi động.

2. Tích hợp Home Assistant

Nếu bạn đã chạy Home Assistant (đã có bài viết giới thiệu trên blog này), nó có tích hợp WoL sẵn. Bạn định nghĩa thiết bị trong configuration.yaml và có thể kích hoạt chúng từ automation hoặc dashboard.

Tuy nhiên, Home Assistant là một stack nặng nếu chỉ dùng cho WoL. Cấu hình bị phân tán qua nhiều file YAML, và network packet vẫn cần phát ra từ đúng interface.

3. UpSnap — Dashboard WoL chuyên dụng

UpSnap là ứng dụng web tự host, nhẹ, được xây dựng riêng cho việc quản lý Wake-on-LAN. Nó lưu danh sách thiết bị, cho phép bạn bật và ping chúng từ trình duyệt, và hiển thị trạng thái theo thời gian thực. Backend viết bằng Go (nhanh, ít tốn RAM — thường dưới 50MB khi chạy), frontend là giao diện SvelteKit gọn gàng.

Chạy trong một Docker container duy nhất. UpSnap dùng PocketBase làm database nhúng, nên không cần quản lý DB bên ngoài.

Ưu và nhược điểm

Công cụ CLI

  • Ưu điểm: Không cần cài đặt, có sẵn trên mọi máy Linux, có thể dùng trong script
  • Nhược điểm: Không có web UI, không kiểm tra trạng thái ping, cần SSH để gửi packet, dễ quên địa chỉ MAC, không có lịch sử hay audit trail

Tích hợp WoL của Home Assistant

  • Ưu điểm: Rất tốt nếu bạn đã có Home Assistant, hỗ trợ automation, tích hợp với các sự kiện smart home khác
  • Nhược điểm: Nặng nếu bạn không dùng phần còn lại của HA, cấu hình phân tán qua nhiều file YAML, không được xây dựng chuyên cho quản lý server

UpSnap

  • Ưu điểm: Được xây dựng đúng cho mục đích này, nhẹ (~30MB image), giao diện sạch sẽ, trạng thái ping thời gian thực, lên lịch bật máy theo cron, có xác thực tích hợp, triển khai một container duy nhất
  • Nhược điểm: Không có app mobile (chỉ dùng qua trình duyệt), WoL packet vẫn phải đến được broadcast domain — cần cấu hình Docker networking cẩn thận

Cách thiết lập được khuyến nghị

Chạy UpSnap trên máy hoạt động 24/7 — router, Raspberry Pi, NAS, hoặc một node nhỏ luôn bật. Máy đó trở thành WoL relay: nhận yêu cầu từ web UI rồi gửi magic packet đến subnet của máy đích.

Đây là chi tiết mà hầu hết các hướng dẫn bỏ qua: Docker container cần dùng host networking (network_mode: host), hoặc phải ở cùng mạng Layer 2 với các máy bạn muốn bật. Magic packet của Wake-on-LAN hoạt động theo kiểu broadcast — không đi qua được các subnet khác. Container trên mạng bridged đơn giản là không thể với tới máy vật lý của bạn.

Host networking kém isolated hơn so với bridge một chút, nhưng trên mạng gia đình đáng tin cậy thì đánh đổi này không đáng lo. Cách thiết lập này đã hoạt động ổn định trên năm node suốt nhiều tháng.

Hướng dẫn triển khai

Bước 1: Bật Wake-on-LAN trên máy đích

Hãy chắc chắn các máy bạn muốn bật từ xa đã kích hoạt WoL. Cần thực hiện ở hai nơi: BIOS và hệ điều hành.

BIOS: Vào BIOS/UEFI → tìm “Wake on LAN”, “Power On by PCI-E”, hoặc tương tự → bật lên.

Linux (kiểm tra trạng thái hiện tại):

sudo apt install ethtool   # nếu chưa cài
sudo ethtool eth0 | grep Wake

Bạn cần thấy Wake-on: g. Nếu hiển thị d, hãy bật lên:

sudo ethtool -s eth0 wol g

Cài đặt này sẽ bị reset khi khởi động lại. Để giữ nguyên sau reboot, thêm script NetworkManager dispatcher. Trên Ubuntu:

cat /etc/NetworkManager/dispatcher.d/99-wol
#!/bin/sh
ethtool -s eth0 wol g

Bước 2: Thu thập địa chỉ MAC

Lấy địa chỉ MAC của network interface trên mỗi máy:

ip link show eth0
# Tìm dòng "link/ether": link/ether aa:bb:cc:dd:ee:ff brd ff:ff:ff:ff:ff:ff

Ghi lại các địa chỉ này — bạn sẽ cần khi thêm thiết bị vào UpSnap.

Bước 3: Tạo file Docker Compose

Trên máy luôn bật, tạo thư mục và file compose:

mkdir -p ~/homelab/upsnap
cd ~/homelab/upsnap
nano docker-compose.yml
services:
  upsnap:
    image: ghcr.io/seriousm4x/upsnap:4
    container_name: upsnap
    network_mode: host
    restart: unless-stopped
    volumes:
      - ./data:/app/pb_data
    environment:
      - TZ=Asia/Ho_Chi_Minh
      # Tùy chọn: chỉ định network interface cho WoL packet
      # - UPSNAP_SCAN_RANGE=192.168.1.0/24
      # - UPSNAP_INTERVAL=@every 5m

Một số điểm quan trọng về cấu hình này:

  • network_mode: host — bắt buộc. Không có cái này, WoL packet sẽ không đến được máy vật lý
  • ghcr.io/seriousm4x/upsnap:4 — ghim vào major version 4 để tránh các thay đổi breaking không mong muốn
  • ./data:/app/pb_data — lưu trữ database PocketBase (danh sách thiết bị, người dùng, cài đặt) qua các lần restart container
  • TZ — đặt theo múi giờ của bạn để các lịch bật máy kích hoạt đúng giờ địa phương

Bước 4: Khởi động container

docker compose up -d
docker compose logs -f upsnap

Theo dõi log cho đến khi thấy dòng Server started at http://0.0.0.0:8090. UpSnap chạy trên cổng 8090 theo mặc định.

Bước 5: Thiết lập ban đầu

Truy cập http://<ip-máy-chủ>:8090 trên trình duyệt. Lần đầu truy cập sẽ hiện prompt tạo tài khoản admin. Dùng mật khẩu mạnh — dashboard này có thể bật máy trên mạng của bạn, nên không nên để ai vào được một cách tình cờ.

Sau khi đăng nhập, vào Settings và cấu hình:

  • Network interface: chọn interface kết nối cùng subnet với các máy đích (ví dụ: eth0, enp3s0)
  • Ping interval: tần suất UpSnap kiểm tra máy có online không (mặc định 5 phút là ổn)

Bước 6: Thêm thiết bị

Nhấn Add Device và điền vào:

  • Name: tên dễ nhớ (ví dụ: “NAS”, “Máy Gaming”, “Dev Server”)
  • IP address: IP tĩnh hoặc DHCP reservation của máy đích
  • MAC address: từ Bước 2
  • Port: 9 (cổng WoL chuẩn) — thường để nguyên là được

Lưu thiết bị. UpSnap bắt đầu ping ngay lập tức và hiển thị trạng thái (Online / Offline) trên dashboard.

Bước 7: Kiểm tra Wake-on-LAN

Tắt một trong các máy đích. Chờ UpSnap hiển thị trạng thái Offline. Sau đó nhấn vào biểu tượng nút nguồn — UpSnap gửi magic packet và bắt đầu polling. Trong vòng 30–60 giây (tùy thời gian POST), máy sẽ khởi động lại và chấm trạng thái chuyển sang màu xanh.

Tùy chọn: Lên lịch bật máy tự động

UpSnap hỗ trợ lịch theo kiểu cron cho từng thiết bị. Để bật máy build server mỗi ngày làm việc lúc 8 giờ sáng:

  • Mở cài đặt thiết bị
  • Trong mục Schedule, bật lên và nhập biểu thức cron: 0 8 * * 1-5

Những máy chỉ cần chạy trong giờ làm việc có thể tắt hoàn toàn vào những lúc khác. Không cần can thiệp thủ công, không lãng phí điện qua đêm.

Tùy chọn: Reverse Proxy với HTTPS

Để truy cập UpSnap từ bên ngoài mạng nội bộ, đặt nó sau một reverse proxy — Nginx Proxy Manager hoặc Traefik đều dùng được. Vì UpSnap dùng network_mode: host, nó bind trực tiếp vào cổng 8090 trên host. Proxy về http://127.0.0.1:8090.

Nếu expose ra internet, hãy thêm xác thực ở tầng proxy nữa. UpSnap đã có auth tích hợp, nhưng bất cứ thứ gì có thể bật nguồn phần cứng từ xa đều xứng đáng có nhiều hơn một lớp kiểm soát truy cập.

Xử lý sự cố thường gặp

Máy không chịu bật

  • Xác nhận WoL đã bật ở cả BIOS lẫn hệ điều hành (output ethtool hiển thị g)
  • Xác nhận container UpSnap đang dùng network_mode: host
  • Xác nhận đúng network interface đã được chọn trong cài đặt UpSnap
  • Thử gửi packet thủ công từ host: wakeonlan <MAC> — nếu cách này chạy được mà UpSnap thì không, đó là vấn đề chọn interface trong UpSnap

Thiết bị luôn hiển thị Offline dù đang chạy

  • UpSnap dùng ICMP ping để kiểm tra trạng thái — hãy chắc chắn máy đích cho phép ping (không bị firewall chặn)
  • Trên UFW: sudo ufw allow in proto icmp

Kết nối tất cả lại với nhau, bạn có một dashboard gọn gàng, chuyên dụng hiển thị toàn bộ máy trong HomeLab chỉ trong một trang. Một cú nhấp để bật bất kỳ máy nào — từ điện thoại, laptop, hay bất kỳ đâu có trình duyệt. Không còn phải đi bộ ra phòng server nữa.

Share: