Hass Panel 開源 Home Assistant 面板實測，補好帳號層再上線

Facebook Line Messenger Telegram

燈光、冷氣、窗簾、攝影機、感測器，Home Assistant 都管得到，官方介面卻常讓人在層層選單裡迷路。Hass Panel 這個開源專案想把這件事變簡單：一頁可以拖曳排列的儀表板，二十幾種卡片對應常見設備，手機還能裝成 App 使用。

把結論放前面講。裝在 Home Assistant OS 的附加元件裡，或只在自家區域網路用 Docker 自架，目前這個版本可以用；想照官方文件教的把它開到網際網路上，出廠狀態撐不住。我把最新版 v1.4.1 的後端在本機跑起來，實際打過它的帳號相關端點：註冊不用任何憑證、密碼以無鹽 MD5 存進資料庫、簽發登入憑證的金鑰則直接寫在公開 repo 的設定檔裡。這幾件事都查得到出處，下面逐項攤開。

先說結論：怎麼裝，決定它有多安全

同一套 Hass Panel，三種裝法是三種風險等級。

附加元件（Add-on）模式最省事，也最推薦。它在 Home Assistant 裡走 ingress 通道，設定檔明寫掛上 HA 的認證 API，等於你的 Home Assistant 帳號擋在最前面，面板自身的帳號體系退居第二層。

Docker 自架是第二種。官方指令用 host 網路模式直接跑，起來後 5123 連接埠對所在網段開放。家裡路由器後面自己用，風險可控；住在宿舍或辦公室共享網路，就要意識到同網段的人都連得到。

第三種是官方 FAQ 明文教學的對外開放：通訊埠轉送，或用 frp、Ngrok 這類穿隧服務，FAQ 的保全建議是 HTTPS 加強密碼。問題在於帳號層的實作讓這兩道防線不夠用，原因在下面兩節。

本機實測帳號層：註冊不鎖、密碼是 MD5、token 可以自己簽

我在本機把 v1.4.1 的後端跑起來（這套環境沒有接 Home Assistant，也沒跑前端），對 127.0.0.1 逐一發請求。

先看註冊端點。我不帶任何登入憑證，直接向 /api/auth/register 送一組使用者名稱和密碼，伺服器回 200，帳號就建好了。程式碼裡其實有一個邀請碼模組，但註冊流程沒有引用它，等於沒接線；換句話說，只要陌生人連得到面板，他就能自己開帳號。

另一條線索在資料庫裡。直接打開 SQLite 檔看 users 表，密碼欄存的值恰好等於 md5(“password”) 的雜湊結果，也就是瀏覽器端做完 MD5 後被原樣入庫。登入時後端拿同樣的等值比較判斷，全程沒有加鹽，也沒有慢雜湊。

最關鍵的則是金鑰。我用註冊的帳號登入，拿到一枚效期三十天的 JWT 通行證，拿 repo 設定檔裡的出廠金鑰對它做簽章驗證，一致；接著我用同一把金鑰在本地自己簽一枚 token，完全不走登入，帶去呼叫需要登入的 /api/users，伺服器照樣回 200，把使用者列表給了我。

我送出的請求	伺服器回應
匿名查詢初始化狀態（GET /api/common/init_info）	200，回報系統尚未初始化
匿名註冊（POST /api/auth/register）	200，帳號建立成功
用該帳號登入（POST /api/auth/token）	200，發出三十天效期 JWT
以出廠金鑰離線簽造的 token 呼叫 /api/users	200，回傳使用者列表
匿名檔案上傳（POST /api/common/upload）	422，卡在參數驗證而非授權牆

最後一列也值得看：上傳端點的路由宣告沒掛授權檢查，匿名請求拿到 422 參數驗證錯誤，連 401 都沒出現，代表請求根本沒先過授權這關。這些行為出自 v1.4.1 的原始碼，也是停更前的最後一版。

為什麼出廠金鑰比弱密碼更麻煩

JWT 的機制用白話講：登入成功後，伺服器發給你一張簽過章的通行證，之後每個請求帶著它就行。Hass Panel 用 HS256 演算法簽章，這類做法簽章與驗章共用同一把金鑰，而這把鑰匙印在 backend/config/prod.toml 裡，開發設定檔 dev.toml 還是同一個值，跟著原始碼一起公開在 repo 上。沒有換掉這個值的部署，任何人都能照規格自己簽一張效期三十天的通行證，帳號密碼整組跳過。

這也是為什麼前面說官方建議不夠用：HTTPS 保護的是傳輸過程，強密碼保護的是登入這一步，偽造 token 兩者都不經過。真要對外連線，要碼換金鑰，要碼在前面再放一道自己可控的門，例如 VPN 或 Home Assistant 官方的遠端方案，讓陌生人根本連不到面板。

附帶一提，通行證存在瀏覽器的 localStorage，效期又是三十天，一旦外洩影響半徑不小。這屬於加固參考，先決條件仍是別讓面板直接見人。

如果面板已經跑了一陣子，補救的順序是：先換金鑰（換完所有舊通行證一起失效，所有人要重新登入，包括來路不明的那些），再到設定頁的使用者列表確認帳號都是自己開的，最後把初始化時填給面板的 Home Assistant 長效權杖也重發一組。動作都不難，難的是意識到這顆面板需要跟路由器同一等級的照顧。

文件寫 bcrypt，資料庫裡存的是無鹽 MD5

README 的功能列表寫著「安全的密碼加密儲存」，repo 裡給開發工具看的 CLAUDE.md 也寫 bcrypt 密碼雜湊。翻開 core/hash_utils.py 的實作：hash_password 函式把收到的字串直接回傳，verify_password 做的是等號比較。專案確實安裝了 passlib 與 bcrypt 套件，程式裡也建立了 CryptContext 物件，只是從頭到尾沒有被呼叫。

於是整條鏈變成：使用者在登入頁輸入密碼，瀏覽器先用 crypto-js 做 MD5，送到後端後原樣存進 SQLite。MD5 是雜湊而非加密，沒加鹽的 MD5 對常見密碼可以直接查表反推。拿到那顆資料庫檔的人，無論來自備份外流、主機失竊還是 WebDAV 備份帳號被盜，都有機會還原你家面板的密碼。

公平地說，密碼設得長又獨特、面板只在自家網路裡，這個弱點的實際傷害有限。它真正的問題在於宣稱與實作的落差：文件叫你放心，資料庫裡存的卻是最容易被反推的那種值。

同一顆資料庫檔裡，還有份量更重的東西。初始化時你填的 Home Assistant 網址與長效存取權杖，存在 HassConfig 資料表裡，欄位型別是純文字 Text，整個後端找不到任何加密處理。也就是說，拿到 hass_panel.db 這一顆檔案，等於同時拿到面板密碼的雜湊值，以及一把能直接操作整個 Home Assistant 的鑰匙。備份、同步到雲端、送修主機時，這顆檔案的保管等級要跟密碼本一樣。

功能是真的：卡片、串流、PWA 都有實作對應

帳號層講完，回頭看工具本體。README 列的二十三種卡片，在原始碼的元件目錄裡一個個數得出來：燈光、冷氣、窗簾、感測器、媒體播放器、路由器與 NAS 監控、攝影機、用電統計、家庭成員狀態等，配置頁支援拖曳排序，v1.4.1 的主打更新是卡片分組管理。攝影機這塊給得很大方：映像檔裡直接捆了 go2rtc 這套串流引擎的四種 CPU 架構版本，WebRTC、RTSP、ONVIF 都繞著它處理，支援的協定還能自動切換 HLS；前端另有雲台控制元件，能對支援 ONVIF 的攝影機下轉向指令。用電統計也不是只做表面：後端起動時會排一個每小時左右的定時任務，向 Home Assistant 拉統計資料寫進快取，圖表資料不是開頁面才現查。容器內部則是 nginx 在 5123 對外、後端 API 在 5124 的兩層結構。

Hass Panel 官方 README 提供的儀表板介面預覽圖，包含感測器、空調與窗簾控制卡片 — 官方 README 的介面預覽圖：感測器、空調、窗簾卡片同頁呈現

隱私面倒要替它說句話。整個 codebase 我從頭 grep 過一遍，找不到任何統計或遙測回報的呼叫；後端對外連線只有兩條明路，一是每日一言卡片固定代理 hitokoto、金山詞霸、今日詩詞、扇貝這四個中文語錄 API，二是更新檢查。更新這條路值得攤開看：設定頁的更新功能會向 GitHub 查最新 release，接著把下載網址包上 ghfast.top 這個第三方 GitHub 加速代理的前綴，抓回壓縮包自動套用，也提供手動上傳更新包的入口。我實測 /api/version 拿到的就是這種包過前綴的網址。方便是方便，但更新內容畢竟經過第三方轉手，講究供應鏈的環境可以不用面板內建的更新，改為自己重新拉整份映像。習慣這類工具的讀者，可以對照先前介紹過的 GitHub 下載加速想清楚這條路徑要不要走。

README 自稱「史上最簡單」「有手就能用」，這是作者的行銷話，我的解讀是：相較直接改 Home Assistant 的 YAML，裝它確實省事，但初始化、換金鑰、填攝影機位址這些步驟一樣都少不了。

資料落在哪：備份一個資料夾就夠，顧好一個資料夾就行

第一次打開面板會跑初始化嚮導：建立管理員帳號、填 Home Assistant 的網址與長效權杖。後端這步做得算扎實，權杖填錯會先被擋下，不會讓你帶著壞設定進系統。

之後所有東西都收在掛載目錄 /config/hass-panel 底下：SQLite 資料庫（帳號、HA 權杖、用電統計的實體設定）、版面配置的 JSON 與其備份檔、攝影機串流用的 go2rtc.yaml、上傳檔案與日誌。搬家或升級前把這個資料夾打包，就算把容器砍掉重練，設定也能原樣回來。

要重來也有清楚的退路。設定頁的全域配置裡有重新初始化按鈕，會清空使用者與 HA 連線設定，卡片配置保留；要是面板連打開都有問題，官方 FAQ 教的是直接刪掉 hass_panel.db 再重啟容器，效果等同回到出廠。另外它內建 WebDAV 備份，可以把面板配置推到自己指定的空間，自動保留最近五個版本，只是備份帳號憑證存在瀏覽器的 localStorage，雲端那頭的權限也要設謹慎。

多使用者管理同樣是真的：管理員能在介面裡開帳號、停用帳號，家裡每人一組帳號各自登入。只是帳號之間沒有角色之分，每個帳號看到的權限一樣大，拿來區隔大人小孩的裝置控制權是做不到的。

一人開發、搬過家、停更近一年

數字面先攤開：repo 從 2025 年 1 月開張，982 顆星、62 個 fork，GPL-3.0 授權。提交紀錄幾乎全出自同一人之手，約兩百九十次提交裡他佔兩百八十六次，另外三位貢獻者各只有兩次。最後一次 commit 停在 2025 年 10 月 20 日，最新版 v1.4.1 同月發布，到今天將近一年沒有動靜。這段期間專案從個人帳號搬進 ha-china，一個 Home Assistant China 的非官方社群組織。

Hass Panel 的 GitHub 專案頁面，位於 ha-china 組織下的 hass-panel 儲存庫 — 專案已搬進 ha-china 組織，頁面顯示 v1.4.1 與 GPL-3.0

搬遷留下了痕跡。README 與附加元件設定裡的舊網址 mrtian2016/hass-panel 會自動轉到新址，可以用；文件站 FAQ 推薦的儲存庫網址 hass-panel/hass-panel 則是 404，照著輸入會失敗。映像發布也分成兩套：README 用 GitHub 的 ghcr，文件站的 Docker 教學用的卻是杭州的阿里雲 registry。官網 hass-panel.com 還活著，有簡中與英文兩種版本，頁尾掛著河北的 ICP 備案號。

這些線索拼起來的圖像是：有真實用戶、程式能跑，但只剩一位維護者而且停更中的專案。把它當現況可用的工具可以，當有人長期看照的基礎設施，就要自己留後路，例如定期備份設定、留意依賴套件老化。

真的要裝：順序比指令重要

最推薦的路：Home Assistant OS 或 Supervised 用戶直接裝附加元件，手動加儲存庫時用 mrtian2016/hass-panel 或 ha-china/hass-panel 都行，別用 FAQ 頁那條 404 的。附加元件模式走 ingress，Home Assistant 的帳號就是第一道門，面板自身的弱點被隔了一層。

Hass Panel 官方文件的安裝指南頁面，列出附加元件安裝步驟 — 官方安裝指南：附加元件是文件推薦的安裝方式

Docker 自架的話，官方指令長這樣：

docker run --name hass-panel --restart unless-stopped \
  --network host \
  -v ./data/:/config/hass-panel \
  -d ghcr.io/mrtian2016/hass-panel:latest

四行各有各自的用意：host 網路模式讓面板直接用主機網路，這樣它才連得到同機的 Home Assistant；./data 掛進容器當設定家，也就是上一節那個要當密碼本保管的資料夾；映像來源在 README 是 ghcr，文件站的教學則給杭州的阿里雲 registry，內容相同，挑連得順的那個就好；起來後打開 5123 就能進初始化。

指令之外，有幾件事先想清楚。host 網路等於面板直接暴露在主機所在的網段，部署在共享或不可信任的區域網路要格外小心。再來，容器裡的後端自己聽在 0.0.0.0 的 5124，host 網路模式下這個埠跟 5123 一樣直接開在網段上，想收緊可以在防火牆擋掉 5124 對外，只留 nginx 的 5123 當入口。還有出廠金鑰的設定檔位於映像內部的 /backend/config/prod.toml，不在掛載目錄裡，想換金鑰只有兩條路：進容器改（映像更新會被還原），或按 GPL-3.0 給的權利自己從原始碼重建映像。需要從外面連回家時，把 VPN（Tailscale、WireGuard 之類）或 HA 官方遠端方案放在前面，別讓 5123 自己面對網際網路。

玩 Docker Compose 的讀者可以順道翻翻之前整理的 NAS Docker Compose 模板庫；想在 Home Assistant 周邊多摸一些物聯網工具，MQTT Explorer 仍是觀察設備訊息的好幫手。

回到最初的問題：值不值得裝。想把家裡設備收進一頁好操作的儀表板，也願意花十分鐘處理金鑰與網路邊界，Hass Panel 在區域網路裡是稱職的開源選項；要的是開箱即用又敢開在外面，那就等它把帳號層補上，或讓更可靠的門擋在前面。