如何設定矩陣滑動同步以加快行動裝置載入速度（無需傳統代理）

更新，2026 年 10 月 6 日：獨立的 Matrix Sliding Sync 代理程式不再是合適的安裝元件。 Matrix.orgmatrix-org/sliding-sync已於 2025 年 11 月存檔了其程式碼庫，因為它實作了較舊的 MSC3575 API，該 API 已被簡化滑動同步 (MSC4186) 取代。 Synapse 自 1.114 版本起已支援原生實現，並且預設為啟用。 2026 年 7 月，Matrix 規範核心團隊接受了 MSC4186 核心提案；相關的擴展提案仍需單獨進行。

對於現代 Synapse 行動部署，實際操作方法是執行最新版本的 Synapse，確認其支援原生滑動同步功能，確保反向代理能夠正確傳遞 Matrix 用戶端 API 路徑，並使用相容的行動用戶端。無需單獨的代理容器、代理資料庫和舊的代理發現 URL。

是否還需要安裝獨立的 Sliding Sync 代理程式？

不，這不適用於現有 Matrix 行動用戶端的新部署。已存檔的代理程式實現的是 MSC3575，而非更新的原生 MSC4186 流。該專案的官方倉庫已聲明停止維護，並且預計現代 Matrix 用戶端將不再與其相容。 Matrix.org 也宣布將於 2025 年 1 月從 Element X 移除對 MSC3575 代理程式的支持，轉而支持原生 MSC3575。

歷史代理指南在識別舊版代理程式時可能仍然有用：它使用了 PostgreSQL、持久性金鑰和SYNCV3_*環境配置。這些說明描述的是一種已棄用的架構。不要僅僅因為舊教程聲稱速度更快，就將其複製到新伺服器或公開舊版代理。

發生了哪些變化？這對行動用戶意味著什麼？

早期的代理是一個獨立的服務，位於客戶端和其主伺服器之間。簡化的滑動同步功能已整合到 Synapse 中。它允許相容的客戶端請求用戶房間清單的相關視窗並進行增量更新，從而減少行動應用程式在開啟或返回大型帳戶時需要執行的同步工作量。

這只是同步方面的改進，並不能保證每個螢幕都能瞬間載入。它無法解決媒體伺服器速度慢、遠端房間加入延遲、行動網路訊號弱或資料庫繁忙等問題。行動應用必須支援 MSC4186，且主伺服器必須廣播該協定。 Matrix.org 的公告指出，原生 Synapse 實作避免了舊代理伺服器的獨立資料儲存和初始完全同步的限制。

啟用該功能前需要準備什麼？

Matrix 家庭伺服器執行 Synapse。本指南不假設 Dendrite、Conduit 或其他家庭伺服器提供相同的原生實作。
Synapse 1.114 版本已持續維護。此版本引入了對 MSC4186 的原生支持，但建議使用目前受支援的版本，而不是將 1.114 版本視為安全或維護建議。
支援簡化滑動同步的行動用戶端。功能完善的伺服器無法讓舊版客戶端使用它本身未實現的 API。
適用於家庭伺服器的可用 HTTPS 用戶端端點和反向代理配置。
在升級或變更伺服器路由之前，請先備份資料庫和設定。

如何檢查 Synapse 是否已經宣傳原生滑動同步功能？

從終端查詢公共客戶端-伺服器 API 版本端點。將範例主機替換為您的 Matrix 用戶端使用的公共基本 URL：

curl -fsS https://matrix.example.org/_matrix/client/versions   | jq -r '.unstable_features["org.matrix.simplified_msc3575"]'

如果回應為true真，則表示伺服器啟用了原生的簡化滑動同步功能標誌。如果回應為假false、null假或缺少某個鍵，則表示在測試用戶端之前，您應該檢查 Synapse 版本和配置。如果 Synapsejq未安裝，請在瀏覽器中要求相同的 URL，或執行命令curl -fsS https://matrix.example.org/_matrix/client/versions並檢查 JSON 回應。

此標誌是伺服器的功能訊號；它並不能證明特定應用程式版本相容，也不能證明所有反向代理路由都正確。請使用版本說明中明確支援原生滑動同步的用戶端，並在其日誌或瀏覽器/網路診斷資訊（如有）中驗證請求路徑。

如何在 Synapse 中啟用原生支援？

Synapse 1.114 及更高版本預設啟用原生滑動同步功能。如果版本回應已為 1.114 true，通常無需安裝單獨的服務，也無需建立新的同步資料庫。請勿僅因舊版指南中描述了代理就隨意添加推測性配置。

如果此功能已在 Synapse 設定中明確停用，請檢查以下設定experimental_features。在使用了已記錄標誌的版本中，相關的 YAML 程式碼如下：

experimental_features:
  msc3575_enabled: true

僅在查閱已安裝 Synapse 版本的設定文件後，方可新增或變更此設定。備份文件homeserver.yaml，保留現有程式碼區塊的其餘部分experimental_features，並保持 YAML 縮排一致。使用 Synapse 針對您安裝的設定驗證指令驗證該文件，然後透過您已使用的服務管理員或容器編排方法重新啟動 Synapse。重啟/_matrix/client/versions後再次檢查。

如果您執行的 Synapse 版本低於 1.114，請依照官方升級說明進行升級。閱讀版本更新說明，備份資料庫和媒體/配置文件，並按照適用於您部署環境的官方支援升級路徑進行操作。切勿將主伺服器升級、反向代理重寫和舊代理移除合併到一次未經驗證的變更中。

您的反向代理是否需要特殊的滑動同步路由？

通常情況下不需要。原生滑動同步使用 Matrix 用戶端伺服器 API 路由/_matrix/client，因此您現有的反向代理程式應該將 Matrix 用戶端 API 命名空間轉送給 Synapse。 Synapse 官方反向代理指南建議轉發 Matrix 用戶端 API 命名空間/_matrix，並/_synapse/client保留請求 URI，而不是對其進行規範化或歸一化。

/_matrix/client/versions如果代理規則正常但相容的應用程式無法同步，請檢查代理程式規則。確認請求能夠/_matrix/client/unstable/org.matrix.simplified_msc3575/到達 Synapse，並且沒有被傳送到殘留的 MSC3575 代理程式、被 Web 應用防火牆阻止或被路徑規則重寫。如果 Synapse 運行在代理伺服器之後，請保留 Synapse 文件中所述的正確的轉送協定和用戶端 IP 標頭。

不要為原生支援建立新org.matrix.msc3575.proxy條目/.well-known/matrix/client。此鍵值標識的是已棄用的代理程式 API。如果您之前已將其新增至靜態的、眾所周知的 JSON 檔案或 Synapse 中extra_well_known_client_content，請在確認沒有其他舊用戶端依賴於該屬性後，僅移除該舊版代理程式屬性。請保留正常的 homeserver 發現資訊。

如何遷移現有的代理伺服器？

記錄目前 Synapse 版本、用戶端版本、代理 URL、反向代理路由以及舊代理程式的資料庫和金鑰位置。
備份主伺服器資料庫、設定和代理資料庫。保留這些備份，直到驗證原生用戶端登入和同步功能正常為止。
如果 Synapse 版本低於 1.114，請依照其記錄的發佈路徑進行升級，然後確認本機功能標誌會回傳true。
將行動用戶端更新至支援原生簡化滑動同步的版本。請依照應用程式內的任何遷移或重新登入提示操作。部分現有會話可能需要重新登入才能從舊協定遷移。
移除已停用的代理廣告，並將 Matrix 用戶端 API 路徑路由至 Synapse。重新載入反向代理，並在應用之前檢查其配置。
先使用一個帳號和一個行動裝置進行測試。確認登入、房間清單載入、開啟加密房間、收發訊息、切換網路後重新連線等功能正常。
在您所支援的客戶測試成功後，停止舊版代理。保留其資料庫備份至約定的回溯視窗期；僅在確認不再需要舊資料後才刪除。

代理資料庫保存的是代理端的同步狀態，而不是 Synapse 的房間歷史記錄。不過，在初始遷移過程中，請避免刪除該資料庫：它為排查舊版配置問題提供了參考，並在使用者遷移到原生會話時提供了更安全的回滾邊界。

如何判斷行動端載入速度是否有提升？

如果您有可靠的基準測量數據，請在變更前後與同一用戶端、帳戶、裝置和網路進行比較。記錄從開啟應用程式到顯示可用聊天清單所需的時間、最近訊息是否能正常顯示（無需長時間載入），以及應用程式在短暫離線後是否能恢復正常。請重複此對比多次；單次啟動可能會受到快取狀態、網路狀況或大型媒體下載的影響。

如果客戶端仍然執行普通/sync請求，從未聲明或嘗試使用原生支持，請檢查客戶端版本及其自身的同步設定。如果用戶端要求簡化端點但收到錯誤，請檢查 Synapse 和反向代理程式日誌中該要求的日誌。如果許多使用者報告載入緩慢，請檢查資料庫運作狀況和伺服器負載。滑動同步可以減少同步工作量，但無法彌補資料庫過載或 API 請求路由錯誤的問題。

主要的設定選項有哪些？

方法	最佳匹配	成本或限制
Synapse 中的原生簡化滑動同步	新建或維護的 Synapse 部署和相容客戶端	需要相容的客戶端；效能仍取決於伺服器和資料庫的運作狀況。
傳統 MSC3575 代理	僅用於理解或暫時維護舊的測試環境	已存檔、不再維護，並且不再適用於現代客戶端。
傳統矩陣同步	不支援原生滑動同步的客戶端或家庭伺服器	對相容客戶端仍然有效，但不提供相同的原生滑動房間清單行為。

來源和版本說明

獨立代理存儲庫已存檔。 Synapse 的原生實作可追溯至 Synapse 1.114 版本。 Matrix 規範核心團隊於 2026 年 7 月接受了 MSC4186 核心提案，而相關擴展仍保持獨立。 Synapse、行動用戶端和 Matrix 規格都在不斷發展，因此請查閱文件和發行說明，以了解您目前正在執行的確切版本。