透過操作解決矩陣房間管理員權限錯誤
追蹤 M_FORBIDDEN 到房間功率等級、成員資格或 Synapse 伺服器管理員存取權限,然後僅恢復被封鎖操作所需的權限。
要讓 Matrix Synapse 主伺服器加入聯盟,首先要使其伺服器名稱可透過 HTTPS 從公共互聯網被發現和訪問,然後將 Matrix 伺服器之間的請求路由到 Synapse。在常見的設定中,反向代理程式會處理 443 連接埠上的 TLS 連接,並且需要透過/.well-known/matrix/server設定檔將您的 Matrix 網域指向該代理程式。如果 Synapse 已經在 8448 連接埠上回應您的伺服器名稱域名,則可能不需要進行委託。
本教學使用 `<your-host-name>`example.com作為永久 Matrix 伺服器名稱,`<your-host-name>`matrix.example.com作為機器或代理端點。請將兩者替換為您自己的名稱。主伺服器儲存 Matrix 帳戶和房間;聯盟允許主伺服器之間進行通訊。 DNS、防火牆規則、代理語法、容器網路和憑證取決於您的主機。
決定使用者的 Matrix ID 格式是 `<your_id> @name:example.com` 還是 `<your_id> `。 ` <your_id>`@name:matrix.example.com的值將成為 Matrix ID 和房間地址的一部分。 Synapse 的安裝文件建議在安裝前選擇此設置,因為之後更改此設置會產生不良後果。如果 Synapse 已在使用中,請勿僅為了匹配網址而更改此設定;請使用委派功能來保留現有 ID。server_namehomeserver.yaml

在編輯之前,請確保您可以存取 Synapse、代理伺服器和公共 DNS,並且擁有有效的聯合端點 TLS 憑證。備份homeserver.yaml簽署金鑰,該金鑰用於驗證主伺服器的身份。請妥善保管該密鑰;常規的聯合設定不需要重新產生它。
8008Synapse 通常監聽反向代理伺服器後面的HTTP 連接埠。在接收代理流量的監聽器中,需要進行相應設置,x_forwarded: true以便 Synapse 可以使用代理伺服器轉送的客戶端位址和協定。代理伺服器必須設定正確的 HTTPX-Forwarded-For和X-Forwarded-ProtoHTTPS 標頭,而不能傳遞外部客戶端提供的任意值。

當代理程式運行在同一主機上時,綁定到目標位址127.0.0.1是合適的。如果代理程式位於其他容器或機器上,則不適用,除非該位址可從代理程式存取。在容器部署中,請使用代理程式可以存取的網路位址或服務名稱,並透過容器網路或防火牆限制存取。保留現有的監聽器結構並編輯相關值;不要盲目地將程式碼片段貼到其他配置上。
設定代理程式的 HTTPS 虛擬主機,將兩個請求都轉/_matrix送到/_synapse/clientSynapse 的 HTTP 監聽器。第一個路徑承載 Matrix API,包括聯合身份驗證;第二個路徑用於 Synapse 用戶端端點。請遵循代理軟體的官方範例,保留請求路徑,並傳送 Synapse 期望的轉送標頭。請勿規範化、解碼或重寫 URI 路徑:如果代理程式變更了編碼後的路徑,Matrix 請求簽章可能會失敗。

Nginx、Caddy、Apache、負載平衡器和託管主機的具體配置各不相同。請參考供應商目前的語法和Synapse 反向代理文件。僅提供代理規則來服務 Web 用戶端,而忽略聯合 API 路徑是不夠的。
例如,matrix.example.com必須解析到代理或負載平衡器,且連接埠443必須可從外部存取。代理需要有效的證書matrix.example.com。如果您直接在提供聯邦服務example.com:8448,請發布該路由和憑證並開啟連接埠8448。可以使用預設的直接端口 8448,也可以委託給其他主機和端口,例如 443。
請確認 DNS、防火牆或雲端安全群組規則以及來自私有網路外部的憑證。如果前端使用了 CDN 或隧道,其是否支援所需的 Matrix 流量取決於該服務的當前配置;請查閱其文件並測試實際路由,而不是想當然地認為相容。
如果 Matrix ID 網域為 ,example.com但 Synapse 可透過 訪問matrix.example.com:443,則透過 HTTPS 在 提供此 JSON https://example.com/.well-known/matrix/server:
{
"m.server": "matrix.example.com:443"
}

本例中明確指定了端口 443;如果省略端口,Matrix 發現機制將預設使用端口 8448。請勿將此文件與 ` /.well-known/matrix/client<server-name>.jsp ...
Matrix 規範定義了聯邦發現機制,Synapse 提供了相關文件。 Matrix 規格允許透過以下方式進行發現/.well-known/matrix/server:在選擇其他方法(例如 SRV 記錄)之前,請務必查看Synapse 的委託指令,因為 SRV 記錄也會影響 TLS 預期。
從伺服器私有網路以外的機器請求發現 URL。它應該透過 HTTPS 傳回上述 JSON 對象,且不包含登入頁面、HTML 重定向、憑證警告或無關網站。然後檢查委託的主機名稱是否解析、其憑證是否有效,以及其通告的連接埠是否能存取 Synapse。測試前,請使用代理程式的設定檢查器並重新載入。
最後,在官方的Matrix Federation Tester中輸入您的伺服器名稱(例如,example.com而不是委派主機名,除非它是您的) 。 Synapse聯盟指南也建議透過加入公共房間(例如)進行測試。測試成功表明常見的發現和可及性檢查已通過;但這並不能保證每個遠端伺服器或每個房間操作都能正常運作,因為遠端策略和網路狀況各不相同。server_name#synapse:matrix.org
如果測試人員報告無法存取您的伺服器,請檢查其嘗試的網域名稱和連接埠、DNS、防火牆規則、憑證名稱、代理路徑、轉送的標頭,以及重新導向是否變更了請求。目前的 Synapse 聯盟文件特別警告,在某些情況下,Synapse 的聯盟伺服器可能不會遵循 HTTP 308 重定向。請避免依賴 308 重定向來存取聯盟端點,並在修正後重新測試。有關特定版本的行為,請參閱與您安裝的 Synapse 版本相符的文件。
聯盟需要遠端主伺服器發現並存取您的聯盟 API。僅憑配置無法確定這是否適用於所有遠端伺服器。請使用測試工具和實際房間加入來確認路由,然後調查特定的故障端點或錯誤。
這些介面面板是配置和發現資料的示意圖範例,並非即時伺服器的螢幕截圖。文件參考資料已於2026年10月10日核實。
追蹤 M_FORBIDDEN 到房間功率等級、成員資格或 Synapse 伺服器管理員存取權限,然後僅恢復被封鎖操作所需的權限。
設定 Synapse 發現、HTTPS 和代理路由,以便其他 Matrix 主伺服器可以找到並聯絡您的伺服器。
配置 Keycloak OIDC 用戶端和 Synapse 提供程序,以便 Element Web 使用者可以透過您的身分伺服器登錄,而無需暴露客戶端金鑰。
儲存恢復金鑰,驗證您的 Element 會話,並檢查加密訊息金鑰是否可以恢復,而不會將備份與您的帳戶密碼混淆。
診斷 Synapse 在同步過程中記憶體不足的故障,安全地調整緩存,識別請求積壓,並驗證穩定的記憶體使用量。
追蹤矩陣聯合憑證故障到正確的伺服器,修復 TLS 鍊或 CA 信任,並在不停用安全檢查的情況下驗證修復。
Route Matrix 用戶端和透過 Cloudflare 在 HTTPS 443 上進行聯合,可以保留 Synapse 探索功能,避免快取 API 流量或中斷媒體上傳。
使用 pg_dump 備份 Synapse,保護其簽章金鑰和介質,並將其還原到乾淨的 PostgreSQL 資料庫中,而無需重複使用過時的一次性金鑰。
使用專用 Matrix 帳戶、加密管理室、Docker Compose、政策清單和權限檢查來設定 Mjölnir。
跳過已停用的代理,配置 Synapse 內建的滑動同步功能。檢查客戶端發現情況,然後在相容的手機上測量房間清單載入和重新連接行為。