如何在 Cloudflare 代理程式後設定 Matrix 伺服器

Matrix 伺服器可以部署在 Cloudflare 之後，但具體設定取決於用戶端和其他伺服器如何發現它。 Cloudflare 的標準 HTTP 代理支援 443 連接埠上的 HTTPS；Synapse 聯盟通常預設使用 8448 端口，而該端口不在 Cloudflare 的標準代理端口列表中。一個可靠的方案是透過反向代理將 Synapse 暴露在 443 連接埠上，並發布 Matrix 的已知記錄，將用戶端和聯盟流量定向到該主機名稱。或者，也可以將聯盟保留在 8448 連接埠上，並將該 DNS 記錄設定為僅用於 DNS 解析。

本指南使用 Synapse（Matrix 官方家庭伺服器實作），並提供範例 Matrix ID@alice:example.com和用戶端端點matrix.example.com。請將這些名稱和地址替換為您自己的名稱和地址。本指南假設 Synapse 和 HTTPS 反向代理程式已安裝。這些說明並非適用於所有家庭伺服器實現，因此可能存在差異。本指南已於 2026 年 10 月 6 日根據 Cloudflare 和 Element Synapse 的最新文件進行驗證。

選擇合適的網頁佈局

Cloudflare 的 orange-cloud 代理程式是一個 HTTP/HTTPS 反向代理。它位於客戶端和來源伺服器之間，用於代理 Web 請求；它並非代理所有 TCP 連接埠。其標準 HTTPS 連接埠包括 443 和 8443，但不包括 Synapse 常用的聯合連接埠 8448。請參閱Cloudflare 支援的網路連接埠和代理限制。

下面使用的是第一種佈局。代理 DNS 記錄本身並不會配置 Matrix 發現、反向代理、TLS 或防火牆策略。

1. 在設定 DNS 之前，請確定 Matrix 伺服器名稱。

Matrix 伺服器名稱是使用者 ID 中冒號後面的部分。在本例中example.com，它是 `<username>`，因此使用者的 ID 類似於 `<username> @alice:example.com`。技術客戶端主機名稱是 `<hostname>` matrix.example.com。這種分離方式可以確保使用者 ID 中使用的網域名稱保持穩定，同時將流量委託給另一個主機名稱。如果 Synapse 已初始化，請勿server_name隨意更改：它是使用者和房間標識的一部分，更改它屬於遷移操作，而不是代理調整。

計劃從伺服器名稱網域提供兩個小型 JSON 發現文件：

• https://example.com/.well-known/matrix/client告訴相容的客戶端使用https://matrix.example.com。
• https://example.com/.well-known/matrix/server告訴其他主伺服器透過以下方式連接到聯盟matrix.example.com:443：

客戶端文件需要Access-Control-Allow-Origin: *響應頭。 Synapse 委託指南包含了這些記錄及其預期結構的範例：Synapse 聯合委託。

2. 建立 Cloudflare DNS 記錄

在 Cloudflare DNS 中，建立一條指向伺服器公網 IPv4 位址的A記錄。僅當來源伺服器具備有效的 IPv6 連線且防火牆已設定 IPv6 時才新增此記錄。將 Web 主機名稱的代理程式狀態設定為「已代理」（橘色雲圖示）。如果根網域也指向此伺服器並將提供常用文件，則也需要代理其 Web 記錄。matrixAAAA

保留無關記錄（包括郵件記錄）的對應 DNS 專用設定。 MX 和 TXT 記錄不會被代理。 Cloudflare 解釋說，代理程式的 A、AAAA 或 CNAME 記錄會將 HTTP/HTTPS 請求路由到 Cloudflare，而 DNS 專用記錄則直接傳回來源位址：Cloudflare 代理程式狀態行為。

允許 Cloudflare 向來源伺服器傳送入站 HTTPS 請求。為了加強保護，請將來源防火牆限制在 Cloudflare 公佈的 IP 位址範圍內，並保持這些範圍更新。如果伺服器的 IP 位址在區域啟動之前就已經暴露，代理 DNS 不會使舊位址失效；請考慮在啟動後更改來源伺服器 IP 位址。不要以為僅憑橙色雲端標誌就能阻止直接來源伺服器存取。

3. 設定 Cloudflare 與來源伺服器之間的 HTTPS 連接

在 Cloudflare 的 SSL/TLS 設定中，如果來源伺服器提供與主機名稱相符的有效憑證（例如公開信任的憑證或 Cloudflare 來源 CA 憑證），請使用「完全（嚴格）」模式。 「完全（嚴格）」模式會對 Cloudflare 與來源伺服器之間的連線進行加密，並驗證來源伺服器憑證；「彈性」模式則不提供相同的端對端 TLS 路徑。請參閱Cloudflare 的「完全（嚴格）」文件。

將憑證和私鑰安裝到反向代理伺服器上，不一定需要在 Synapse 中安裝。反向代理伺服器應監聽公網連接埠 443，並將 Matrix 請求內部轉送至 Synapse 的 HTTP 監聽器（通常為連接埠 8008）。如果反向代理伺服器是唯一的入口點，請勿將 Synapse 監聽器公開。

4. 告知 Synapse 它位於受信任的反向代理之後

在相關的 HTTP 監聽器中homeserver.yaml，啟用轉送標頭處理。以下是一個針對非容器化伺服器的簡化範例：

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

將這些設定合併到現有監聽器中，而不是取代整個配置。 Synapse 的官方文件建議x_forwarded: true使用反向代理，並建議在代理程式運行在同一台主機上時綁定到 localhost。對於容器部署，將 Synapse 綁定到容器的回環位址可能會導致主機代理無法存取它；請改用容器或服務的網路位址，並對該路徑進行防火牆保護。在變更監聽器設定之前，請務必查閱最新的Synapse 反向代理指南。

只有當 Synapse 接受來自您控制的代理程式的流量時，轉送的標頭才可信。如果 Cloudflare 是唯一面向互聯網的路由，請阻止對來源位址的直接公共訪問，並配置代理以傳遞正確的用戶端位址。$remote_addr否則，Nginx 的位址將是 Cloudflare 的位址，因為 Cloudflare 已連接到 Nginx。在使用前，請將 Nginx 的 real-IP 模組配置為僅信任 Cloudflare 發布的來源位址範圍CF-Connecting-IP；切勿信任來自任意互聯網用戶端的該標頭。除非有特殊原因，否則請將 Synapse 管理 API 保持私有。

5. 無需重寫即可路由矩陣路徑

配置反向代理，使其同時向 Synapse 發送請求/_matrix。/_synapse/client務必保持請求 URI 的完整性。如果代理解碼或規範化了編碼後的路徑段，Synapse 聯合身份驗證請求簽章可能會失敗。

以下是一個簡潔的 Nginx 範例matrix.example.com。它假設您已為此伺服器區塊配置了 TLS 憑證指令，並且反向代理程式和 Synapse 運行在同一台主機上：

server {
    listen 443 ssl;
    server_name matrix.example.com;

    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_http_version 1.1;
        client_max_body_size 50M;
    }
}

請勿在此正規表示式位置新增 URI 後綴proxy_pass。 Synapse 的代理文件指出，URI 規範化是導致聯合簽章錯誤的原因之一。此外，client_max_body_size請根據 Synapse 上傳限制和適用於您區域的任何 Cloudflare 套件限制進行調整。50M以上值僅為範例，並非通用建議。

Cloudflare 的套餐支援 WebSocket，Matrix 用戶端可以使用長連線。請確認您的代理允許升級，並且任何 WAF 或速率限制規則都不會拒絕合法的 Matrix 請求。 Cloudflare 的WebSocket 文件詳細介紹了其升級後連線的處理方式。

6. 公佈眾所周知的回應

透過 HTTPS 提供以下兩個回應example.com。您可以從 Web 伺服器、靜態主機或單獨的虛擬主機傳回它們。請確保客戶端文件和聯合身份驗證文件彼此不同：

GET /.well-known/matrix/client
HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *

{"m.homeserver":{"base_url":"https://matrix.example.com"}}

GET /.well-known/matrix/server
HTTP/1.1 200 OK
Content-Type: application/json

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

請勿在未檢查 Matrix 發現要求和用戶端行為的情況下，使用重定向到無關主機作為替代方案。請確保伺服器名稱主機已配置有效的 HTTPS 證書，並且在您變更伺服器名稱時，Cloudflare 不會快取過時的發現回應。

7. 保持 API 流量動態變化，並將上傳量控制在限制範圍內。

不要快取已認證的 Matrix API 回應。新增 Cloudflare 快取規則以繞過 Matrix API 路徑（包括 `<path>`/_matrix/*和`<path>`）的緩存，/_synapse/client/*除非您有經過充分測試的理由需要對特定的公共回應進行特殊處理。避免使用範圍過廣的 WAF 或機器人規則來質疑或阻止聯合端點；聯合請求來自許多獨立的伺服器。如果必須使用安全規則，請在全面實施之前，針對用戶端登入、同步、媒體上傳和聯合請求進行測試。

上傳檔案大小有多個獨立的限制：客戶端限制、Cloudflare 套件或區域上傳設定、反向代理的請求體大小限制以及 Synapse 的限制max_upload_size。 413 錯誤表示請求被上述限制之一拒絕。 Cloudflare 會公佈與套餐相關的上傳限制，並指出這些設定可以在文件規定的範圍內進行調整：請參閱Cloudflare 的 413 故障排除頁面。僅提高必要的限制，並在進一步提高限制之前，使用小於配置上限的檔案進行測試。

8. 驗證客戶端存取、發現和聯合

請在伺服器網路以外的電腦上執行這些檢查。請替換範例中的主機名稱：

curl -i https://example.com/.well-known/matrix/client
curl -i https://example.com/.well-known/matrix/server
curl -i https://matrix.example.com/_matrix/client/versions
curl -i https://matrix.example.com/health

前兩個請求應傳回 HTTP 200 狀態碼、JSON 內容以及預期值。客戶端文件應包含 CORS 標頭。客戶端版本端點應透過 Cloudflare 從 Synapse 傳回 JSON 資料。 Synapse 健康端點在透過已設定的監聽器存取時會傳回 HTTP 200 狀態碼，但它不能取代登入或聯合驗證檢查。

然後使用以 `<your_id>` 結尾的 ID 透過 Matrix 用戶端登錄:example.com，加入一個託管在其他伺服器上的房間，並確認訊息和成員更新是否同步。使用 Matrix 聯盟測試器或第二個主伺服器來驗證伺服器發現和聯盟。成功請求 `<your_id>`/_matrix/client/versions僅證明面向客戶端的路由有效；它並不能證明聯盟發現、簽署或出站聯盟正確。

成功的標誌是什麼——以及何時需要改變設計

• 用戶端透過 Cloudflare 連線： DNS 解析為 Cloudflare 位址，HTTPS 使用預期的證書，Matrix 用戶端 API 傳回回應。
• 發現結果正確：兩個知名 URL 都回傳了正確的 JSON，並且客戶端文件通過了跨域檢查。
• 聯合身份驗證成功：遠端伺服器發現您發布的端點並可以交換房間狀態。如果 443 連接埠委派失敗但直接 8448 連接埠有效，請檢查已知記錄、代理路徑路由和 Web 應用防火牆 (WAF) 規則。
• 上傳功能在預期大小範圍內有效：測試上傳一個代表性的檔案。如果小檔案上傳成功，但大檔案上傳失敗（返回 413），請檢查所有四個檔案大小限制，而不僅僅是更改 Synapse 的設定。
• 此來源位址並非備用公共路徑：直接發送至該來源位址的請求應依設計被封鎖或限制。如果請求仍能到達 Matrix 服務，請修正防火牆和受信任代理程式的設定。

如果您的需求或實作無法在 443 連接埠上路由聯盟，請使用 8448 連接埠上的僅 DNS 聯盟。但請注意，這會暴露來源位址，並移除 Cloudflare 對該主機名稱的 HTTP 代理保護。 Spectrum 是另一個非標準連接埠的選擇，但需視產品可用性和套餐限製而定。 Cloudflare 代理程式也意味著 TLS 連線會在 Cloudflare 終止，然後再建立與您的來源伺服器的第二個 TLS 連線；Matrix 端對端加密可以保護加密訊息內容，但不會隱藏連接元資料或未進行端對端加密的內容，從而保護 HTTP 請求處理服務。請根據您的隱私權、聯盟和可用性要求選擇拓撲結構，並在變更 DNS、憑證、Synapse 或 Cloudflare 規則後重新測試。