疑難排解

找到你的症狀，看原因，照著解決方式做。範例使用的 container 名稱是 holyarrs；如果你的不一樣，請換成你的。

前 3 項檢查

1. 查看 log：docker logs -f holyarrs。機密資料會被遮蔽。按 Ctrl+C 停止追蹤；container 會繼續執行。
2. 執行 doctor：docker exec holyarrs /holyarrs doctor。每一行會顯示 OK、WARN 或 FAIL，而每個 WARN 或 FAIL 都會說明怎麼修復。
3. 還是卡住？下載支援封包再求助。請看取得支援。

連不上網頁

症狀： 瀏覽器無法連線到 http://your-server:6262。

原因： container 已停止、port 沒有對應，或是有 proxy 擋在中間。

解決方式：

1. 執行 docker ps。你應該會看到 holyarrs 顯示 0.0.0.0:6262->6262。
2. 如果它一直重新啟動，請查看 docker logs holyarrs 找出原因。
3. 如果你使用 /holyarrs 這類路徑，請看 Reverse proxy 與 URL base。

Permission denied

症狀： doctor 說某個資料夾無法寫入，或是匯入時出現權限錯誤。

原因： 這個資料夾在主機上的擁有者與 PUID 和 PGID 不一致。

解決方式： 執行 doctor 建議的 chown，或把 PUID 和 PGID 設成該資料夾的擁有者。在 NAS 上，請在權限畫面中給該使用者讀取和寫入權限。請看 NAS、Synology 和 Unraid。

什麼都沒有下載

症狀： 作品一直顯示缺少，也沒有任何東西送到你的下載器。

原因： 沒有來源回應、下載器沒有連線，或是沒有發行版通過你的挑選規則。

解決方式：

1. 開啟 Settings > Downloaders（設定 > 下載器），在你的下載器上按下 Test（測試）。應該會通過。
2. 開啟 Settings > Sources（設定 > 來源），在每個來源上按下 Test。
3. 在作品頁面開啟 Choose a release（手動選擇發行版），查看所有結果，以及它們沒被選中的原因。

請看下載器和來源。

已下載但沒有匯入

症狀： 下載在你的下載器中已經完成，但作品沒有出現在你的媒體庫。

原因： HolyArrs 在相同路徑看不到檔案、無法寫入媒體庫資料夾，或是這次匯入需要你決定。

解決方式：

1. 讓 HolyArrs 和下載器在相同路徑上使用同一個下載資料夾，例如 /downloads，或是在下載器上設定 Downloader’s path 和 HolyArrs’ path。
2. 執行 doctor，修正下載資料夾或媒體庫資料夾上的任何 FAIL。
3. 在下載清單中找標示為 Needs a decision（需要決定）的項目，核准或捨棄計畫。

匯入的是複製，不是 hardlink（硬連結）

症狀： doctor 說 hardlink 無法使用，或是匯入後磁碟用量變成兩倍。

原因： 下載資料夾和媒體庫資料夾位於不同的磁碟或掛載上，或是這個磁碟無法建立 hardlink（DrivePool、許多 NAS 和 SMB 共用資料夾、Windows 上的 Docker Desktop）。每個檔案還是只會寫入一次。下載完成的 Usenet 檔案，如果和媒體庫在同一個磁碟上，就會被移動。

解決方式： 改成把同一個共用的上層資料夾掛載進 container，不要分開掛載。請看資料夾。

HolyArrs 無法啟動

症狀： container 停止，或是立刻重新啟動。

原因： log 會寫出來。常見的有：/config 放在網路共用資料夾或 FUSE 路徑上，或是某個功能區塊壞了。

解決方式：

1. 如果 log 這麼說，把 /config 移到本機磁碟。HolyArrs 不會在網路共用資料夾上執行它的資料庫。
2. 否則就以安全模式啟動，在 Settings（設定）中修復，再正常重新啟動。

缺少某個功能

症狀： 你讀到的某個功能，App 裡沒有。

原因： 它可能在這個新版中暫緩。

解決方式： 請看暫緩的功能。

頁面沒有名稱或圖片

症狀： 作品顯示時沒有海報或詳細資料。

原因： 連不上 metadata 伺服器。

解決方式： 檢查你的 DNS 和防火牆。doctor 的 Network 區段會顯示伺服器有沒有回應。

給進階使用者

Doctor 的檢查項目與選項

doctor 在 container 內以 HolyArrs 執行時相同的使用者身分執行，所以它碰到的狀況就是 HolyArrs 碰到的狀況。

區段	顯示內容
App	版本、使用者與群組、umask、是否在 container 中執行。
Config folder	擁有者、權限、可用空間、是否在本機磁碟上。
Library and download folders	是否存在、擁有者、是否可寫入、可用空間、下載資料夾與媒體庫資料夾之間的 hardlink。
Network	metadata 伺服器的名稱能否解析、是否有回應。
Clock	時間、時區（TZ），時鐘明顯不對時會顯示警告。

選項	作用
-config <folder>	檢查 /config 以外的另一個 HolyArrs 設定資料夾。
-json	以 JSON 輸出報告。

結束碼 0 表示沒有失敗；1 表示有一行是 FAIL。報告絕不會顯示金鑰、密碼或 token。它只讀取，唯一的例外是會寫入並移除一個小的測試檔案。以 root 啟動時，它也會像一般啟動一樣，把設定資料夾交給 PUID:PGID。

如果 HolyArrs 一直重新啟動，docker exec 會失敗。請用相同的資料夾，在新的 container 中執行 doctor：

docker run --rm --volumes-from holyarrs -e PUID=<puid> -e PGID=<pgid> -e TZ=<tz> holyarrs/holyarrs:<tag> doctor

使用 Compose：docker compose run --rm holyarrs doctor。

啟動時的資料夾檢查

啟動時，HolyArrs 會檢查它的資料夾，並記錄一行摘要，例如 folders: 4 ok, 1 not writable，然後為每個有問題的資料夾記錄一行，附上解決方式。檢查在 3 秒後就會停止，所以啟動不會卡住。回應太慢的資料夾會算成未檢查；這通常是磁碟正從休眠中喚醒，或是網路共用資料夾太慢。doctor 檢查時沒有時間限制。請看 Log。

image 裡沒有 shell

image 裡只有 HolyArrs 程式，所以體積小，也讓攻擊者能利用的東西更少。docker exec holyarrs sh 會失敗，這是刻意的設計。如果想更仔細地查看，請在旁邊啟動一個用完即丟的輔助 container：

docker run --rm -it --pid container:holyarrs --network container:holyarrs --volumes-from holyarrs busybox sh

它看得到 HolyArrs 的程序、共用它的網路，而且在相同路徑上有相同的資料夾。它以 root 執行，所以只看不改：以 root 寫入的檔案，HolyArrs 可能讀不到。如果要以 HolyArrs 的使用者身分測試，請加上 --user <PUID>:<PGID>。

查詢版本

docker inspect --format '{{ index .Config.Labels "org.opencontainers.image.version" }}' holyarrs

doctor 的 App 區段也會顯示同樣的資訊。

相關頁面

• 取得支援
• Log
• 健康檢查