從檔案匯入金鑰

設定

把你的來源、下載器、媒體伺服器、字幕網站和郵件資料填進一個檔案，匯入之後，就不用在設定裡一個一個輸入金鑰。

開始之前

HolyArrs 在 Docker 中執行，設定放在 /config。
你可以在 Settings > API > API keys（設定 > API > API 金鑰）建立擁有者 API 金鑰。

匯入檔案

把 holyarrs-secrets.template.yaml 複製成 holyarrs-secrets.yaml。
填入你有用到的項目。其他留空；留空表示略過。
設成只有你能讀取：
Terminal window
```
chmod 600 holyarrs-secrets.yaml
```

以唯讀方式掛載到 container 中：

volumes:
  - /srv/holyarrs/config:/config
  - /srv/holyarrs/holyarrs-secrets.yaml:/run/secrets/holyarrs.yaml:ro

在 Settings > API > API keys 建立範圍為 admin 的擁有者 API 金鑰。把它放進檔案的 holyarrs 區塊，位址填 http://127.0.0.1:6262。
先試跑一次。這不會改變任何東西：
Terminal window
```
docker exec holyarrs /holyarrs import-secrets -file /run/secrets/holyarrs.yaml -dry-run
```
每個項目你應該會看到一行 would set。
正式執行（同樣的指令，去掉 -dry-run）。你應該會看到 set 行，結束碼是 0。
檢查新的來源和下載器，然後讓它們繼續。測試新的媒體伺服器和通知，然後開啟它們。
在主機上刪除檔案（請看刪除檔案）。如果不再需要，也一併刪除 API 金鑰。

每個區塊會變成什麼

檔案中的內容	會變成
`trakt.client_id`	Trakt 的 App 金鑰（Settings > Outside lists（設定 > 外部清單））。
`tmdb`、`tvdb`	舊檔案中的這些會接受。Metadata 不需要金鑰。
`opensubtitles`、`subdl`	一個使用你帳號的字幕網站。
`addic7ed`	一個 Addic7ed 字幕網站，只限影集。
`indexers`	每個項目一個來源，並且是 paused（已暫停）。
`jackett`、`prowlarr`	它們的金鑰會填入位址相同、但沒有金鑰的 `indexers` 項目。
`qbittorrent`、`sabnzbd`	一個下載器，並且是 paused。
`nzbget`、`transmission`、`deluge`	略過。匯入目前還不能設定這些；請在 Settings > Downloaders（設定 > 下載器）新增。
`jellyfin`、`emby`、`plex`	一個媒體伺服器，在你測試之前是 off（關閉）。
`smtp`、`discord`、`webhook`	通知中的「Email」、「Discord」和「Webhook」，在你測試之前是 off。
`radarr`、`sonarr`、`lidarr`、`prowlarr`、`bazarr`、`seerr`	為 Import from other apps（從其他 App 匯入）儲存的金鑰。
`holyarrs`	只用來在 HolyArrs 執行時連到它。絕不會儲存。

每個金鑰都會進入加密保險庫，和你在設定中輸入的一樣。

選項

區域網路開關

每個有位址的區塊都可以加上 allow_local_network: true。它讓該項目能連到這台電腦或你的家用網路（192.168.x.x、10.x.x.x、container 名稱）。沒有它的話，該項目只能連到網際網路，所以家裡的下載器不會有回應。HolyArrs 絕不會從位址去猜這件事。它和設定中的 May reach the local network（可連到區域網路）是同一個開關。

HolyArrs 停止時

用同一個設定資料夾執行一次性的 container。它會直接儲存到設定資料夾，不需要 holyarrs 區塊：

docker stop holyarrs
docker run --rm -e PUID=1000 -e PGID=1000 \
  -v /srv/holyarrs/config:/config \
  -v /srv/holyarrs/holyarrs-secrets.yaml:/run/secrets/holyarrs.yaml:ro \
  holyarrs/holyarrs:latest import-secrets -file /run/secrets/holyarrs.yaml
docker start holyarrs

使用和 App 相同的 PUID 和 PGID，否則設定資料夾會被改成 1000:1000。PUID 使用者必須能讀取該檔案。如果你使用 HOLYARRS_MASTER_KEY_FILE，要給一次性 container 同樣的變數和掛載。

重複執行

重複執行是安全的。相符的項目會顯示 unchanged；只有變更過的項目才會儲存。

項目	比對依據
來源	名稱
下載器、媒體伺服器	類型和位址
通知	名稱和類型
字幕網站、舊的 App	類型

位址或金鑰變更過的來源或下載器會再次暫停。一旦你自己讓某一個繼續，重新執行也會讓它維持執行。indexers 項目中空白的 api_key 會保留已儲存的金鑰；加上 clear_key: true 才會移除。

刪除檔案

使用 -delete 時，指令會在完全沒有失敗的執行之後，把檔案用零覆寫再移除。唯讀掛載無法在 container 內部刪除，所以請在主機上刪除：

系統	指令
Linux	`shred -u holyarrs-secrets.yaml`
macOS	`rm -P holyarrs-secrets.yaml`
Windows	`Remove-Item holyarrs-secrets.yaml`，然後清空資源回收筒。

在 SSD 和寫入時複製的檔案系統上，舊的區塊可能還留在磁碟上。金鑰本身現在已經存在加密保險庫裡。

如果沒有成功

症狀	原因	解決方式
檔案可以被其他使用者讀取	權限太寬鬆。	執行 `chmod 600`。在 Windows 上，把它放在只有你能開啟的資料夾。
有一個未知的 key 讓匯入停止	打錯字，或指出的那一行有 tab。	修正那一行。沒有任何東西被儲存。
純 http 被拒絕	`holyarrs` 位址不在這台電腦上。	在 container 內使用 `http://127.0.0.1:6262` 執行，或改用 https。
家裡的下載器沒有回應	沒有區域網路權限。	在該區塊設定 `allow_local_network: true`。
一次性 container 改了資料夾擁有者	`PUID`/`PGID` 不同。	使用 App 的 `PUID` 和 `PGID`。
`-delete` 沒有作用	有東西失敗了，或掛載是唯讀的。	在主機上刪除。

給進階使用者

旗標與結束碼

旗標	作用	預設
`-file <path>`	機密資料檔案。	無
`-dry-run`	只說明會設定什麼。	關閉
`-config <folder>`	設定資料夾。	`/config`
`-delete`	在沒有失敗的執行之後，用零覆寫檔案並刪除。	關閉
`-forget-move-credentials`	刪除所有已儲存的舊 App 金鑰，然後停止。	關閉
`-allow-http-lan`	允許對家用網路位址使用純 `http://`。會印出警告。	關閉
`-allow-readable-file`	接受其他使用者可讀取的檔案。Windows 上的 Docker Desktop 會把每個檔案都顯示為可讀取。	關閉

holyarrs 位址必須是 https://，或是只指向這台電腦的純 http://（127.0.0.1、::1、localhost）。使用純 http 時，你的擁有者金鑰和整個檔案都會以未加密的方式傳送。

結束碼	意思
`0`	每個項目都順利完成。
`1`	有項目失敗。修正檔案後再執行一次。
`2`	指令列或檔案有誤。

輸出

每個項目一行：set（試跑時是 would set，有時附帶備註）、unchanged、skipped (empty)、skipped (why) 或 failed: why。它絕不會印出金鑰、密碼、token 或位址。歷史記錄只會留下一筆只有數量的事件。如果錯誤訊息會顯示你檔案中的值，會改顯示 [hidden]。

檔案格式

一小部分嚴格的 YAML：

區塊用空格縮排，絕不用 tab；清單用 - ，
值可以是純文字、"double quotes" 或 'single quotes'（在單引號內要寫 ' 就寫兩次），
# 在行首或在引號外的空格之後開始註解，所以含有 # 的密碼要加引號，
以 &、*、!、|、>、[、{、%、@ 或反引號開頭，或含有 : 的值，要加引號。

未知的 key，或超過 256 KB 的檔案，會在儲存任何東西之前讓整個匯入停止；訊息會指出該 key 和行號。指向該檔案的連結會被拒絕。

特殊欄位

欄位	規則
SABnzbd	需要完整的 `api_key`。`nzb_key`、使用者名稱或密碼會被略過，也不會儲存。
`tvdb.api_key`、`tvdb.unique_user_key`、`trakt.redirect_urls`	接受但略過。
`smtp.host`	只填伺服器名稱，不要有 scheme 或 port。
`smtp.port`	1 到 65535。預設 `587`。
`smtp.from`	一個單純的 email 位址。
舊 App 區塊	在 Import from other apps 中搭配 Use the saved key（使用已儲存的金鑰）使用。絕不顯示、僅限擁有者、成功讀取一次後就刪除。