反向代理與 URL base

設定

讓 HolyArrs 透過你的 reverse proxy，放在像 https://home.example/holyarrs 這樣的位址。

reverse proxy（反向代理）是放在你的 App 前面的網頁伺服器，負責把每個位址送到正確的 container。URL base 是 HolyArrs 所在的路徑。

設定路徑

把路徑加到你的 Compose 檔：

services:
  holyarrs:
    environment:
      - HOLYARRS_URL_BASE=/holyarrs

重新啟動 container。
從 Proxy 範例加入一條 proxy 規則。
開啟 https://home.example/holyarrs/。你應該會看到登入頁面。Settings > This app（設定 > 這個 App）會顯示目前使用的路徑。

選項

在哪裡設定路徑

位置	何時生效
`HOLYARRS_URL_BASE`	啟動時生效。優先於其他兩種。
`-url-base /holyarrs` 旗標	啟動時生效，前提是沒有設定環境變數。
Settings > This app	下次啟動時生效，前提是環境變數和旗標都沒有設定。

Proxy 範例

nginx-proxy-manager。 為你的網域建立一個 proxy host，然後加入一個自訂 location：

Location：/holyarrs
Forward hostname 填 holyarrs，port 填 6262。結尾不要加斜線，否則路徑會被截掉。
在該 location 的齒輪設定框中：

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 middleware。

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
    }
  }
}

主機名稱與 proxy 位址

如果大家是用主機名稱連到 HolyArrs，請把它加到 HOLYARRS_ALLOWED_HOSTS。
如果 proxy 會加上 X-Forwarded-For，請把 proxy 的位址加到 HOLYARRS_TRUSTED_PROXIES。沒有加的話，登入時無法判斷誰在你的家用網路裡。

如果沒有成功

症狀	原因	解決方式
每個頁面都顯示找不到	proxy 把路徑截掉了	移除截斷路徑的設定，或移除結尾的斜線。
即時更新一直沒有送到	proxy 緩衝了回應	關閉緩衝（`proxy_buffering off`、`flush_interval -1`）。
儲存的路徑讓你無法登入	儲存的路徑是錯的	用 `HOLYARRS_URL_BASE=/` 啟動，就會忽略它。
登入時把你當成在網路之外	proxy 不受信任	傳送 `X-Real-IP` 和 `X-Forwarded-For`，並設定 `HOLYARRS_TRUSTED_PROXIES`。

更多解決方式：疑難排解。

給進階使用者

路徑規則

允許的字元：字母、數字、-、_、. 和 /。不能有 .. 或 //。
holyarrs、/holyarrs 和 /holyarrs/ 都代表 /holyarrs。
儲存的路徑如果無效，會被忽略。
所有東西都會移到這個路徑底下：頁面、API、即時更新、登入，以及 HolyArrs 產生的連結（邀請連結、行事曆 feed）。
/healthz 和 /readyz 在根路徑也會回應，所以 image 本身的健康檢查仍能運作。
路徑之外的其他任何位址都會回應找不到。

proxy 必須做到什麼

需求	原因
原封不動地傳遞路徑	HolyArrs 依完整路徑來路由。
保留 `Host` 標頭	主機檢查和產生的連結都會用到它。
不緩衝回應	即時更新是透過一個保持開啟的回應串流傳送。
較長的讀取逾時（1 小時）	即時更新串流會一直保持開啟。