登录和密码

设置

决定大家怎么登录：密码长度、家庭网络的免登录捷径，以及外部登录。这些只有所有者能改，位置在 Settings > Sign-in and security（设置 > 登录与安全）。

设置密码最短长度

打开 Settings > Sign-in and security > Passwords（密码）。
输入一个 4 到 64 之间的数字。默认是 8。
点击 Save（保存）。刷新页面后，你应该会看到新数字还在。

最短长度对每个新密码都生效：第一个所有者、接受邀请时设的密码、在 My account（我的账户）里改的密码，还有 holyarrs reset-owner。已有的密码可以继续用，到下次修改时才受限制。密码最长 1024 个字符。

在局域网内免登录

家庭网络里的设备打开 HolyArrs 时直接就是所有者身份，不用密码。默认关闭。

打开 Settings > Sign-in and security > Local network（局域网）。
列出你的网络，每行一个，最多 32 个。可以写一个网段（192.168.1.0/24、fd00::/8），也可以写单个地址（192.168.1.20）。
打开开关并保存。你应该会在卡片上看到自己的地址。

列表为空时开关打不开，只要还有儿童账户存在也打不开。创建 API 密钥、改登录设置、读取或替换密钥类信息、恢复备份，这些操作仍然要输入密码。

先检查地址

有些环境会让所有设备看起来都来自同一个网关地址：Docker Desktop、rootless 模式的 Docker 或 Podman，以及 Kubernetes NodePort。常见的有 172.17.0.1、172.18.0.1 及往上、10.88.0.1、10.89.x.1、10.0.2.2 和 192.168.65.x。

把这类地址写进列表，任何能访问 HolyArrs 的人都会以所有者身份进来。某一项看起来像这类地址时，卡片会给出警告。用第二台设备打开这个页面：如果显示的地址一样，就关掉开关并删掉那一项。

在反向代理后面，HolyArrs 只从 HOLYARRS_TRUSTED_PROXIES 里的代理读取转发过来的地址。否则卡片不显示地址，并提示代理不受信任。

单点登录

可以用一个 OpenID Connect 提供方来登录。它会以按钮的形式出现在登录页上。

打开 Settings > Sign-in and security > Single sign-on（单点登录）。
输入提供方的 issuer，点击 Test（测试）。测试时不会发送任何密钥。
输入 client id 和 client secret。如果提供方不用密钥，勾选 Public client（公开客户端）。
复制 Callback address（回调地址），在提供方那边原样登记这个地址。
输入你的密码，如果开了两步验证还要输入验证码，然后点击 Save。每次改动都要这样确认。

接着关联你自己的账户：用密码登录，打开 My account，在 Linked sign-ins（已关联的登录方式）下点击 Link（关联），确认密码，再点击 Single sign-on。

选项

允许新人通过单点登录加入

默认关闭。打开后，提供方放行的任何人都会得到一个账户，所以 HolyArrs 会让你确认一次。新来的人以成员身份加入，只能提交请求。单点登录永远不会产生所有者或管理员。

更改 issuer 或 client id

密钥要重新输入。旧的关联会被移除，所有用过单点登录的人都会被退出登录。他们要在 My account 里重新关联。关闭单点登录也会让他们退出登录。

取消关联一种登录方式

你自己的：My account > Linked sign-ins > Unlink（取消关联）。需要最近确认过密码；如果这是你唯一的登录方式，会被拒绝。
任何人的：所有者在 Settings > Users and roles（用户和角色）里操作。如果这是对方唯一的登录方式，HolyArrs 会再问一次。

取消关联后，用过这种方式的设备会被退出登录。如果允许加入的开关开着，同一个人可以作为新成员再回来。想把对方挡在外面，就关掉加入。

如果不成功

现象： HolyArrs 又让你输入密码。 原因： 改动账户、密钥和设置，需要在最近 10 分钟内确认过密码，开了两步验证的还要加上验证码。外部登录和局域网免登录不算数。 解决办法： 用密码确认。退出登录和结束设备会话从不需要确认。

现象： 回调失败，只有一条简短的错误，你仍然没登录上。 原因： 提供方那边的回调地址和 HolyArrs 的不一样。 解决办法： 重新复制 Callback address，原样粘贴到提供方那边。

现象： 通过单点登录创建的账户没法设置密码。 原因： 这个版本还做不到。 解决办法： 先创建本地所有者，再把单点登录关联到它上面。

现象： 退出了 HolyArrs，但在提供方那边还是登录状态。 原因： HolyArrs 只结束它自己的登录。 解决办法： 在共用设备上，把提供方那边也退出登录。

所有者密码丢了？见会话和密码。

进阶

受信任代理登录

如果反向代理已经负责让人登录，HolyArrs 会接受它传过来的名字。只能在环境变量里设置。它会以按钮的形式出现在登录页上；光凭请求头访问一次，不会让任何人登录。

代理要去掉传入的 Remote-User 和 Remote-Name，登录后再设置它自己的值。
Remote-User：一个固定不变的名字，最多 255 字节。Remote-Name：可选的显示名，最多 200 字节。
重复的值、用逗号拼接的值或带控制字符的值会被拒绝。角色请求头会被忽略。

让 HolyArrs 只能通过这个代理访问。信任一个代理地址，就等于信任它发来的每一个名字。在 My account > Link trusted proxy sign-in（关联受信任代理登录）里把它关联到账户。

环境变量

在启动前设置。两种方式不打开就都是关闭的。配置有误会让 HolyArrs 无法启动；提供方出故障时，密码登录仍然能用。只要设置了 HOLYARRS_OIDC_ENABLED，哪怕设成 false，单点登录就归环境变量管，Settings 里只能看。

变量	作用	默认
`HOLYARRS_OIDC_ENABLED`	打开单点登录	`false`
`HOLYARRS_OIDC_ISSUER`	提供方准确的 HTTPS issuer	无
`HOLYARRS_OIDC_CLIENT_ID`	登记过的 client id	无
`HOLYARRS_OIDC_CLIENT_SECRET_FILE`	存放 client secret 的文件，最多 4096 字节。公开客户端不用填	无
`HOLYARRS_OIDC_REDIRECT_URL`	准确的 HTTPS 回调地址：你的地址，有 URL 基础路径就加上，再接 `/api/v1/auth/oidc/callback`	无
`HOLYARRS_OIDC_ALLOW_JOIN`	新人以成员身份加入，只能提交请求	`false`
`HOLYARRS_OIDC_ALLOW_LOCAL_NETWORK`	允许使用你私有网络里的提供方	`false`
`HOLYARRS_OIDC_ALLOW_LOOPBACK_HTTP`	允许在回环地址上用普通 HTTP，供测试用	`false`
`HOLYARRS_FORWARD_AUTH_ENABLED`	打开受信任代理登录	`false`
`HOLYARRS_FORWARD_AUTH_ISSUER`	这个代理固定不变的 HTTPS 名称。换一个值就算新的来源	无
`HOLYARRS_FORWARD_AUTH_TRUSTED_PEERS`	用逗号分隔的代理地址或网段。必填。覆盖所有地址的网段会被拒绝	无
`HOLYARRS_FORWARD_AUTH_ALLOW_JOIN`	新的代理用户名以成员身份加入，只能提交请求	`false`

ALLOW_LOCAL_NETWORK 和 ALLOW_LOOPBACK_HTTP 这两个设置项，对在 Settings 里配置的单点登录同样生效。

单点登录的工作方式

提供方必须支持带 PKCE S256 的授权码登录和 RS256 令牌，并且每个端点都在 issuer 的同一个源上。
账户按提供方自己的账户 id 匹配，从不按邮箱匹配。
不使用提供方的角色和用户组。
client secret 加密保存，之后不再显示。字段留空就保留原来的值。