如何在 Matrix Synapse 上設定 Federation：逐步指南

矩陣聯盟允許 Synapse 伺服器與其他伺服器交換房間事件，從而使使用不同伺服器的使用者能夠參與同一個房間。要進行設置，需要使 Synapse 的聯盟 API 可透過 HTTPS 訪問，發布正確的伺服器發現訊息，允許所需的網路流量，並測試公共端點。如果 DNS、TLS 或代理程式路由設定錯誤，僅啟動 Synapse 或開啟 8448 連接埠是不夠的。

本指南使用典型的反向代理部署：Matrix 身分域為 `<domain>` example.org，Synapse 運行在 ` matrix.example.org<domain>`，代理處理 443 連接埠上的 TLS 連線。請將範例網域替換為您自己的網域。如果 Synapse 已可透過 `<domain>` 上的 HTTPS 訪問example.org:8448，則通常不需要進行委託。命令和檔案路徑取決於您是透過軟體包、虛擬環境還是容器安裝 Synapse。

聯邦制要有效運作，必須滿足哪些條件？

您的 Synapse 伺服器擁有一個穩定的公用主機名稱server_name。此名稱會出現在 Matrix ID 中，例如@alex:example.org；之後變更此名稱並非常規的主機名稱編輯。
其他主伺服器可以透過 HTTPS 存取聯合 API 並驗證 TLS 憑證。
伺服器發現功能可引導遠端主伺服器找到正確的主機和連接埠。標準聯合連接埠為 8448；委派可以指向 443 連接埠的 HTTPS。
防火牆規則允許您選擇的聯盟端點上的入站流量和出站聯盟連線。

聯盟指的是伺服器之間的通訊。它不會自動將私人房間公開或邀請其他使用者。用戶仍然需要加入或被邀請才能加入房間，房間成員資格和房間設置決定了誰可以參與。首先確定您的 Matrix ID 格式，然後使用與 Synapse 相同的網域名稱server_name。

步驟 1：檢查 Synapse 伺服器名稱和部署

開啟目前網域homeserver.yaml並確認這server_name是您想要保留的網域。常見的做法是：

server_name: "example.org"
public_baseurl: "https://matrix.example.org/"

server_name決定使用者 Matrix ID 中的網域名稱。public_baseurl它是面向客戶端的公共 URL，例如使用者在用戶端輸入的 URL；如果位於反向代理之後，則應指定代理 URL。它們用途不同，因此請勿將伺服器名稱替換為後端容器名稱，或僅為了匹配子網域而變更它。如果伺服器已在使用中，請在變更網路設定之前備份其配置和資料庫。

檢查 Synapse 的安裝和管理方式。 systemd 服務、Docker Compose 堆疊、Kubernetes 部署和託管主機產品使用不同的重新啟動和網路流程。請將以下範例套用至正確的設定文件，並保留所有現有的監聽器和自訂設定。

步驟 2：選擇直接聯合到 8448 埠或委託到 443 埠

聯邦成員加入聯邦通常有兩種途徑：

使用預設連接埠 8448：將網域名稱的 DNS 指向server_name該伺服器，在連接埠 8448 上開放 HTTPS 服務，並提供對該網域有效的憑證。如果 API 可以透過指定的網域和server_name連接埠 8448 來訪問，Synapse 文件指出無需進行委派。
使用連接埠 443 並啟用委託：透過 JSON提供https://example.org/.well-known/matrix/server指向實際端點的請求，例如 `<hostname>.example.com` {"m.server":"matrix.example.org:443"}。委託的主機名稱必須能夠公開解析，並提供有效的憑證matrix.example.org。

並非所有部署都必須使用 8448 連接埠。如果將請求委派到 443 端口，則入站聯合身份驗證可以使用 443 端口。如果出站連接受到出口防火牆的限制，則應同時允許 443 和 8448 端口，因為遠端伺服器可能使用其中任何一個端口。選擇一條入站路由，並確保 DNS 記錄、TLS 憑證、反向代理程式和防火牆都與該路由保持一致。

步驟 3：透過反向代理路由 Synapse 的聯邦 API

Synapse 通常監聽反向代理後的 HTTP 連接埠 8008。代理程式終止 HTTPS 請求並將 Matrix 端點轉送給 Synapse。在相關的homeserver.yaml監聽器中，確保 HTTP 監聽器包含客戶端和聯合資源，並信任代理程式標頭：

listeners:
  - port: 8008
    type: http
    tls: false
    x_forwarded: true
    bind_addresses: ['127.0.0.1']
    resources:
      - names: [client, federation]

這是一個範例監聽器，並非適用於所有安裝的完整配置。如果 Synapse 運行在容器中，綁定到127.0.0.1容器內部可能會導致代理容器無法存取它；請改用服務網路和適當的綁定位址。請將後端監聽器設為私有，並僅如預期公開代理。

設定代理伺服器將請求轉送到8008 端口，並設定 `--proxy-server-host`/_matrix和` --proxy-server-host`。對於 NGINX，關鍵配置位置如下所示：/_synapse/clientX-Forwarded-ForX-Forwarded-Proto

location ~ ^(/_matrix|/_synapse/client) {
    proxy_pass http://127.0.0.1:8008;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host;
}

請使用主機或容器網路的正確上游位址。請勿在路徑後附加重寫後的路徑proxy_pass；Synapse 的代理指南警告稱，規範化編碼後的請求路徑可能會導致聯合簽章驗證錯誤。如果使用者需要上傳更大的文件，請將代理上傳大小限制與 Synapse 媒體上傳設定保持一致。

步驟 4：設定 TLS 和 DNS

為用於聯盟的主機名稱取得一個公開信任的 TLS 憑證。使用上述反向代理設定時，即matrix.example.org使用委託給該主機時，就需要這樣做。確認代理提供完整的證書鏈，自動續訂證書，並在遠端伺服器將連接的連接埠上提供正確的證書。自簽名憑證或指向錯誤主機名稱的憑證將無法在其他伺服器上進行驗證。

建立一條公網 A 記錄，如果您使用 IPv6，則還需要一筆matrix.example.org指向代理程式的 AAAA 記錄。驗證這兩筆記錄是否都能到達目標服務；即使 IPv4 運作正常，錯誤的 AAAA 記錄也可能導致支援 IPv6 的遠端伺服器發生故障。如果您直接使用連接埠 8448，則 DNS 解析example.org必須指向監聽器，且其憑證必須相符example.org。

步驟 5：發布伺服器發現訊息

對於委託範例，請讓下列 HTTPS URL 傳回狀態碼 200 和包含確切端點的 JSON：

https://example.org/.well-known/matrix/server

{
  "m.server": "matrix.example.org:443"
}

將其作為設定檔提供application/json。檢查它是否無需登入即可公開讀取，是否不會陷入重定向循環，以及主機名稱和連接埠是否與 TLS 代理程式相符。matrix.example.org如果代理實際上將聯合身份驗證路由到其他位置，則不要在文件中發布該文件。

serve_server_wellknown: true只有當請求被https://<server_name>/正確路由到 Synapse 時，Synapse 才能自行提供此檔案。如果您的伺服器名稱是 `<server_name>`，example.org但 Synapse 託管在 `<server_name>` matrix.example.org，那麼在 `<server_name>` 上使用靜態 Web 伺服器或反向代理example.org通常是提供委託回應的更合適選擇。

常見的混淆是將伺服器檔案/.well-known/matrix/client和/.well-known/matrix/server客戶端檔案視為可以互換使用。伺服器檔案幫助其他主伺服器發現傳入的聯盟。客戶端文件用於發布面向客戶端的主伺服器 URL，對於聯盟而言是可選的。只有當您希望相容的用戶端能夠從使用者的 Matrix ID 中發現用戶端 URL 時，才需要單獨設定用戶端檔案。

步驟 6：開啟所需的防火牆路徑

對於直接入站聯合，允許入站 TCP 連接埠 8448 存取 TLS 監聽器或代理程式。對於委託範例，允許入站 TCP 連接埠 443 存取代理程式。客戶端連線通常也使用 443 連接埠上的 HTTPS。如果出站網路存取受到限制，則允許 Synapse 透過 TCP 連接埠 443 和 8448 連接到遠端主伺服器。如果反向代理程式設計為公共入口點，請勿將 Synapse 後端連接埠 8008 開放給公共網際網路。

如果伺服器位於雲端防火牆、路由器、容器網路和主機防火牆之後，請逐層檢查。本機請求 8008 連接埠成功僅證明 Synapse 在本機上有回應；但這並不能證明遠端 Matrix 伺服器可以解析您的網域名稱、驗證 TLS 或存取公共監聽器。

步驟 7：安全重新啟動並驗證公共端點

重新啟動前，請使用安裝方式支援的驗證指令驗證 YAML 檔案。然後重新啟動 Synapse 服務或部署，並檢查其日誌是否有設定或監聽器錯誤。從私有網路以外的電腦請求發現檔案和聯合版本端點：

curl -i https://example.org/.well-known/matrix/server
curl -i https://matrix.example.org/_matrix/federation/v1/version

對於第一個指令，預期會收到一個包含正確資訊的 JSON 回應體，該回應體為 HTTPSm.server格式。對於第二個命令，預期會收到 Synapse 發送的成功 HTTPS 回應，而不是代理錯誤、憑證警告或連線逾時。特定的響應體內容可能因 Synapse 版本而異。

接下來，在Matrix Federation Tester中輸入您的 Matrix 位址server_name（例如，example.org不一定是代理主機名稱）。修復任何報告的 DNS、委派、憑證或端點錯誤，然後再次執行測試。最後，邀請另一台主伺服器上的使用者加入測試房間，或加入其他伺服器上的房間。測試成功可以作為公共連線性檢查的有效依據，但並不能保證每個遠端伺服器、房間策略、防火牆或用戶端設定的行為都完全相同。

導致設定失敗或出現意外狀況的誤解

「我必須始終開放 8448 連接埠。」不。預設連接埠是 8448，但伺服器委派可以將傳入的聯盟請求定向到 443 連接埠。請開放已發布的發現路由實際使用的連接埠。
「客戶端已知端點檔案啟用聯合身份驗證。」並非如此。聯合身份驗證發現使用伺服器已知端點或受支援的 DNS 回退；用戶端端點用於其他用途。
「聯盟會將所有本地房間公開。」並非如此。聯盟僅支援伺服器通訊。房間的可見性和成員資格仍然決定參與者；您可以邀請遠端帳戶加入測試房間，以確認您所需的使用場景。
「本地健康檢查結果為綠色就證明聯盟已建立。」並非如此。本機檢查不會測試公用 DNS、外部 TLS 驗證、NAT、雲端防火牆規則或代理路由。請從外部進行測試，並使用聯盟測試工具。

Synapse 官方文件建議使用反向代理進行 TLS 終止，並解釋了用戶端連接埠和聯盟連接埠的差異。有關反向代理設定、入站聯盟委託、Synapse 設定選項以及防火牆和安全指南，請參閱官方指南。有關伺服器發現規則，請參閱Matrix Server-Server API 規格。此處的範例假設使用 HTTPS 反向代理後的標準 Synapse；容器網路、託管部署和自訂監聽器佈局可能需要不同的值。