LanLens 實戰：自託管區網設備監控，把家裡網路當資料中心管

家裡那組 24 port switch 撐了三年，後面陸續多了 NAS、軟路由、Home Assistant、兩台 Proxmox、一堆 ESP32，還有越來越多吃 PoE 的 IP cam。某天有台機器吃了一個我不認得的 IP，翻 router 的 DHCP lease table 沒翻出個所以然，最後是用 arp-scan 對著網段慢慢比對 MAC vendor 才找到——是去年隨手插上的一張舊 Wi-Fi 模組。

家用環境跟資料中心的差異，從來不是規模，而是有沒有把資產當回事。一台 IP cam 上線時你可能不在家，更新韌體時 MAC 沒換但 IP 換了，過了半年連你自己都忘記它是誰。Homelab 玩到一定階段都會撞到這個問題：服務愈來愈多、設備愈來愈雜，但「網段裡到底有什麼」反而變成黑盒。

這篇要記錄的是 LanLens——一個用單一 Docker container 就跑得起來的自託管區網監控儀表盤。它做的事情其實不複雜：持續 ARP 掃描、用 MAC vendor 認 device、建表、給每台機器加 metadata、然後讓你能直接從 UI 開 SSH 過去。但工具的價值不在於它解的問題多新穎，而在於它剛好補上家用 / 小型網路一直缺的那一塊。

一、為什麼需要區網監控工具

router 自帶的設備清單通常只有三件事：IP、MAC、hostname（如果裝置有送的話）。對於排查問題基本上不夠用。常見的痛點大概是這幾類：

新裝置悄悄上線：可能是有人連了 Wi-Fi，也可能是某個 IoT 自動換 IP，沒有通知就無感
MAC vendor 看不懂：拿到一串 b8:27:eb: 大概知道是樹莓派，但 00:11:32: 是 Synology？是 QNAP？沒有 vendor DB 一律靠 google
跨網段沒有統一視角：管理 VLAN 的人都懂，10.0.10.x 跑 IoT、10.0.20.x 跑 server、10.0.30.x 跑 guest，要在同一張表看完，router 的 UI 通常做不到
裝置 metadata 沒地方記：哪台是 backup server、哪個 IP 是給哪個 VM 預留的、哪個 IP 還沒分配——這些「文件化」工作通常散落在 Notion 或某個 Excel
想直接連線：找到 IP 後還要切到 terminal 開 SSH、或開瀏覽器打 https://，多兩三步就懶

成熟方案像 NetBox、LibreNMS 都能做，但對家用來說重得離譜。Pi-hole 只看 DNS query、Fing 偏移動端、router 的內建工具又太陽春。LanLens 把這個夾縫填得相當精準。

二、LanLens 的技術定位

從專案 README 可以看出它的選型很現代：

層級	技術
後端 API	FastAPI + SQLAlchemy + APScheduler
儲存	SQLite（預設）/ MariaDB / MySQL
前端	React + TypeScript + Tailwind
掃描引擎	scapy（ARP）+ nmap（port scan）
部署	單一 Docker container（host network 模式）
通知	Telegram Bot API
Web Server	nginx + uvicorn

關鍵在 host network 模式。ARP 是 L2 廣播，必須直接打到實體網卡，bridge 模式下 scapy 沒辦法送 raw Ethernet frame，container 也看不到真實的 LAN segment。這是它跟一般 HTTP-only self-hosted 工具最大的部署差異——你不能像 Uptime Kuma 那樣丟到 Cloudflare Tunnel 後面就忘掉。

License 是 MIT，現役版本到 1.4.3（2026-04-21 release），更新節奏算積極。

下面這張是專案 dashboard 主畫面：

LanLens Dashboard
圖片來源：LanLens GitHub repo

三、安裝與啟動

3.1 Docker 部署

最快路徑就是 docker run 一條指令。先準備 secret key 和資料夾：

# 隨機產生 32-byte hex key
openssl rand -hex 32

# 建立資料目錄
mkdir -p ~/lanlens/data && cd ~/lanlens

跑起來：

docker run -d \
  --name=lanlens \
  --restart=unless-stopped \
  --network=host \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  -v $(pwd)/data:/data \
  -e SECRET_KEY=<剛剛產的 hex 字串> \
  -e DEFAULT_ADMIN_PASSWORD=admin \
  -e LANLENS_PORT=7765 \
  -e BACKEND_PORT=17765 \
  -e TZ=Asia/Taipei \
  alexrosbach/lanlens:latest

注意三個東西：

--network=host：ARP 掃描必需，沒得選
--cap-add=NET_ADMIN / NET_RAW：scapy 送 raw socket 要用
host 網路下不需要 -p map port，HTTP 直接走 LANLENS_PORT 開的 port

如果 host 跑的是 macOS 或 Windows Docker Desktop，host network 行為不一致，建議直接丟 Linux server 跑（NAS、軟路由、Proxmox VM、Raspberry Pi 都可以）。

也可以用 docker-compose，比較好維護：

services:
  lanlens:
    image: alexrosbach/lanlens:latest
    container_name: lanlens
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - ./data:/data
    environment:
      - SECRET_KEY=<hex 32 bytes>
      - DEFAULT_ADMIN_PASSWORD=admin
      - LANLENS_PORT=7765
      - BACKEND_PORT=17765
      - TZ=Asia/Taipei
    healthcheck:
      test: ["CMD-SHELL", "curl -fs http://localhost:$${LANLENS_PORT:-7765}/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s

啟動後瀏覽器打 http://<host-ip>:7765，預設帳密 admin / admin，第一次登入會強制改密碼。

3.2 必要環境變數

變數	說明	必填
`SECRET_KEY`	至少 32 字元隨機字串，用於 Fernet 加密憑證	是
`DEFAULT_ADMIN_PASSWORD`	初始 admin 密碼，登入後須改	否（預設 admin）
`LANLENS_PORT`	UI 對外 HTTP port	否（預設 7765）
`BACKEND_PORT`	內部 FastAPI port	否（預設 17765）
`DB_PATH`	SQLite 路徑	否（預設 `/data/lanlens.db`）
`DATABASE_URL`	切換到 MariaDB/MySQL 用	否
`TZ`	容器時區	否

SECRET_KEY 是硬性要求，弱 key 會被 app 拒絕啟動，這算是滿合理的安全預設。app 啟動後 key 不能換，換了等於把所有加密過的 SSH 憑證一起丟掉。

如果家裡網段大、需要多人協作或要做備份備援，可以把 SQLite 換成 MariaDB：

environment:
  - DATABASE_URL=mysql+pymysql://lanlens:<password>@mariadb:3306/lanlens
depends_on:
  - mariadb

四、核心功能

4.1 自動掃描與識別

底層用的是 ARP 廣播——對網段內每個 IP 送 who-has，收到 reply 就記下 IP↔MAC 對應。這套機制比 ICMP ping sweep 可靠很多，因為很多 IoT 裝置防火牆會擋 ICMP，但不會擋 ARP（擋了它連 router 都連不上）。也因為 ARP 是 L2，跨 subnet 就掃不到了，這就是為什麼 LanLens 走 host network 模式：要直接黏在實體網卡上才能看到所有 reply。

掃描週期由 APScheduler 排，UI 上可以設定 scan range（自動偵測 host subnet 為預設）和頻率。多網段環境下可以分別建立掃描範圍，例如 10.0.10.0/24、10.0.20.0/24、10.0.30.0/24 同時掃。

發現新 device 時，LanLens 會用內建的 OUI database 把 MAC prefix 翻成 vendor name。Apple, Inc.、Espressif Inc.、Synology Incorporated 這類自動就帶出來，不用自己 google。OUI 資料是 offline 的，不會跑去打 IEEE API，掃描不會因為網路不通而失準。

第二層是 DHCP badge 偵測：如果裝置的 IP 是由 DHCP 分配的，UI 會打上 DHCP 標籤，跟 static IP 一眼分得出來。對排查「這個 IP 是不是會跳」很有用——尤其是 IoT 裝置常常 DHCP lease 一過就換 IP，但 MAC 不會變，LanLens 會把這台裝置的 IP 變化記下來，而不是當成一台新機器。

4.2 裝置文件化

這是 LanLens 跟一般 network scanner 最不一樣的地方。每台 device 都可以加自定義欄位：

裝置名稱（覆蓋自動辨識的 vendor 名）
角色 / 用途（例如「Plex backend」「IoT VLAN gateway」）
服務清單（記錄這台機器跑了哪些 port / service）
自由 metadata（自由 key-value）
標籤、分類、備註

Network Segment 也是一等公民：可以定義多個網段、給每個網段配色、設 IP range，dashboard 會顯示每個網段的使用率。對 VLAN 切得細的家用環境很實用。

Network Segments
網段管理畫面，每個網段獨立顯示使用率與顏色標記。圖片來源：LanLens GitHub repo

把這些欄位填滿之後，LanLens 等於成了 home network 的 source of truth。下次有問題，直接查 LanLens 而不是翻 router、翻 NAS、翻 Notion。

4.3 SSH / Web UI 直連

device 詳細頁有 quick action 按鈕：

SSH：開新 tab 帶 ssh://user@ip（會交給作業系統的 default handler）
HTTP / HTTPS：直接開 web UI，適合 NAS、router、印表機
RDP：Windows 機器一鍵丟到 Remote Desktop client

更進一步是 Deep Scan：如果你在 LanLens 裡幫機器存了 SSH（Linux）或 WinRM（Windows）憑證，它會用這組憑證連進去抓：

硬體資訊（CPU、RAM、磁碟）
OS 版本
跑著的 service
container 清單（Docker / Podman）
虛擬化環境（自動偵測 Proxmox、KVM、Hyper-V，並列出 guest VM）

憑證用 Fernet 對稱加密儲存，加密 key 由 SECRET_KEY 衍生。session 是 server-side cookie，httpOnly。對家用環境來說安全強度算是夠用了，但這也是為什麼前面強調 SECRET_KEY 不能弱、不能漏。

下圖是某台 device 的 detail view：

Device Detail
Device 詳細頁可看到 deep scan 抓到的硬體與服務清單。圖片來源：LanLens GitHub repo

五、實測：掃自己家裡的網段

跑起來後第一輪掃描，2 分鐘內把 192.168.1.0/24 整段掃完，抓到 31 台 device。意外發現：

3 台不認得的裝置：兩台是去年裝修時電工裝的 PoE switch（vendor TP-Link），一台是某個瑜珈墊送的智慧體重計，安裝完就忘了
Hostname 缺很多：自己組的 Linux 機器全都有 hostname，但 IoT 類裝置一律空白，這時 vendor 認得就很關鍵
MAC 重複的裝置：一台筆電同時出現在無線跟有線兩個 IP，LanLens 會把它合併成同一個 device entry，IP 列出兩個
VM 跟 host 區分明確：兩台 Proxmox host 各自跑了 5 台 VM，deep scan 下去自動把 hypervisor relationship 拉出來，dashboard 直接看到誰跑誰

幫所有 device 加完 metadata（角色、服務、備註），花了大約半小時。完成後我把 home-network.xlsx 直接刪了，後面就只看 LanLens。寫入過程也順便清掉了一些「IP 預留沒用到」的 ghost entry，這種清理動作不開儀表盤是不會主動做的。

Telegram 通知也設了，新裝置上線會推一條訊息進私人 channel：MAC、vendor、IP、第一次看到的時間。實測有效，半夜手機某個被遺忘的 ESP32 因為韌體更新換 IP，馬上跳通知。

下圖示範了 device 文件化頁面，每台機器除了基本資訊還能加上自定義欄位：

Device Documentation
Home Assistant 主機的 documentation 頁面，包含服務清單、metadata、連線快捷按鈕。圖片來源：LanLens GitHub repo

實測下來幾個值得注意的細節：

首輪掃描完成後，UI 不會「鎖定」裝置清單——後續每輪掃描結果會增量合併，原本填過的 metadata 不會被覆蓋
離線裝置也會留——某台機器關機時不會從清單消失，只會標記成 offline。這個行為比預期合理，避免家裡冷門設備被掃掉
重置密碼有 CLI：忘記密碼的時候，docker exec -it lanlens reset-password --password "新密碼" 直接救回來，不用砍資料庫

六、vs. 其他方案（Pi-hole / Fing / NetBox）

把幾個常被拿來比較的工具排在一起看：

工具	主要用途	自託管	文件化能力	適合對象
LanLens	LAN 設備發現 + 文件化 + 連線	是	強	Homelab / SOHO
Pi-hole	DNS 過濾 + query log	是	弱（只列 client）	廣告封鎖
Fing	LAN 設備發現（行動為主）	部分（雲端帳號）	中	一般家庭
NetBox	機房 DCIM + IPAM	是	極強	企業 / 資料中心
LibreNMS	SNMP-based 監控	是	中	ISP / 大型網路

LanLens 卡在 Fing（太消費級、要綁帳號）跟 NetBox（太重、學習曲線陡）中間。它沒打算做完整的 IPAM、不做 SNMP、不做流量圖；它做的是「家用 / 小型網路想要一份能維護的設備清冊」這件事。

如果你已經在用 Pi-hole，LanLens 跟它完全不衝突——一個管 DNS、一個管 device 清冊，可以並存。如果你想要 NetBox 等級的 IPAM，LanLens 不夠用，但對 95% 的 Homelab 玩家來說，LanLens 反而剛好。

七、適合與不適合的場景

適合：

家裡 / 小辦公室的 LAN，裝置數在 20～200 台之間
有切 VLAN，想統一視角看全部網段
Homelab 玩家，需要 SSH 進 Linux server / 進 Proxmox 看 VM
想要新裝置上線通知，但又不想架完整 SIEM
對 NetBox 太重、router 內建工具太弱有共鳴

不適合：

純消費級用戶（直接用 router 自帶的就好）
多 site / 跨地區網路（LanLens 是 single LAN scope）
需要 NetFlow、SNMP、頻寬圖表的（拿 LibreNMS 或 Zabbix）
部署環境只能用 bridge / overlay 網路（ARP 掃描廢掉）
法遵 / 稽核要求嚴格的企業環境（憑證儲存方案太單純）

實務上我會把 LanLens 跟 Uptime Kuma 搭配：LanLens 看 LAN 上有什麼、Uptime Kuma 看 service 有沒有活著。兩個都是 single Docker container 就跑得起來，部署成本低、目標分工清楚。

八、小結

LanLens 是那種「想做的東西就那麼多，但每件都做得不錯」的專案。沒有花俏的 AI、沒有過度設計的微服務架構，後端就是一個 FastAPI、前端就是一個 React SPA，外面包一層 nginx，全部塞進一個 container。

對 Homelab 用戶最實際的價值是：讓家裡網路第一次有了「完整視角」。以前散在 router、NAS、Proxmox 三邊的資訊終於在同一頁看得到，每台機器有自己的卡片、有 metadata、有 SSH 直連按鈕。一旦上手，回不去用 router 內建那張表。

部署門檻只有「需要 host network 模式」這一條，但這條其實是必然——任何 ARP-based 工具都會撞到。願意接受這個前提，剩下的就是 docker run 一條指令的事。

值得花 30 分鐘試試。

參考資料

原始介紹文：自托管网络监控工具 LanLens（杨浦老苏）
LanLens GitHub repo：https://github.com/AlexRosbach/LanLens
Docker Hub：https://hub.docker.com/r/alexrosbach/lanlens
Quick Start 文件：https://github.com/AlexRosbach/LanLens#quick-start
Deep Scan 權限說明：https://github.com/AlexRosbach/LanLens#deep-scan--required-permissions