分域 WebFinger

Hollo 支援分域 WebFinger 設定：聯邦宇宙帳號句柄使用一個網域名稱（例如 @alice@example.com），而實際的 ActivityPub 伺服器執行在另一個網域名稱（例如 https://ap.example.com）上。這與 Mastodon 文件中「在根網域名稱上託管 WebFinger」描述的模式，以及 GoToSocial 所稱的基於 host-meta 的主機互換模式相同。

此功能基於 Fedify 的 origin 設定選項實作。

為什麼要分域？

最常見的動機是：你已經擁有一個簡短好記的網域名稱（example.com），希望句柄看起來像 @alice@example.com，但又不想把 Hollo 部署在該網域名稱的根上——根網域名稱往往被首頁、其他 Web 應用程式或既有服務占用。

在分域設定下：

用戶在聯邦宇宙的任何地方都以 @alice@example.com 稱呼你。
Hollo 本身執行在 https://ap.example.com。Web UI、 Mastodon 相容 API、OAuth 和 actor URI 都位於此網域名稱。
根網域名稱 example.com 只需做一件事：把 /.well-known/webfinger 請求重新導向到 ap.example.com。

設定方法

在 Hollo 實例上設定以下兩個環境變數：

HANDLE_HOST — 用於句柄的主機名稱（不含 scheme，也不含路徑），例如 example.com。
WEB_ORIGIN — Hollo 實際執行的 scheme + host，例如 https://ap.example.com。

兩者必須同時設定；只設定其中一個會導致 Hollo 啟動失敗。

HANDLE_HOST=example.com
WEB_ORIGIN=https://ap.example.com

完成此設定後，剩下的由 Fedify 處理：

WebFinger 回應的 subject 為 acct:alice@example.com。
Actor URI 形如 https://ap.example.com/@alice。
Mastodon 相容的 /api/v1/instance 與 /api/v2/instance 端點將實例網域名稱回報為 example.com，因此用戶端會顯示正確的句柄。

反向代理重新導向

Hollo 自身只監聽 WEB_ORIGIN 主機。解析 @alice@example.com 的遠端伺服器會向 https://example.com/.well-known/webfinger 發送 WebFinger 請求，因此你需要在該網域名稱的反向代理上把這些請求重新導向到 Hollo。

保留查詢字串的 301 重新導向即可。一些實作會在發現階段探測 /.well-known/nodeinfo 和 /.well-known/host-meta，建議一併重新導向。

nginx
Caddy

server {
  listen 443 ssl;
  server_name example.com;
  # … 你的常規站台設定 …

  location /.well-known/webfinger {
    return 301 https://ap.example.com$request_uri;
  }
  location /.well-known/nodeinfo {
    return 301 https://ap.example.com$request_uri;
  }
  location /.well-known/host-meta {
    return 301 https://ap.example.com$request_uri;
  }
}

example.com {
  # … 你的常規站台設定 …

  redir /.well-known/webfinger* https://ap.example.com{uri} permanent
  redir /.well-known/nodeinfo*  https://ap.example.com{uri} permanent
  redir /.well-known/host-meta* https://ap.example.com{uri} permanent
}

不需要重新導向 /@username 路徑或任何 actor URL；這些 URL 位於 ap.example.com，遠端伺服器在解析 WebFinger 回應後會直接存取那裡。

驗證設定

部署後，以下三項檢查可以快速確認是否一切正常：

句柄網域名稱上的 WebFinger 是否被重新導向：
```
curl -i "https://example.com/.well-known/webfinger?resource=acct:alice@example.com"
```
應回傳 https://ap.example.com/.well-known/webfinger?... 的 301 回應。
伺服器網域名稱上的 WebFinger 是否回應：
```
curl "https://ap.example.com/.well-known/webfinger?resource=acct:alice@example.com"
```
應回傳 JRD，其中 subject 為 acct:alice@example.com， self 連結指向 https://ap.example.com/@alice。
實例端點是否回報句柄網域名稱：
```
curl https://ap.example.com/api/v2/instance | jq .domain
```
應輸出 "example.com"。

若需更全面的稽核，可以用 Julian Fietkau 的 WebFinger Canary 對你的句柄網域名稱進行檢查。目前 Mastodon 與基於 Fedify 的伺服器能夠正確處理分域設定；Misskey 和 Pixelfed 尚不支援。