Homelable là ứng dụng self-hosted giúp biến sơ đồ homelab từ một bản vẽ tĩnh thành bản đồ hạ tầng có dữ liệu thiết bị, kiểm tra online/offline, tài liệu vận hành và tích hợp Proxmox. Điểm mạnh lớn nhất của nó là kết hợp sơ đồ logic, rack vật lý và ghi chú/runbook trong cùng một giao diện; nhưng không nên nhầm nó với hệ thống giám sát metrics hay CMDB tự động hoàn chỉnh.
Tóm tắt
Homelable giải quyết một vấn đề quen thuộc: sau nhiều năm thêm NAS, máy chủ, container, VM, thiết bị mạng và smart home, thông tin “cái gì chạy ở đâu, kết nối với cái gì, cấu hình vì sao như vậy” bị chia ra giữa bookmark, ghi chú và trí nhớ. Ứng dụng cung cấp canvas kéo-thả, quét mạng đưa thiết bị tìm được vào hàng chờ, kiểm tra trạng thái, nhập inventory Proxmox và thiết bị Zigbee/Z-Wave, sơ đồ rack, thư viện Markdown và API/MCP.[1][2]
Phiên bản mới nhất tôi kiểm tra là 3.7.0, phát hành ngày 7/11/2026. Bản này bổ sung sao lưu/đồng bộ diagram và tài liệu qua Git, trang tổng quan Documentation, đồng bộ nhiều Proxmox server và một số sửa lỗi nhập inventory.[3]
Các nhóm chức năng chính
1. Sơ đồ mạng có thông tin trạng thái
Bạn có thể tạo nhiều canvas như “Network”, “Services”, “Smart home” hoặc “Rack”, thêm node/zone/đường kết nối và tự bố trí. Scanner dùng Nmap quét CIDR được cấu hình, nhận diện dịch vụ theo port rồi đưa thiết bị mới vào Pending Devices. Người quản trị chọn thiết bị nào được đưa vào bản đồ, ẩn hoặc bỏ qua những kết quả không cần.[2][6]
Các phép kiểm tra trạng thái gồm ping, TCP, HTTP/HTTPS, SSH, Prometheus /metrics và /health. Điều này cho biết endpoint có phản hồi theo điều kiện đã cấu hình, nhưng không thay thế thu thập metrics, alerting theo ngưỡng, lưu lịch sử dài hạn hay phân tích log như Prometheus/Grafana hoặc hệ thống monitoring chuyên dụng.[2][7]
2. Import Proxmox: phần có giá trị nhất với homelab của bạn
Homelable đọc Proxmox qua REST API và tạo các node cho host, VM, LXC, kèm trạng thái, CPU, RAM, disk, IP nếu có dữ liệu. VM có thể lấy IP qua QEMU Guest Agent; LXC lấy từ cấu hình mạng tĩnh. Khi import lại, ứng dụng cập nhật các mục đã có thay vì xóa chúng; có thể bật auto-sync để nhập định kỳ.[5]
Với môi trường có Proxmox và nhiều container như của bạn, đây có thể là cách nhanh để lập bản đồ host → VM/LXC rồi bổ sung thủ công các dịch vụ, NAS, switch, router và quan hệ phụ thuộc mà API Proxmox không biết.
Bảo mật token: tài liệu khuyến nghị tạo API token riêng, để privilege separation và gán vai trò PVEAuditor chỉ đọc. Token nhập cho một lần import không được lưu; nếu dùng auto-sync, token nằm trong .env phía server và được giữ trong bộ nhớ của ứng dụng. Không dùng token root có quyền ghi chỉ để đọc inventory.[5]
3. Rack canvas và sơ đồ vật lý
Rack canvas mô phỏng tủ rack với đơn vị U, thiết bị, mặt trước, vị trí cổng và patch cable nối port-to-port. Có thể nhập thiết bị từ inventory vào rack; kết nối vật lý hữu ích khi cần nhớ cổng switch/patch panel thay vì chỉ biết máy nào nối với máy nào ở mức logic.[2]
Giá trị phần này phụ thuộc việc bạn có rack vật lý hoặc muốn quản lý patching. Với vài mini-PC và thiết bị đặt rải rác, đây có thể là tính năng hay nhưng không nhất thiết phải dùng.
4. Tài liệu ngay cạnh thiết bị
Mỗi thiết bị có thể có trang Markdown được tạo ban đầu từ thông tin scan, cùng thư viện để ghi runbook, quyết định thiết kế, quy trình backup/restore và ghi chú sự cố. Có liên kết wiki giữa trang, tìm kiếm, tag và lịch nhắc review; lịch sử lưu tối đa 50 phiên bản theo tài liệu dự án. Tài liệu được lưu riêng, không tự ghi đè khi thông tin thiết bị thay đổi; ứng dụng đưa cảnh báo để người dùng quyết định cập nhật.[2]
Đây là tính năng thực dụng: sơ đồ cho biết máy ở đâu, runbook giải thích cách vận hành và khôi phục. Nhưng phải duy trì các trang thủ công và tạo backup của dữ liệu Homelable; bản 3.7.0 bổ sung Git sync để đẩy diagram và documentation vào repository do mình quản lý.[3]
5. Smart home và AI/MCP
Ứng dụng có thể nhập topology từ Zigbee2MQTT và Z-Wave JS UI qua MQTT, đồng thời cung cấp MCP server để client AI đọc topology, lịch sử scan và inventory; một số tool còn có thể tạo/sửa/xóa node, trigger scan, tạo rack và patch cáp.[2]
MCP là tính năng mạnh nhưng có rủi ro vận hành: đây không chỉ là “hỏi AI trạng thái homelab”, mà có thể trao cho agent quyền chỉnh sửa sơ đồ, dữ liệu thiết bị hoặc kích hoạt scan. Chỉ bật khi có nhu cầu, đặt key riêng đủ mạnh, giới hạn port trong LAN/tunnel tin cậy và chỉ cấp quyền cho client cần thiết. Tài liệu nói rõ MCP server không được phơi ra Internet.[2]
Cài đặt và cách bắt đầu
Có hai chế độ:
- Full mode: chạy backend và frontend, cần cho network scan, Proxmox import, inventory, tài liệu, live status và MCP.
- Standalone/frontend-only: chỉ vẽ sơ đồ trên trình duyệt và lưu canvas trong
localStorage; không có scanner/import/backend. Phù hợp thử giao diện hoặc xuất hình, không phải cài đặt đầy đủ.[4][7]
Bản Docker dùng image dựng sẵn trên GHCR cho linux/amd64 và linux/arm64; dự án cũng có hướng dẫn cài Proxmox LXC hoặc bare-metal Debian/Ubuntu. Quick start Docker chính thức đưa thông tin đăng nhập ban đầu admin/admin, nên đổi password trước khi cho thiết bị khác trong LAN truy cập và tuyệt đối không mở giao diện ra Internet với mặc định đó.[4]
Quy trình triển khai khuyến nghị:
- Dùng LXC riêng hoặc Docker host riêng trong LAN; pin image theo release cụ thể thay vì dùng tag
latestcho môi trường ổn định. - Đổi tài khoản mặc định, chỉ bind/publish cổng giao diện tới mạng tin cậy; nếu truy cập từ xa, dùng VPN hoặc reverse proxy HTTPS có xác thực.
- Tạo Proxmox API token riêng với
PVEAuditor, chỉ bật quyền auto-sync nếu thực sự cần. - Bắt đầu bằng import Proxmox; kiểm tra host/VM/LXC và IP trước khi bật scan CIDR.
- Quét subnet được phép quản trị của chính bạn; duyệt Pending Devices thay vì tự động coi mọi kết quả là thiết bị đã xác minh.
- Tạo runbook cho các dịch vụ quan trọng và bật Git sync/backup theo hướng dẫn trước khi coi Homelable là nơi lưu tài liệu vận hành.
Giới hạn và điều cần kiểm tra
Network discovery không thể biết toàn bộ mạng
Kết quả Nmap phụ thuộc subnet được cấu hình, khả năng route, firewall, VLAN, port đang mở và quyền raw socket. Dịch vụ ở port không chuẩn có thể cần deep scan; scan từ Docker bridge cũng có thể không nhìn thấy MAC vì giới hạn Layer 2, khiến thiết bị đổi DHCP/IP có nguy cơ xuất hiện như bản ghi mới. Host networking có thể giúp một số trường hợp nhưng làm thay đổi ranh giới mạng và cần đánh giá bảo mật riêng.[4][6]
“Online” không phải là “dịch vụ khỏe”
Ping hoặc TCP connect thành công chỉ xác nhận một điều kiện kết nối. Ngay cả HTTP 2xx–4xx (theo logic status check <500 trong README) cũng chưa chứng minh ứng dụng xử lý đúng nghiệp vụ. Chọn /health endpoint có ý nghĩa, nếu dịch vụ có; tiếp tục dùng monitoring riêng cho metric, alert và lịch sử sự cố.[2]
Quyền truy cập và bề mặt quản trị
Không để mật khẩu mặc định, API token Proxmox, key Git hoặc MCP key trong file compose chia sẻ công khai. Đặt Homelable trong LAN, giới hạn firewall và có kế hoạch backup database, .env/secret và các file dữ liệu. Docs/API shape có thể không nằm sau đăng nhập theo README, nên không nên công khai service chỉ vì endpoint dữ liệu yêu cầu auth.[2][4]
Tốc độ phát triển đồng nghĩa phải theo dõi cập nhật
Repo có nhiều thay đổi và bản 3.7.0 bổ sung Git sync; các release gần đây cũng sửa những vấn đề import/scan và MCP. Điều này cho thấy dự án đang được phát triển tích cực, nhưng cũng khiến việc nâng cấp cần đọc changelog, backup trước và xác minh sau khi update.[2][3]
Nhận xét riêng cho homelab Proxmox của bạn
Mức phù hợp: cao nếu mục tiêu là inventory, sơ đồ và runbook; trung bình nếu kỳ vọng thay monitoring. Bạn đã có Proxmox, nhiều LXC dịch vụ và NAS/network devices. Import tự động host/VM/LXC có thể giảm đáng kể công nhập ban đầu; sau đó vẽ các quan hệ mà Proxmox không biểu diễn, chẳng hạn dịch vụ nào phụ thuộc NAS, reverse proxy nào trỏ tới container nào, hoặc switch/port vật lý.
Tôi sẽ chạy thử song song trên một LXC nhỏ riêng, không thay cấu hình hay cài đặt Proxmox hiện tại. Lưu ý yêu cầu tài nguyên chính thức cần đối chiếu với INSTALLATION.md trước khi cấp CPU/RAM; trong bài review này tôi không đưa con số RAM của container làm kết luận vì chưa xác minh từ tài liệu cài đặt cụ thể. Ưu tiên chỉ đọc Proxmox, không mở quyền ghi, và chưa bật MCP trong giai đoạn đầu.
Pilot thực tế đề xuất
- Import một Proxmox host và một nhóm LXC/VM trước; đối chiếu số lượng, hostname, trạng thái, RAM/CPU và IP với giao diện Proxmox.
- Bổ sung thủ công NAS, switch, router, dịch vụ quan trọng cùng quan hệ logic; không kỳ vọng Nmap tự hiểu dependency.
- Cấu hình vài health check đại diện: một HTTP
/health, một TCP port, một thiết bị ping; cố tình dừng một dịch vụ thử để xem trạng thái cập nhật và false positive. - Viết 3 runbook quan trọng (khôi phục backup VM, kiểm tra NAS share, khởi động dịch vụ reverse proxy) rồi thử Git sync/restore trên bản sao.
- Đo thời gian cập nhật inventory, độ chính xác IP, số thiết bị trùng sau DHCP thay đổi, tài nguyên container và khả năng khôi phục database/config.
- Chỉ bật scanner trên subnet quản trị mình sở hữu; xem Nmap output và Pending list trước khi approve.
Kết luận
Homelable đáng thử như một bản đồ sống kiêm sổ tay vận hành cho homelab: Proxmox import giúp khởi tạo inventory, canvas thể hiện kết nối, rack canvas ghi lại patching, tài liệu/runbook giúp lưu ngữ cảnh. Bản Git sync mới tăng giá trị cho backup và lịch sử thay đổi.
Nhưng nó không phải công cụ thay thế Proxmox, Nmap, Prometheus/Grafana, hệ thống log hay backup. Dữ liệu discovery cần người rà soát; trạng thái online đơn giản không thay health monitoring; và token/MCP cần được giữ trong LAN với quyền tối thiểu.
Khuyến nghị: cài pilot LXC riêng, import Proxmox bằng token PVEAuditor chỉ đọc, thử trên một phần nhỏ trước, sau đó mới quyết định có dùng làm inventory/runbook chính hay không. Với homelab của bạn, lợi ích có khả năng đến nhiều nhất từ việc nhìn nhanh toàn bộ VM/LXC và giữ tài liệu khôi phục ngay cạnh từng dịch vụ.
Để lại một bình luận