doona
疑難排解
示範
繁體中文
疑難排解

疑難排解

native_api 設定寫在 native_api { } 之外

native_api 的欄位直接寫在 experimental 下，honk 因此拒絕此組態。fatal error, shutting down: 一行會列出設定路徑與訊息，例如 experimental.ui: native API setting belongs inside native_api { }。enabled 與 secret 也屬於其他組態區塊，因此 honk 對這兩個欄位只回報 unknown experimental setting。請將欄位移入 native_api { }。

# Wrong: "native API setting belongs inside native_api { }"
experimental {
    ui: '/usr/share/doona'
}

# Wrong: "unknown experimental setting"
experimental {
    enabled: true
}

# Right
experimental {
    native_api {
        enabled: true
        password_auth: true
        ui: '/usr/share/doona'
    }
}

daeuniverse/honk main 分支的建置沒有原生 API，會以 unknown experimental setting 拒絕所有 native_api 設定。Glassyiris/honk feat/native-api 分支的建置若未啟用 native-api 功能，啟用 native_api 時會以 native-api feature is required 阻止啟動。請執行 honk-core --version 檢查版本並安裝 doona 發行版附帶的建置，詳見 honk 版本。

honk 拒絕 native_api 組態區塊

  • configuration administration requires a bearer secret or password login：config_write: true 需要 password_auth: true 或 secret。
  • password login requires an empty secret; a configured secret selects token mode：兩者只能保留一個。
  • password login cannot be combined with anonymous loopback：刪除 allow_anonymous_loopback。
  • native API requires a secret, password login, or explicitly anonymous loopback：enabled: true 需要 secret、password_auth: true，或 loopback listen 與 allow_anonymous_loopback: true。

listen 為 loopback 位址且設定 allow_anonymous_loopback: true 時，請求無需 Token 即可獲准存取，權限與通過 bearer Token 驗證的請求相同。此模式僅用於本機開發。

狀態資料庫問題

範例組態設定了 password_auth: true，資料庫無法開啟時 honk 會在啟動時結束，日誌顯示 state database: 與原因。Token 模式下 honk 會記錄警告並在沒有資料庫的情況下執行：地理資料來源卡片消失，只有同時設定兩個下載網址，「更新」按鈕才會保留。請在日誌中尋找原因：

sudo journalctl -u honk-core | grep -i 'state database'
sudo ls -la /var/lib/honk/state/

日誌也會保留先前每次啟動的訊息，請查看最近一次啟動的記錄。

state database is unavailable
state database path is unsafe
state database is locked by `honk-core admin reset`
state database is corrupt
  1. unavailable：data_dir 不存在時由 honk 建立，state/ 也由 honk 在其中建立。執行 honk 的使用者必須能在父目錄中建立 data_dir，並能寫入該目錄；使用安裝中的 systemd 單元時該使用者為 root。
  2. unsafe：state/ 與 honk.db 必須屬於該使用者，且不授予群組或其他使用者任何權限。honk.db 必須是一般檔案，不能是符號連結，也不能在 honk 開啟時被替換。
  3. locked：等待 honk-core admin reset 執行完畢。
  4. corrupt：設定 password_auth: true 時 honk 會結束。Token 模式下 honk 會將檔案移至 honk.db.corrupt 並建立新的資料庫；若已存在較早的 .corrupt 檔案，honk 會保留兩者，並在該檔案刪除之前不使用資料庫執行。
  5. 修正後重新啟動 honk。

another honk-core has the state database open 與 state database has a foreign application id or a newer schema 一律會阻止啟動：請停止另一個執行個體，或使用寫入該資料庫的 honk 版本。doona beta.10 附帶的 honk 建置開啟 beta.9 附帶建置寫入的資料庫時會出現第二則錯誤；beta.11 及之後附帶的建置可以開啟該資料庫。

地理資料來源無法編輯，或自動更新從未執行

honk 正在沒有狀態資料庫的情況下執行，而來源與更新排程都存在該資料庫中。自 doona beta.9 起，概覽頁的「資料路徑」卡片會提示狀態資料庫無法使用，即使無法讀取資料路徑也會顯示。/api/v1/runtime 的 degradations 清單也會列出該項；<listen> 為 listen 位址，<token> 為 secret：

curl -s -H 'Authorization: Bearer <token>' http://<listen>/api/v1/runtime

出現 persistence_unavailable 項目即可確認，其 reason 指出原因，請參閱狀態資料庫問題。修正之前，「更新」從 native_api 中的 geosite_download_url 與 geoip_download_url 下載，且只在手動按下時執行。

persistence_unavailable 的 reason 為 unsafe

honk 拒絕使用資料目錄中的 state/ 或其中的 honk.db。兩者都必須屬於執行 honk 的使用者，不授予群組或其他使用者任何權限，且不能是符號連結。資料目錄為 ps w | grep '[h]onk-core' 顯示的 --data-dir 值；沒有此參數時為組態中的 data_dir，預設為 /var/lib/honk。

ls -ld /var/lib/honk/state /var/lib/honk/state/honk.db
chmod 700 /var/lib/honk/state
chmod 600 /var/lib/honk/state/honk.db

只變更這兩項，不要遞迴變更；/etc/honk 與 config.d/ 不受影響。若 ls 顯示擁有者不同，請以 chown 將兩者改為執行 honk 的使用者。之後重新啟動 honk。

OpenWrt 的 /var 位於記憶體中，因此預設的 /var/lib/honk 每次重新開機都會遺失資料庫。請依最小組態將資料存放在 /etc/honk/data。

地理資料更新失敗並顯示 checksum_unavailable

檔案已下載，但無法取得 <url>.sha256sum。404 不算失敗：honk 會保留未經驗證的檔案。beta.9 附帶的建置在檔案下載連續 30 秒無進展或總計超過 10 分鐘時逾時；校驗和請求有獨立的 10 秒期限。HTTP 403、429 或路由故障也會讓校驗和請求失敗。可改用其他鏡像站；僅當可信鏡像站的.sha256sum 網址確定無法使用時，才關閉「SHA-256 驗證」。

階段 意義 處理方式
checksum_mismatch 檔案與其 .sha256sum 不符。 改用其他鏡像站；僅當確認可信鏡像站的.sha256sum 檔案有誤時，才關閉驗證。
download_timeout 檔案下載連續 30 秒無進展，或總計超過 10 分鐘。 改用較快的路由或較近的鏡像站。
http_status_rejected 伺服器回應 200 與 404 以外的狀態碼，包括重新導向。 改用最終網址；遇到 403 或 429 時稍後重試。
http_not_found 檔案網址回應 404。 檢查網址。
connection_failed honk 無法連線到伺服器或節點。 檢查節點；直接下載時檢查 bootstrap_resolver。
tls_failed TLS 交握或憑證檢查失敗。 檢查閘道器的時鐘與網址的主機名稱。
group_unavailable 下載所經的群組沒有可用節點。 在「策略」頁檢查該群組。
route_blocked 路由規則將下載主機導向 block。 修改符合該主機的規則。
destination_rejected 網址的位址或連接埠不允許用於下載。 改用連接埠 80 或 443 上的公開位址。
asset_too_large 檔案超過 honk 的大小上限。 確認網址指向地理資料檔案。
invalid_source 網址不是有效的 HTTP 或 HTTPS 網址。 修正網址。

固定映射時出現 Invalid argument

/sys/fs/bpf 不是 bpffs。請依系統需求掛載。

核心版本過舊

honk 會在掛載前拒絕早於 6.12 的核心。驗證器拒絕編譯後的分流程式時，請使用啟用 BPF 與 BTF 的 Linux 6.12 或更新版本，並保留完整的驗證器日誌以便回報。

停止 OpenWrt 防火牆會刪除 honk 的 nft 表

service firewall stop 會刪除 honk 的 nft 表，NFQUEUE staging 隨之失效。重新啟動防火牆後，執行 /etc/init.d/honk-core restart。fw4 reload 和 service firewall restart 不會刪除該表。

沒有原生 API，或 /api、/ui/ 回傳 404

從 journalctl -u honk-core -b 的本次開機日誌中找到最近一筆 honk-core <版本> starting，再與 honk 版本對照。

  • 無法連線到 listen 位址：honk 未執行、enabled 不是 true，或 listen 指向其他位址。enabled: false 時監聽不會啟動。
  • /api 回傳 404：該位址上的服務沒有原生 API，例如 daeuniverse/honk main 分支的建置。doona 的登入頁面此時顯示「此 honk 建置沒有提供原生 API」。請安裝 doona 發行版附帶的建置。
  • 只有 /ui/ 回傳 404：原生 API 正在執行，但 ui 為空。
  • honk 啟動時以 failed to inspect native UI directory、failed to inspect native UI index.html 或 native UI index.html must be a regular file 結束：請依安裝 doona 並啟動將 doona 解壓縮到 ui 目錄。

登入與跨網域失敗

  • 首次設定只能在閘道器本機或私有網路中的用戶端完成。
  • 設定中顯示「網路連線失敗」或「網路或跨網域請求失敗」：無法透過 listen 位址存取 honk，或 doona 所在來源未列入 allow_origins 與 allowed_hosts。
  • 透過 openwrt.lan 存取 API 時，若主機名稱不在 native_api 的 allowed_hosts 中，會回傳 403。請改用區域網路 IP，或在 native_api 中加入 allowed_hosts: 'openwrt.lan' 並重新啟動 honk。
  • 忘記密碼：停止 honk，執行 sudo /usr/local/bin/honk-core admin reset（在 root shell 中去掉 sudo；OpenWrt 上執行 /usr/bin/honk-core --data-dir /etc/honk/data admin reset），再啟動 honk 重新設定。
  • HTTPS 頁面無法存取 HTTP API，請參閱從其他來源開啟 doona。

唯讀的組態檔案

符合下列任一條件時，doona 會將組態檔案標記為唯讀：

  • config_write 不是 true。
  • 既沒有 password_auth: true，也沒有 secret。
  • 檔案在 native_api 或 clash_api 中包含 secret，或包含與 8 位元組以上監聽密鑰相同的文字。
  • honk 仍在載入組態檔案，或其寫入協調器未執行。
  • 僅在以 --store db 執行時出現，本文件不使用此模式：已啟用的修訂未能記錄，導致寫入被阻止。

請將所有密鑰移入 config.d/api.dae，並在變更 native_api 後重新啟動 honk。

「日誌」與「事件」中沒有啟動訊息

「設定」中的「日誌記錄」預設為「隨面板」，只在 doona 連線時記錄。請改為查看系統日誌：

logread -e honk                  # OpenWrt
journalctl -u honk-core -b       # systemd

「連線」或「規則」頁保持空白

「流程記錄」設為「依流程需求」時，honk 只在用戶端請求時記錄。從 beta.9 起，doona 在「連線」或「規則」頁開啟時請求流程，最後一次請求結束後繼續記錄 60 秒。使用 beta.8 或更早版本且看不到流程時，可在「設定」中將「流程記錄」設為「常開」。

「連線」頁僅顯示區域網路位址，全部直接連線

檢查 lan_interface：在 OpenWrt 上設為 br-lan，讓 honk 處理區域網路裝置的流量。使用旁路由器時，也要確認用戶端的閘道器指向旁路由器的區域網路位址。請參閱最小組態。

升級後 doona 仍顯示舊版本

Service worker 在更新完成前會提供快取的版本。請重新載入頁面一至兩次，或關閉所有 doona 分頁後重新開啟。

透過 HTTP 登入時出現 crypto.randomUUID is not a function

0.1.0-beta.8 之前的 doona 需要安全環境才能呼叫此函式，而區域網路上的純 HTTP 不屬於安全環境。請將 doona 升級至 0.1.0-beta.8 或更新版本。

doona

doona 文件

繁體中文
doona 文件doona 是 daeuniverse 引擎共用原生 API 的靜態 Web 介面：目前對接 honk，dae 實作同一份契約後也可對接。 系統需求 在 Debian 或 Ubuntu 上安裝本頁在 Debian、Ubuntu 及其他使用 APT 的系統上，用 .deb 套件安裝 doona，並從同一個 doona 發行版本安裝 honk-core。 在 Fedora 或 RHEL 上安裝本頁在 Fedora、RHEL 及其他使用 DNF 的系統上，用 .rpm 套件安裝 doona，並從同一個 doona 發行版本安裝 honk-core。 在 Arch Linux 上安裝本頁在 Arch Linux 及其他使用 pacman 的系統上，用 .pkg.tar.zst 套件安裝 doona，並從同一個 doona 發行版本安裝 honk-core。 在 Gentoo 上安裝本頁用 Portage 從 doona 儲存庫中的 ebuild 安裝 doona，並從同一個 doona 發行版本安裝 honk-core。 在 OpenWrt 上安裝本頁在 OpenWrt 25.12 上用發行版本中的封存檔安裝 doona 與 honk-core。 在其他系統上安裝本頁在沒有 doona 套件、符合核心要求的 x86_64 或 aarch64 Linux 系統（例如 Alpine Linux）上，用發行版本中的封存檔安裝 doona 與 honk-core。 安裝詳解先安裝 honk 並撰寫組態，再安裝 doona 並啟動 honk。 最小組態本頁撰寫能啟動 honk 並提供 doona 的最小 honk 組態，然後手動啟動 honk 檢查組態。 服務管理本頁以 systemd 或 OpenWrt procd 服務的形式運作 honk：先建立一次服務，再列出啟動、停止、重新啟動、重載 honk 以及檢視日誌的命令。 首次登入本頁在瀏覽器中開啟 doona，建立管理員帳戶，並檢查 doona 是否顯示正在運作的 honk。 介面導覽本頁說明登入 doona 後各項功能的位置：四個導覽分區、頂端列，以及頁面內的分頁、詳細資料面板與操作選單。 觀測流量本頁說明「活動」分區（「活動」與「系統狀態」）及「觀測」分區（「連線」、「分流」、「DNS」、「日誌」與「事件」）。 路由、節點與規則本頁說明「路由」分區中的「策略」「節點」與「規則」三個頁面。 組態與設定本頁說明「組態」頁：在此檢視、驗證並套用 honk 的組態檔。 常見操作本頁彙整調整路由、查看流量與維護 honk 的常用步驟。 組態組態分為兩個檔案。 功能請先確認閘道器能轉送流量。 疑難排解 開發送出 pull request 前先讀 CONTRIBUTING.md。