故障排查

找到你遇到的现象，看原因，照着解决办法做。示例里的容器名是 holyarrs；如果你的不一样，换成你自己的。

先做 3 项检查

1. 看日志：docker logs -f holyarrs。敏感信息会被遮住。按 Ctrl+C 停止跟踪；容器会继续运行。
2. 运行 doctor：docker exec holyarrs /holyarrs doctor。每一行都会显示 OK、WARN 或 FAIL，每个 WARN 或 FAIL 都会告诉你怎么修。
3. 还是卡住？下载一个支持包再去问。见获取支持。

打不开网页

现象：浏览器连不上 http://your-server:6262。

原因：容器停了、端口没有映射，或者中间挡着一个代理。

解决办法：

1. 运行 docker ps。你应该会看到 holyarrs 带着 0.0.0.0:6262->6262。
2. 如果它一直重启，看 docker logs holyarrs 找原因。
3. 如果你用了 /holyarrs 这样的路径，见反向代理和 URL 基础路径。

权限被拒绝

现象：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（HolyArrs 的路径）。
2. 运行 doctor，把下载文件夹或媒体库文件夹上的 FAIL 都修好。
3. 在下载列表里找标着 Needs a decision（待你决定）的项目，批准或放弃它的方案。

导入是复制，不是硬链接

现象：doctor 说硬链接不能用，或者导入后磁盘占用翻倍。

原因：下载文件夹和媒体库文件夹在不同的磁盘或挂载点上。

解决办法：把一个共用的上级文件夹挂载进容器，不要分开挂载。见文件夹。

HolyArrs 启动不了

现象：容器马上停止或重启。

原因：日志里会写明。常见的有：/config 放在网络共享或 FUSE 路径上，或者某个功能模块坏了。

解决办法：

1. 如果日志这么说，就把 /config 移到本地磁盘。HolyArrs 不会在网络共享上运行数据库。
2. 否则用安全模式启动，在 Settings（设置）里修好，再正常重启。

少了一个功能

现象：你读到过的某个功能，应用里没有。

原因：它可能在这个版本里暂未开放。

解决办法：见暂未开放的功能。

页面没有名称或图片

现象：条目显示出来没有海报，也没有详细信息。

原因：连不上元数据服务器。

解决办法：检查你的 DNS 和防火墙。doctor 的 Network（网络）部分会显示服务器有没有响应。

进阶

doctor 的检查项和选项

doctor 在容器里运行，用的就是 HolyArrs 运行时的那个用户，所以 HolyArrs 会碰到的问题它也会碰到。

部分	显示什么
App（应用）	版本、用户和用户组、umask、是否在容器里运行。
Config folder（配置文件夹）	属主、权限、剩余空间、是否在本地磁盘上。
Library and download folders（媒体库和下载文件夹）	是否存在、属主、是否可写、剩余空间、下载文件夹和媒体库文件夹之间能否硬链接。
Network（网络）	元数据服务器的名字能否解析、服务器有没有响应。
Clock（时钟）	时间、时区（TZ），时钟明显不对时给出警告。

选项	作用
-config <folder>	检查 /config 以外的另一个 HolyArrs 配置文件夹。
-json	以 JSON 格式输出报告。

退出码 0 表示没有失败项；1 表示有一行显示 FAIL。报告从不显示密钥、密码或令牌。它只读不写，只有一个小测试文件例外，写完就删。以 root 启动时，它还会把配置文件夹交给 PUID:PGID，和正常启动一样。

如果 HolyArrs 一直重启，docker exec 会失败。那就在一个新容器里用同样的文件夹运行 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 检查它时没有时间限制。见日志。

镜像里没有 shell

镜像里只有 HolyArrs 程序本身，所以体积小，留给攻击者的东西也少。docker exec holyarrs sh 会失败，这是有意这样设计的。想看得更细，可以在它旁边启动一个用完就丢的辅助容器：

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 部分显示的也是它。

相关页面

• 获取支持
• 日志
• 健康检查