反向代理和 URL 基础路径

设置

把 HolyArrs 放在反向代理后面，用 https://home.example/holyarrs 这样的地址访问。

反向代理是挡在你各个应用前面的 Web 服务器，它把每个地址转给对应的容器。URL 基础路径是 HolyArrs 所在的路径。

设置路径

把路径加到你的 Compose 文件里：

services:
  holyarrs:
    environment:
      - HOLYARRS_URL_BASE=/holyarrs

重启容器。
从代理示例里加一条代理规则。
打开 https://home.example/holyarrs/。你应该会看到登录页面。Settings > This app（设置 > 本应用）会显示正在使用的路径。

可选项

在哪里设置路径

位置	何时生效
`HOLYARRS_URL_BASE`	启动时。优先于其他两种。
`-url-base /holyarrs` 参数	启动时，前提是没有设置这个变量。
Settings > This app	下次启动时，前提是变量和参数都没有设置。

代理示例

nginx-proxy-manager。为你的域名建一个代理主机，然后加一个自定义位置：

Location：/holyarrs
Forward hostname 填 holyarrs，端口填 6262。末尾不要加斜杠，否则路径会被去掉。
在这个位置的齿轮框里填：

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_buffering off;
proxy_read_timeout 1h;

Traefik。不要加 StripPrefix 中间件。

labels:
  - traefik.enable=true
  - traefik.http.routers.holyarrs.rule=Host(`home.example`) && PathPrefix(`/holyarrs`)
  - traefik.http.services.holyarrs.loadbalancer.server.port=6262

Caddy。用 handle。handle_path 会去掉路径。

home.example {
  handle /holyarrs* {
    reverse_proxy holyarrs:6262 {
      flush_interval -1
    }
  }
}

主机名和代理地址

如果大家用主机名访问 HolyArrs，把它加到 HOLYARRS_ALLOWED_HOSTS 里。
如果代理会加上 X-Forwarded-For，把代理的地址加到 HOLYARRS_TRUSTED_PROXIES 里。不加的话，登录时分不清谁在你的家庭网络里。

如果不成功

现象	原因	解决办法
所有页面都显示“not found”	代理去掉了路径	去掉去除路径的设置，或者去掉末尾的斜杠。
实时更新一直收不到	代理缓冲了响应	关掉缓冲（`proxy_buffering off`、`flush_interval -1`）。
保存的路径把你锁在了外面	保存的路径不对	用 `HOLYARRS_URL_BASE=/` 启动来忽略它。
登录时把你当成在网络之外	代理没有被信任	发送 `X-Real-IP` 和 `X-Forwarded-For`，并设置 `HOLYARRS_TRUSTED_PROXIES`。

更多解决办法：故障排查。

进阶

路径规则

允许的字符：字母、数字、-、_、. 和 /。不能有 .. 或 //。
holyarrs、/holyarrs 和 /holyarrs/ 都表示 /holyarrs。
保存的路径如果无效，会被忽略。
所有东西都移到这个路径下：页面、API、实时更新、登录，以及 HolyArrs 生成的链接（邀请链接、日历订阅源）。
/healthz 和 /readyz 在根路径上也有响应，所以镜像自带的健康检查照常工作。
路径之外的其他地址都返回“not found”。

代理必须做到的事

要求	原因
原样传递路径	HolyArrs 按完整路径来路由。
保留 `Host` 请求头	主机检查和生成的链接要用它。
不缓冲响应	实时更新通过一个保持打开的响应持续传输。
较长的读取超时（1 小时）	实时更新的数据流一直保持打开。