安装

新手入门

在 Docker 中运行 HolyArrs，然后在浏览器里打开它。整个过程只要几分钟。

开始之前

一台装有 Docker 和 Docker Compose 的机器。
你的媒体文件夹，或者一个可以新建它们的地方。如果想让文件瞬间移动而不是复制，先读文件夹。
在 NAS、Unraid 或群晖 (Synology) 上，见 NAS、群晖和 Unraid。不用 Docker 的话，见便携压缩包。

步骤

在本地磁盘上建一个放配置的文件夹，例如 /srv/holyarrs/config。不要放在网络共享上。在 Docker Desktop 上，改用命名卷。见 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 有响应后，容器就会显示为 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

镜像标签

标签	你拿到的是什么
`latest`	最新的正式版
`1.0.2`（任意版本号）	就是那个版本，永远不变

设置说明

端口和文件夹

设置项	作用
`-p 6262:6262`	Web 应用。
`-v /config`	数据库、设置、主密钥、备份和日志。只能放在本地磁盘上。
`-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`	可选。你的反向代理的地址或网段。
`HOLYARRS_URL_BASE`	可选。让 HolyArrs 在某个路径下提供服务。见 URL 基础路径和反向代理。
`HOLYARRS_MASTER_KEY_FILE`	可选。从单独的文件里读主密钥。

任何变量都可以从文件里读。在变量名前面加上 FILE__，再把文件的路径作为值：

environment:
  - FILE__HOLYARRS_ALLOWED_HOSTS=/run/secrets/holyarrs_hosts

文件末尾的一个换行符会被去掉。PUID、PGID、 UMASK 和 TZ 也可以这样用。如果文件不存在，HolyArrs 会停止，并在日志里写出是哪个变量。它绝不会打印变量的值。

镜像

镜像里除了 HolyArrs 几乎没有别的东西。它没有 shell，所以你不能用 docker exec 进去看。要看日志，用 docker logs holyarrs，或者打开配置文件夹里的 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

镜像为 amd64、64 位 ARM 和 32 位 ARM 构建。在内存约为 2.5 GiB 或更少的机器上，HolyArrs 会自己打开低内存模式。日志的第一行会写明。

用户和用户组

容器以 root 启动，只是为了完成自身的准备工作。需要时它会把配置文件夹交给 PUID:PGID，然后永久切换到这个用户。日志的第一行会显示用户、用户组和 umask。

HolyArrs 绝不会改你的媒体文件夹或下载文件夹的属主。你要自己给 PUID 用户这些文件夹的写入权限。只有读取权限不够，因为 HolyArrs 要新建文件夹和移动文件。

有些存储改不了属主，比如开了 root squash 的 NFS、SMB 或只读挂载。这时 HolyArrs 会在日志里记一条警告，然后继续运行。你要手动让 PUID:PGID 能写入配置文件夹。

切换用户需要 CHOWN、DAC_OVERRIDE、SETUID 和 SETGID 这几项能力。Docker 默认会给。如果你去掉了它们，HolyArrs 会停止并给出提示。它不会退回去用 root 运行。真想以 root 运行，就设置 PUID=0 和 PGID=0。

HolyArrs 切换用户时，会保留 group_add: 里的额外用户组。

UMASK 只影响新文件。不填就保持 022，也就是你能写、其他人能读。如果用户组也要能写，就用 002。

媒体文件夹

只挂载你用得到的文件夹：/movies、/tv 和 /music 作为媒体库文件夹，/downloads 作为下载文件夹。

关于硬链接的提示：每个单独挂载的文件夹在容器里都是一个独立的挂载点，而文件不能跨挂载点做硬链接，所以导入会变成完整复制。如果你想用硬链接，可以改为挂载一个共用的上级文件夹（下载文件夹和媒体库文件夹都在它里面），代替那四个可选挂载，并且让下载器在同样的路径上用同一个挂载。这个上级文件夹还必须是同一个文件系统。它下面如果是各自独立的 NAS 共享或数据集，仍然会复制。HolyArrs 不得不复制时， Settings > Library folders（设置 > 媒体库文件夹）会提醒你。

HOLYARRS_SAVE_PATH 会随每个下载任务发给下载器，所以它也会改变下载器的保存位置。不填就沿用下载器自己的设置。如果不填，就把下载文件夹加到 Settings > Library folders > Extra import folders（额外的导入文件夹）下面，这样你才能从里面手动导入。

保管好主密钥

HolyArrs 用主密钥加密保存的密码、密钥和令牌。第一次启动时会生成 /config/holyarrs.key。

备份里从不包含这个密钥。在别的地方另存一份。简单的办法：以所有者身份打开 Settings > Backups（设置 > 备份），选择 Download key kit（下载密钥包）。要把它放回去，就把文件命名为 holyarrs.key，在 HolyArrs 停止时放进配置文件夹。用不同的密钥恢复会被拒绝。用命名卷时没有文件夹可以打开：用 docker cp holyarrs.key hx:/config/ 把它复制进去，做法见 Docker Desktop。要搬到新机器？先把密钥放回去，再恢复备份。见备份。

你也可以把密钥放在一个单独的只读文件里：

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。见更新和备份。

主机名和反向代理

IP 地址和 localhost 不用设置就能用。首次设置时你用的家用主机名，比如 tower.local，会自动保存下来。其他主机名在 Settings > Sign-in and security（设置 > 登录与安全）的 Allowed host names（允许的主机名）下面添加，或者写进 HOLYARRS_ALLOWED_HOSTS。

如果反向代理会加上 X-Forwarded-For，只把代理的地址或网段填进 HOLYARRS_TRUSTED_PROXIES。不填的话，单点登录、真实的客户端地址和 Secure cookie 都不起作用，而且代理后面的所有人共用同一个登录次数限制。日志会写出要添加的代理地址。如果前面还有另一层代理，比如 Cloudflare，也要把它的地址段加上。

用 nginx 时，两个请求头都要发：

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

如果两者不一致，HolyArrs 会把访问者当作来自你的网络之外。

安全基础

不要在路由器上转发端口 6262。用 Tailscale 这样的 VPN，或者带 HTTPS 的反向代理。
第一次启动后马上创建所有者账户。
在配置文件夹之外另存一份主密钥。
让镜像保持最新。

特殊环境

Docker Desktop（Windows 和 Mac）

Docker Desktop 通过一个中间层共享主机文件夹，数据库的文件锁在这一层上不安全。HolyArrs 会拒绝放在那里的 /config，并在端口 6262 上显示解决办法。/config 要用命名卷。媒体文件夹可以继续用主机文件夹。

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:

要把旧的配置文件夹搬进卷里，先停止 HolyArrs，再运行：

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

把备份复制出来：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 会被忽略，日志里会写明。 Kubernetes 的 runAsUser 也是这种情况。

Rootless Docker 和 Podman

在 rootless 模式下，容器里的 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）上两个都不要用：它没法重新打标签，容器会启动不了。
健康检查要写成列表。镜像里没有 shell。
重启策略保持 always。Podman 的开机自启服务只会启动 always 的容器。
要想重启后不登录也能启动，运行一次 loginctl enable-linger $USER。然后用 Quadlet 文件；如果用的是 podman run，就运行 systemctl --user enable podman-restart.service。

如果文件夹已经归一个很大的 id 所有，先停止容器，然后：

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 守护进程来运行（nsenter -U --preserve-credentials -n -m -t $(cat $XDG_RUNTIME_DIR/docker.pid)）。

自己构建镜像

在 HolyArrs 的代码检出文件夹里运行：

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

然后用 holyarrs:local 作为镜像。

故障排查

先运行 doctor。它会检查配置、文件夹、网络和时钟，并告诉你每个问题怎么解决。

容器在运行：docker exec holyarrs /holyarrs doctor
容器不停重启：docker compose run --rm holyarrs doctor

日志和支持包见故障排查。

你看到的	这样做
配置文件夹在共享文件夹或网络文件夹上	用本地磁盘，在 Docker Desktop 上用命名卷。在 Unraid 上用 `/mnt/<pool>/appdata/holyarrs`。
配置文件夹在内存里	把 `/config` 放到磁盘上。在 Unraid 上，检查存储池的路径是否存在。如果是测试机，`HOLYARRS_CONFIG_IN_MEMORY=yes` 可以放行。
配置文件夹无法写入	去掉 `:ro`，并检查文件夹的属主是不是 `PUID:PGID`。
磁盘已满	给 `/config` 所在的磁盘腾出空间，然后重启。
没有映射 `/config`	见下文。
无法切换用户	把那四项能力加回来，或者用 `user: "<uid>:<gid>"`。
PUID/PGID 在这个容器里不存在	这些 id 超出了映射范围。见 Rootless Docker 和 Podman。
读不到某个 `FILE__` 变量	检查路径，并确认文件已经挂载。
权限被拒绝	检查 `PUID`、`PGID` 和所有文件夹的写入权限。
未知的主机名	用 IP 打开 HolyArrs，在 Allowed host names 下面加上这个主机名。
导入时是复制	挂载一个共用的文件夹。见媒体文件夹。
主密钥不匹配	把属于这些数据库的密钥放回去。
恢复已准备好，但应用一直没起来	加上重启策略，然后启动容器。

忘了映射 /config？

HolyArrs 仍然会启动，但到处都会警告。容器一旦被删除，所有东西都会丢失。先把它保存下来：

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

然后映射 ./holyarrs-config:/config（或一个命名卷），再重建容器。在 Docker Desktop（Windows 和 Mac）上，用命名卷，不要用主机文件夹，并按 Docker Desktop 里的做法把数据复制进去。更早的安装可能还留在一个没有名字的卷里。用 docker volume ls 把它们列出来。