更新

新手入門

HolyArrs 會在新版本推出時通知你，但不會自行安裝。你可以在方便的時候 pull 新的 image。

查看是否有新版本

開啟 Status（狀態）頁面（http://your-server:6262/health）。
查看 Updates（更新）。你應該會看到下列其中一種：

訊息	意思
“HolyArrs 1.2.0 is out, newer than this one.”	準備好時就更新
“This is the newest version.”	不需要做任何事
“No HolyArrs release is published yet.”	Feed 是空的。沒有任何問題
“The last check did not work: …”	連不到 Feed，通常是沒有網路
“The update check is off: …”	已在設定中關閉

想立刻確認的話，按下 Check now（立即檢查）（或 Check again，再檢查一次）。這需要 Change settings（變更設定）權限。

有更新的版本時，也會以健康警告的方式顯示。檢查失敗則只會顯示在 Updates 底下。

更新

pull 新的 image 並重新啟動：先執行 docker compose pull，再執行 docker compose up -d。
HolyArrs 啟動。如果新版本改變了資料的儲存方式，它會先做 backup，再更新資料。你應該會看到 App 以新版本開啟。

退回舊版

HolyArrs 無法自行更換 image，所以你要執行舊版的 image，再由 HolyArrs 把舊的資料放回去。

把 compose 檔（或 docker run）裡的 image tag 改成舊版，例如 holyarrs/holyarrs:<older version>。
執行 docker compose up -d。
如果這次更新沒有改變資料，舊版就會啟動。到這裡就完成了。
否則舊版會顯示一個頁面，而不是 App。選擇 Put back the data from before the update（放回更新前的資料）。
輸入一次性代碼。用 docker logs <container> 找到它，找出含有 “one-time code” 的那一行。
HolyArrs 會檢查 backup、把它放回原位，然後停止。你應該會看到 container 透過重新啟動原則，用那份資料再次啟動。如果沒有設定重新啟動原則，就自己啟動。

不使用這個頁面的做法：先執行 docker exec <container> /holyarrs restore --pre-update，再執行 docker restart <container>。不使用 Docker 的做法：停止 HolyArrs，執行 holyarrs restore --pre-update，再啟動它。

不會刪除任何東西。較新的資料會移到 backups/before-restore-<time>/，所以你可以復原。如果退回不只一個版本，會選出那個版本讀得懂、最新的更新前 backup。

選項

全都在 Settings > Health checks（設定 > 健康檢查）。最後三項在這張卡片的進階區塊裡。

設定項目	預設	何時要變更
Check for a newer HolyArrs（檢查是否有更新的 HolyArrs）	開啟	你完全不想對外發出請求
Check for updates every（更新檢查間隔）	1 天	你想減少檢查次數：3、7、14 或 30 天
Release feed（發行版 Feed）	空白（HolyArrs 新版）	你自己架設 Feed
Feed may be on the local network（Feed 可以在區域網路上）	關閉	你的 Feed 在自己的網路上
Include test versions (like 1.2.0-rc1)（包含測試版）	關閉	你想收到測試版的通知

如果沒有成功

症狀： “The last check did not work.” 原因： 伺服器沒有網路，或是你自己的 Feed 在區域網路上。 解決方式： 檢查網路連線，或開啟 Feed may be on the local network。

症狀： 發行版 Feed 無法儲存。 原因： 位址裡含有名稱、密碼、?query 或 #fragment，或不是以 http:// 或 https:// 開頭。 解決方式： 移除那些部分。

症狀： 更新因為磁碟空間不足而停止。 原因： 沒有足夠的空間放副本和更新。 解決方式： 在設定資料夾所在的位置釋出空間，然後重新啟動。

症狀： 退回頁面不接受你的代碼。 原因： 代碼是舊的，或是自上次啟動以來已經輸入錯誤 10 次。 解決方式： 從最新的 log 行複製代碼。輸入錯誤 10 次之後，請重新啟動 container，並使用新的代碼。

暫緩的功能

有些功能在這個版本中預設是關閉的。要開啟的話，風險自負。功能暫緩時，它們的頁面和選單項目會隱藏，API 路由會回應「找不到」，它們的工作也不會執行。你為它們儲存的資料會保留。

要開啟其中一項，請把它的開關加到 HOLYARRS_FLAGS，以逗號分隔，然後重新啟動 container：

environment:
  HOLYARRS_FLAGS: "subtitle_sites,alert_channels_more"

要關閉的話，移除名稱再重新啟動。再次開啟時，隱藏的設定會回來。

開關	功能
`row_title_stats`	在 Appearance 中顯示探索橫列的作品統計
`trakt_lists`	Trakt 金鑰、Trakt 清單和 Trakt 評論。TMDB 清單維持開啟
`alert_channels_more`	Telegram、ntfy、Gotify、Pushover 和 webhook 通知。Discord 和 email 維持開啟
`subtitle_sites`	字幕網站和字幕搜尋。你的字幕語言設定維持開啟
`emby_signin`	使用 Emby 登入。Emby 媒體庫重新整理仍可使用
`go_back`	Status 頁面上的 Go back（退回舊版）面板。退回舊版的步驟不需要它也能使用

加了開關之後沒有任何變化？檢查拼字（小寫、底線），並重新啟動 container，不是只重新整理頁面。

給進階使用者

檢查會送出什麼

對 api.github.com 發出一次請求來取得最新的發行版，只帶 User-Agent: HolyArrs/<version>。沒有帳號、金鑰或媒體清單。關閉檢查時，完全不會發出請求。

最後一次的回應會被儲存，所以重新啟動不會在還沒到時間前就檢查。一次檢查最多等 15 秒、最多讀取 512 KB，最多跟隨 3 次重新導向，而且不會在 http 和 https 之間切換。只有當發行說明連結指向 GitHub 上 HolyArrs 的發行頁面時才會顯示；否則版本只會以純文字顯示。

Release feed 接受 GitHub 風格的發行版回應、發行版清單、任何含有 version 的 JSON，或內容是版本號的純文字。雲端 metadata 位址一律會被拒絕。測試版會被視為比正式版更舊。

更新前的 backup

在變更儲存的資料之前，HolyArrs 會：

檢查是否有足夠的空間放副本和更新。如果沒有，就不會變更任何東西。可用 HOLYARRS_SKIP_SPACE_CHECK=yes 跳過。
把每個資料庫複製到 backups，檢查副本，並在旁邊寫入一個 sha256 檔案。複製失敗 3 次後，不會變更任何東西。
每個更新步驟各自執行並檢查。失敗的步驟會被復原；已完成的步驟會保留。再次啟動同一個版本，就會用同一份副本，從失敗的步驟接續。

第一次成功啟動後，這份副本會變成 holyarrs-backup-pre-update-<time>.zip，說明文字類似 “before updating from 1.1.0 to 1.2.0”。它會顯示在 Settings > Backups 和 holyarrs restore --list 中。最新的 3 份會保留；backup 排程不會移除它們。全新安裝，或是不動到資料的更新，不會產生這種 backup。

驗證 image

從 1.0.3 開始，Docker Hub 上的每個 image 都由 GitHub 上的發行流程簽署。不需要下載任何金鑰。請用 cosign 檢查 image。把你執行的版本，例如 1.0.3，放在寫著 <version> 的地方：

cosign verify holyarrs/holyarrs:<version> \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/HolyArrs/HolyArrs/\.github/workflows/sign\.yml@refs/(tags/[0-9.]+|heads/main)$'

你應該會看到 The cosign claims were validated。看到其他結果，就表示這個 image 不是來自 HolyArrs 的發行流程：不要執行它。

這個 image 也附有一份建置方式的記錄，以及一份內容物清單（SBOM）。用 GitHub CLI 檢查它們：

gh attestation verify oci://docker.io/holyarrs/holyarrs:<version> --repo HolyArrs/HolyArrs

每個 GitHub release 上都有同樣的檔案：.sigstore.json（簽章）、.intoto.jsonl（建置記錄）和 .sbom.spdx.json（內容物）。