从文件导入密钥

设置

在一个文件里填好你的来源、下载器、媒体服务器、字幕站和邮件，导入它，就不用在设置里一个个输入密钥了。

开始之前

HolyArrs 运行在 Docker 里，配置在 /config。
你可以在 Settings > API > API keys（设置 > API > API 密钥）里创建一个所有者 API 密钥。

导入文件

把 holyarrs-secrets.template.yaml 复制为 holyarrs-secrets.yaml。
填上你用到的部分。其余留空；留空就表示跳过。
让它只有你自己能读：
Terminal window
```
chmod 600 holyarrs-secrets.yaml
```

把它以只读方式挂载进容器：

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 应用密钥（Settings > Outside lists（设置 > 外部列表））。
`tmdb`, `tvdb`	为兼容旧文件而接受。元数据不需要密钥。
`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`	一个为 Move from other apps（从其他应用迁移）保存的密钥。
`holyarrs`	只在 HolyArrs 运行时用来连接它。绝不保存。

每个密钥都会进加密保险库，和在设置里输入的一样。

选项

局域网开关

每个带地址的块都可以加上 allow_local_network: true。它允许这一项访问本机或你的家庭网络（192.168.x.x、10.x.x.x、容器名）。不加的话，这一项只能访问互联网，所以家里的下载器不会有响应。HolyArrs 绝不会根据地址去猜。它和设置里的 May reach the local network（可以访问局域网）是同一个开关。

HolyArrs 停止时

在同一份配置上运行一个一次性容器。它直接保存到配置文件夹，不需要 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

PUID 和 PGID 要和应用用的一样，否则配置文件夹的属主会变成 1000:1000。PUID 对应的用户必须能读这个文件。如果你用了 HOLYARRS_MASTER_KEY_FILE，要给一次性容器同样的变量和挂载。

再运行一次

再运行一次是安全的。对得上的项会显示 unchanged；只有改过的项才会保存。

项	按什么匹配
来源	名称
下载器、媒体服务器	类型和地址
通知	名称和类型
字幕站、旧应用	类型

地址或密钥变了的来源或下载器会再次被暂停。你自己恢复使用之后，再运行也不会动它。indexers 条目里的 api_key 留空会保留已存的密钥；加上 clear_key: true 才会把它移除。

删除文件

加上 -delete 后，命令会用零覆盖这个文件再把它移除，前提是这次运行没有任何一项失败。只读挂载的文件没法从容器里删除，所以要在主机上删：

系统	命令
Linux	`shred -u holyarrs-secrets.yaml`
macOS	`rm -P holyarrs-secrets.yaml`
Windows	`Remove-Item holyarrs-secrets.yaml`，然后清空回收站。

在 SSD 和写时复制的文件系统上，旧的数据块可能还留在磁盘上。密钥本身现在已经存在加密保险库里了。

如果不成功

现象	原因	解决办法
文件能被其他用户读取	权限太宽。	运行 `chmod 600`。在 Windows 上，把它放在只有你能打开的文件夹里。
一个未知的键让导入停了下来	提示的那一行有拼写错误或制表符。	改好那一行。什么都没有保存。
普通 http 被拒绝	`holyarrs` 的地址不在本机上。	在容器里用 `http://127.0.0.1:6262` 运行，或者用 https。
家里的下载器没有响应	没有局域网权限。	在那个块上设置 `allow_local_network: true`。
一次性容器改了文件夹的属主	`PUID`/`PGID` 不一样。	用应用的 `PUID` 和 `PGID`。
`-delete` 什么都没做	有东西失败了，或者挂载是只读的。	在主机上删掉它。

进阶

参数和退出码

参数	作用	默认
`-file <path>`	密钥文件。	无
`-dry-run`	只说明会设置什么。	关
`-config <folder>`	配置文件夹。	`/config`
`-delete`	一次没有失败的运行之后，用零覆盖文件并删除它。	关
`-forget-move-credentials`	删除所有已保存的旧应用密钥，然后停止。	关
`-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。它绝不会打印密钥、密码、令牌或地址。历史记录里会多一个事件，只有数量。如果某条错误本来会显示你文件里的值，就改为显示 [hidden]。

文件格式

YAML 里很小、很严格的一部分：

块靠空格缩进，绝不用制表符；列表用 - ，
值可以直接写，也可以放在 "double quotes" 或 'single quotes' 里（单引号里的 ' 要写两次），
# 在行首或引号外的空格之后表示注释开始，所以含有 # 的密码要加引号，
以 &、*、!、|、>、[、{、%、@ 或反引号开头的值，或者含有 : 的值，要加引号。

遇到未知的键或超过 256 KB 的文件，整个导入会在保存任何东西之前停下；提示信息会指出是哪个键、哪一行。指向这个文件的链接会被拒绝。

特殊字段

字段	规则
SABnzbd	需要完整的 `api_key`。`nzb_key`、用户名或密码会被跳过，绝不保存。
`tvdb.api_key`, `tvdb.unique_user_key`, `trakt.redirect_urls`	接受但跳过。
`smtp.host`	只写服务器名，不带协议或端口。
`smtp.port`	1 到 65535。默认 `587`。
`smtp.from`	一个普通的邮件地址。
旧应用的块	在 Move from other apps 里配合 Use the saved key（用已保存的密钥）使用。绝不显示，仅限所有者，成功读取一次后就删除。