安裝

新手入門

在 Docker 中執行 HolyArrs，然後用瀏覽器開啟。只需要幾分鐘。

開始之前

一台有 Docker 和 Docker Compose 的電腦。
你的媒體資料夾，或是可以建立它們的地方。如果想要瞬間移動而不是複製，請先讀資料夾。
如果用 NAS、Unraid 或 Synology，請看 NAS、Synology 與 Unraid。沒有 Docker 的話，請看可攜式壓縮檔。

步驟

在本機磁碟上建立一個設定資料夾，例如 /srv/holyarrs/config。不要放在網路共用資料夾。Docker Desktop 請改用 named volume。請看 Docker Desktop。
找出擁有你媒體資料夾的使用者與群組：
Terminal window
```
id youruser
# uid=1000(youruser) gid=1000(youruser)
```
把 uid 當作 PUID，把 gid 當作 PGID。

把下面的內容儲存為 docker-compose.yml，並修改路徑：

name: holyarrs
services:
  holyarrs:
    image: holyarrs/holyarrs:latest
    container_name: holyarrs
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - /srv/holyarrs/config:/config
      - /path/to/movies:/movies #optional
      - /path/to/tv:/tv #optional
      - /path/to/music:/music #optional
      - /path/to/downloads:/downloads #optional
    ports:
      - 6262:6262
    restart: unless-stopped

啟動它：
Terminal window
```
docker compose up -d
docker compose ps
```
HolyArrs 一有回應，container 就會顯示為 healthy。
開啟 http://your-server:6262，馬上建立擁有者帳號。沒有預設密碼。在你建立之前，第一個開啟 HolyArrs 的人就會成為擁有者。
接著照開啟的設定畫面進行。請看首次執行。

如果你比較習慣 docker run：

docker run -d \
  --name=holyarrs \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -p 6262:6262 \
  -v /srv/holyarrs/config:/config \
  -v /path/to/movies:/movies `#optional`   -v /path/to/tv:/tv `#optional`   -v /path/to/music:/music `#optional`   -v /path/to/downloads:/downloads `#optional` \
  --restart unless-stopped \
  holyarrs/holyarrs:latest

Image tag

Tag	你會得到什麼
`latest`	最新的新版
`1.0.0`（任何版本）	剛好是那個版本，永遠不會變

設定說明

Port 與資料夾

設定項目	作用
`-p 6262:6262`	Web 介面。
`-v /config`	資料庫、設定、主金鑰、backup 和 log。只能放本機磁碟。
`-v /movies`	選用。電影媒體庫資料夾。
`-v /tv`	選用。影集媒體庫資料夾。
`-v /music`	選用。音樂媒體庫資料夾。
`-v /downloads`	選用。下載器的下載資料夾。請看媒體資料夾。
`--read-only=true`	選用。請看唯讀根檔案系統。
`--user=1000:1000`	選用。請看以固定使用者啟動。

環境變數

變數	作用
`PUID`、`PGID`	HolyArrs 執行時使用的使用者與群組。沒有設定時是 1000 和 1000。
`TZ`	時區，例如 `Europe/Amsterdam`。
`UMASK`	選用。新檔案要去掉哪些權限位元，例如 `022` 或 `002`。
`HOLYARRS_SAVE_PATH`	選用。下載器的儲存資料夾，以下載器看到的路徑為準。
`HOLYARRS_ALLOWED_HOSTS`	選用。大家用來連到 HolyArrs 的其他主機名稱，用逗號分隔。
`HOLYARRS_TRUSTED_PROXIES`	選用。你的 reverse proxy 的位址或網路。
`HOLYARRS_URL_BASE`	選用。把 HolyArrs 放在某個路徑底下。請看 URL base 與 reverse proxy。
`HOLYARRS_MASTER_KEY_FILE`	選用。從單獨的檔案讀取主金鑰。

任何變數都可以從檔案讀取。在變數名稱前面加上 FILE__，並把檔案路徑當作值：

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

檔案結尾的一個換行會被去掉。PUID、PGID、 UMASK 和 TZ 也可以這樣用。如果檔案不存在，HolyArrs 會停止，並在 log 中寫出變數名稱，但不會印出值。

Image

這個 image 只有 HolyArrs，幾乎沒有其他東西。它沒有 shell，所以你無法用 docker exec 進去看。請改用 docker logs holyarrs 讀 log，或開啟設定資料夾裡的 logs/holyarrs.log。

HolyArrs 自己的指令仍然可以透過 docker exec 使用：

docker exec holyarrs /holyarrs doctor
docker exec -i holyarrs /holyarrs reset-owner
docker exec holyarrs /holyarrs restore --pre-update

Image 有 amd64、64 位元 ARM 和 32 位元 ARM 版本。在記憶體約 2.5 GiB 以下的電腦上，HolyArrs 會自動開啟低記憶體模式。 log 的第一行會寫明這件事。

使用者與群組

container 以 root 啟動，只是為了完成自身設定。需要時，它會把設定資料夾交給 PUID:PGID，然後永久切換成那個使用者。log 的第一行會顯示使用者、群組和 umask。

HolyArrs 絕不會變更你的媒體資料夾或下載資料夾的擁有者。請自己給 PUID 使用者寫入權限。只有讀取權限不夠，因為 HolyArrs 要建立資料夾和移動檔案。

有些儲存空間無法變更擁有者，例如開了 root squash 的 NFS、SMB 或唯讀掛載。HolyArrs 這時會在 log 寫下警告，然後繼續執行。請手動讓設定資料夾可由 PUID:PGID 寫入。

切換使用者需要 CHOWN、DAC_OVERRIDE、SETUID 和 SETGID 這幾項 capability。Docker 預設就有。如果你拿掉它們，HolyArrs 會停止並顯示訊息，不會退回用 root 執行。要真的以 root 執行，請設定 PUID=0 和 PGID=0。

group_add: 加入的額外群組，在 HolyArrs 切換使用者時會保留。

UMASK 只影響新檔案。不設定的話會維持 022，也就是你可寫入、其他人可讀取。如果群組也必須能寫入，請用 002。

媒體資料夾

只掛載你會用到的資料夾：/movies、/tv 和 /music 當作媒體庫資料夾，/downloads 當作下載資料夾。

hardlink（硬連結）提示：你單獨掛載的每個資料夾，在 container 裡都是獨立的 mount，而檔案無法跨 mount 做 hardlink，所以匯入會變成完整複製。如果你想要 hardlink，可以改為掛載一個共用的上層資料夾（下載資料夾和媒體庫資料夾都放在裡面），取代那四個選用的掛載，並讓下載器用同一個路徑掛載同一個資料夾。上層資料夾也必須屬於同一個檔案系統。底下分開的 NAS 共用資料夾或 dataset 仍然會複製。當 HolyArrs 必須複製時，Settings > Library folders（設定 > 媒體庫資料夾）會提醒你。

HOLYARRS_SAVE_PATH 會隨每個下載項目一起送給下載器，所以它也會改變下載器的儲存位置。不設定的話，會沿用下載器自己的設定。如果不設定，請把下載資料夾加到 Settings > Library folders > Extra import folders，這樣你才能從那裡手動匯入。

保管好主金鑰

HolyArrs 用主金鑰加密儲存的密碼、金鑰和 token。第一次啟動時會建立 /config/holyarrs.key。

backup 絕不包含這把金鑰。請在別處另存一份。簡單的做法：以擁有者身分開啟 Settings > Backups（設定 > 備份），選擇 Download key kit（下載金鑰組）。要放回去時，把檔案命名為 holyarrs.key，在 HolyArrs 停止的狀態下放進設定資料夾。用不同金鑰還原會被拒絕。如果用的是 named volume，就沒有資料夾可以開啟：請用 docker cp holyarrs.key hx:/config/ 複製進去，做法和 Docker Desktop 一樣。要搬到新電腦？先把金鑰放回去，再還原 backup。請看 Backup。

你也可以把金鑰放在單獨的唯讀檔案：

environment:
  - HOLYARRS_MASTER_KEY_FILE=/keys/holyarrs.key
volumes:
  - /srv/holyarrs/keys:/keys:ro

檔案必須存在，內容要是 32 個原始位元組、64 個十六進位數字，或 32 位元組的 base64。PUID 使用者必須能讀取它。

重新啟動與還原

請保留重新啟動原則。還原會先檢查並暫存，然後 HolyArrs 以狀態碼 75 結束，讓 Docker 再次啟動它並套用還原。unless-stopped 就能處理這件事。

要更新本機建置的版本，請重新建置並重新建立，不要動到掛載：

docker build --file deploy/Dockerfile --tag holyarrs:local .
docker compose up -d --force-recreate

更新時絕對不要移除 /config。請看更新和 Backup。

主機名稱與 reverse proxy

IP 位址和 localhost 開箱即用。你在首次設定時使用的家用名稱，例如 tower.local，會自動幫你儲存。其他名稱請加到 Settings > Sign-in and security 底下的 Allowed host names（允許的主機名稱），或加到 HOLYARRS_ALLOWED_HOSTS。

當 reverse proxy 加上 X-Forwarded-For 時，只把 proxy 的位址或網路放進 HOLYARRS_TRUSTED_PROXIES。沒有這個設定的話，Single Sign-on、真實的用戶端位址和 Secure cookie 都無法運作，而且 proxy 後面的所有人會共用同一個登入限制。log 會寫出要加入的 proxy 位址。如果前面還有另一層 proxy，例如 Cloudflare，也要加入它的範圍。

用 nginx 的話，兩個 header 都要送：

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

如果兩者不一致，HolyArrs 會把訪客當作在你的網路之外。

安全基本原則

不要在路由器上轉送 port 6262。請用 Tailscale 之類的 VPN，或有 HTTPS 的 reverse proxy。
第一次啟動後，馬上建立擁有者帳號。
把主金鑰的副本放在設定資料夾以外的地方。
讓 image 保持最新。

特殊設定

Docker Desktop（Windows 與 Mac）

Docker Desktop 透過一層機制分享主機資料夾，在那一層上資料庫檔案鎖並不安全。HolyArrs 會拒絕放在那裡的 /config，並在 port 6262 顯示解決方式。請為 /config 使用 named volume。媒體資料夾可以繼續用主機資料夾。

name: holyarrs
services:
  holyarrs:
    image: holyarrs/holyarrs:latest
    container_name: holyarrs
    environment:
      - TZ=Etc/UTC
    volumes:
      - holyarrs-config:/config
      - C:/Media/movies:/movies
    ports:
      - 6262:6262
    restart: unless-stopped

volumes:
  holyarrs-config:

要把舊的設定資料夾搬進 volume，請先停止 HolyArrs，然後執行：

docker create --name hx -v holyarrs-config:/config holyarrs/holyarrs:latest
docker cp C:\old\config\. hx:/config/
docker rm hx

要把 backup 複製出來：docker cp holyarrs:/config/backups .

在 Mac 上，如果你已確認檔案鎖在你的資料夾可以運作，可以設定 HOLYARRS_ALLOW_DESKTOP_FOLDER=1 強制啟動。HolyArrs 每次啟動都會警告。這個設定永遠不會解除對網路共用資料夾的拒絕。

唯讀根檔案系統

只有 /config 和 /tmp 需要可寫入：

services:
  holyarrs:
    read_only: true
    tmpfs:
      - /tmp

PUID、PGID 和 UMASK 仍然有效。

以固定使用者啟動

services:
  holyarrs:
    user: "1000:1000"

這樣 HolyArrs 不會變更任何擁有者，所以設定資料夾必須已經可由那個使用者寫入。PUID 和 PGID 會被忽略，log 會說明這點。 Kubernetes 的 runAsUser 也是同樣的情況。

Rootless Docker 與 Podman

在 rootless 模式下，container 裡的 root 就是你自己的使用者，而其他 id 在主機上會對應到很大的數字。用 PUID=1000 的話，設定資料夾在主機上最後會屬於一個陌生的擁有者。

你執行的是	`docker info` 或 `podman info` 顯示	使用
一般 Docker	沒有 `rootless`	照常使用 `PUID` 和 `PGID`
Rootless Docker	Security Options 底下有 `rootless`	做法 1
Rootless Podman	`rootless: true`	做法 1 或 2

做法 1。 設定 PUID=0 和 PGID=0。只有在 rootless 模式下才安全。一般 Docker 或 NAS 上絕對不要這樣做。

做法 2。 Podman 搭配 keep-id，寫成 Quadlet，放在 ~/.config/containers/systemd/holyarrs.container：

[Container]
Image=holyarrs/holyarrs:latest
UserNS=keep-id
User=%U:%G
Volume=%h/holyarrs/config:/config:Z
PublishPort=6262:6262
HealthCmd=["/holyarrs","-healthcheck"]
HealthInterval=30s

[Service]
Restart=always

[Install]
WantedBy=default.target

或用一行指令：

podman run -d --name holyarrs --userns=keep-id --user "$(id -u):$(id -g)" -v ~/holyarrs/config:/config:Z -p 6262:6262 --health-cmd '["/holyarrs","-healthcheck"]' --health-interval 30s --restart always holyarrs/holyarrs:latest

:Z 用於有 SELinux 的系統。下載器共用的資料夾請用 :z。網路共用資料夾（NFS 或 SMB）兩者都不要用：它無法重新標記，container 會無法啟動。
健康檢查要寫成清單。image 沒有 shell。
重新啟動原則請維持 always。Podman 的重開機後啟動服務只會啟動 always 的 container。
想在重開機後不用登入就啟動，請先執行一次 loginctl enable-linger $USER。然後使用 Quadlet 檔案，如果是 podman run，就執行 systemctl --user enable podman-restart.service。

如果資料夾已經屬於很大的 id，請先停止 container，然後：

Rootless Podman：podman unshare chown -R 0:0 ~/holyarrs/config（做法 1）或 podman unshare chown -R 1000:1000 ~/holyarrs/config。
Rootless Docker：rootlesskit chown -R 0:0 ~/holyarrs/config，要透過 nsenter 進入 rootless daemon 來執行（nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)）。

自己建置 image

在 HolyArrs 的 checkout 資料夾中：

docker build --file deploy/Dockerfile --tag holyarrs:local .

然後用 holyarrs:local 當作 image。

疑難排解

請先執行 doctor。它會檢查設定、資料夾、網路和時鐘，並告訴你每個問題怎麼解決。

container 正在執行：docker exec holyarrs /holyarrs doctor
container 一直重新啟動：docker compose run --rm holyarrs doctor

log 和支援封包請看疑難排解。

你看到	怎麼做
Config folder is on a shared or network folder	改用本機磁碟，Docker Desktop 則用 named volume。Unraid 請用 `/mnt/<pool>/appdata/holyarrs`。
Config folder is in memory	把 `/config` 放在磁碟上。Unraid 請確認 pool 路徑存在。測試用的機器可以用 `HOLYARRS_CONFIG_IN_MEMORY=yes` 允許。
Config folder cannot be written	移除 `:ro`，並確認 `PUID:PGID` 擁有該資料夾。
Disk is full	在存放 `/config` 的磁碟上釋出空間，然後重新啟動。
`/config` is not mapped	請看下方。
Cannot switch user	把那四項 capability 加回來，或使用 `user: "<uid>:<gid>"`。
PUID/PGID does not exist inside this container	這些 id 超出了對應的範圍。請看 Rootless Docker 與 Podman。
A `FILE__` variable cannot be read	檢查路徑，並確認檔案已掛載。
Permission denied	檢查 `PUID`、`PGID`，以及所有資料夾的寫入權限。
Unknown host name	用 IP 開啟 HolyArrs，並把名稱加到 Allowed host names。
Imports are copied	掛載一個共用資料夾。請看媒體資料夾。
Master key does not match	把屬於那些資料庫的金鑰放回去。
Restore staged but the app stays down	加上重新啟動原則，然後啟動 container。

忘了對應 /config？

HolyArrs 仍然會啟動，但到處都會警告。container 一移除，所有東西就會消失。請先儲存下來：

docker stop holyarrs
docker cp holyarrs:/config ./holyarrs-config

然後對應 ./holyarrs-config:/config（或 named volume），並重新建立 container。Docker Desktop（Windows 與 Mac）請用 named volume，不要用主機資料夾，並照 Docker Desktop 的做法把資料複製進去。較舊的設定可能還放在沒有名稱的 volume 裡。用 docker volume ls 列出它們。