使用 Docker 將 Mjölnir 運行為 Matrix Room 管理機器人
使用專用 Matrix 帳戶、加密管理室、Docker Compose、政策清單和權限檢查來設定 Mjölnir。
對於目前的 Matrix 行動用戶端,請勿將舊的獨立滑動同步代理程式新增至 Docker Compose 中。該代理程式已於 2025 年 11 月歸檔;Synapse 本身提供原生簡化滑動同步功能,該功能自 Synapse 1.114 版本起預設為啟用。請將 Synapse 更新至支援的版本,檢查用戶端是否可以透過您的公用 URL 存取原生功能,並在支援該功能的用戶端上測量負載。
「滑動同步」最初指的是 MSC3575 的代理實現,它位於 Synapse 前端,需要單獨的服務和發現設定。 Matrix 規範不斷發展:MSC4186(簡化滑動同步)取代了此設計。官方代理庫已存檔,並聲明現代客戶端不再需要與其相容。 Synapse 已新增對 MSC3575 和 MSC4186 的原生支持,並從 v1.114.0 版本開始預設啟用,具體內容記錄在Synapse 更新日誌中。
本指南假設 Synapse 已透過 Docker Compose 運行在公共 HTTPS URL(例如 `https://localhost:3000`)之後https://matrix.example.org。您需要對 Compose 專案擁有 shell 存取權限,能夠編輯其鏡像標籤和 homeserver 配置,並且需要一個目前版本支援原生滑動同步的行動應用程式。如果您只是想在不支援滑動同步的用戶端上加快初始載入速度,新增代理程式並不能使該用戶端使用此功能。
請使用目前維護的 Synapse 版本,而不是將新部署版本限制在歷史最低功能版本。請查閱Synapse 官方版本發布說明以及您要升級的來源版本的升級說明。升級前備份資料庫和 Synapse 資料/配置卷,並檢查升級說明中是否要求進行中間升級步驟。這點對於舊版本尤其重要:Synapse針對滑動同步房間狀態洩漏的安全公告列出了受影響的版本(最高至 v1.120.0),並在 v1.120.1 中修復了該問題。請選擇包含後續修復程式的目前支援版本,而不僅僅是第一個已打補丁的版本。
在您的 Compose 檔案中,找到 Synapse 的服務金鑰及其使用的鏡像標籤。如果該標籤指向的是舊版本,請將其變更為您選擇的受支援版本。然後,僅拉取並重新建立該服務;synapse如果您的服務名稱不同,請取代以下內容:

docker compose pull synapse

docker compose up -d synapse
docker compose logs --tail=100 synapse
請先查看日誌,確認是否有啟動錯誤以及資料庫升級是否已完成,然後再繼續操作。若啟動失敗,切勿盲目降級;請參考特定版本的升級指南,並僅使用適用於您資料庫的復原流程來還原備份。
Synapse 通常預設啟用原生滑動同步功能,因此全新安裝通常無需額外添加 YAML 檔案。此設定保留了舊的 MSC 名稱,這可能會造成混淆:它控制 Synapse 的原生實現,而不是請求運行已棄用的代理程式。請檢查現有配置中homeserver.yaml是否有明確的 false 值。如果發現,請在現有功能區塊中進行變更:

experimental_features:
msc3575_enabled: true
如果experimental_features該組態項已存在,請編輯該組態項,而不是新增重複的 YAML 鍵。如果該設定不存在或已為真,則無需修改。配置變更後,請重新建立 Synapse 服務並檢查其日誌。 YAML 縮排錯誤可能會導致 Synapse 無法啟動。
檢查提供的 JSON 資料https://matrix.example.org/.well-known/matrix/client。如果其中包含舊org.matrix.msc3575.proxy屬性,請移除該屬性,同時保留無關的用戶端發現條目。此外,移除任何將 Matrix 用戶端要求傳送至已停用代理程式的反向代理規則;標準/_matrix/client/API 路徑必須能夠存取 Synapse。不要為原生 MSC4186 新增新的代理連接埠或發布代理 URL。根據您的設置,保留任何其他已知值,包括您的主伺服器 URL。
從一台可以存取公共主伺服器的機器上,查詢客戶端-伺服器版本端點。這將檢查客戶端實際發現的服務,而不僅僅是檢查私有 Docker 網路上的容器:

curl -fsS https://matrix.example.org/_matrix/client/versions | jq '.unstable_features["org.matrix.simplified_msc3575"]'
對於已啟用原生支援且路由正確的端點的 Synapse 版本,此操作應輸出結果true。如果jq結果不可用,請執行curl不含管道符的請求並檢查 JSON 欄位。缺失值或 false 值是有用的故障訊號:請驗證 DNS 和 HTTPS 是否連接到預期伺服器,反向代理是否將用戶端 API 路徑傳遞給 Synapse,執行的鏡像是否是您選擇的版本,以及是否有明確配置停用該功能。共用診斷輸出時請勿揭露存取權杖;此公用版本請求不需要存取權杖。
使用與對比測試相同的帳號和手機,登入或重新連線支援原生協定的用戶端版本。如果可能,在更改伺服器之前記錄基線資料。只有當您了解清除或重建本機應用程式資料會移除快取內容時,才比較冷啟動後的應用程式;然後比較正常的熱啟動和手機離線後重新連線的情況。保持網路、帳號、房間設置和測試方法的一致性。
更快的首次房間清單載入速度以及重新連線後流暢的同步是客戶端正在使用預期路徑的實用標誌。速度提升並非一成不變:客戶端實作和本地快取、網路延遲、資料庫效能、帳戶房間數量以及伺服器負載都會影響最終結果。滑動同步也無法加速媒體下載或修復過載的資料庫。如果功能檢查通過但應用程式仍然運行緩慢,請先比較其他支援的用戶端,並在更改代理程式或快取設定之前排查瓶頸。如果您仍在執行依賴已停用的 MSC3575 代理程式的舊用戶端,請在移除其舊的發現路徑之前單獨測試其相容性;不要想當然地認為一個端點可以服務所有用戶端。
使用專用 Matrix 帳戶、加密管理室、Docker Compose、政策清單和權限檢查來設定 Mjölnir。
跳過已停用的代理,配置 Synapse 內建的滑動同步功能。檢查客戶端發現情況,然後在相容的手機上測量房間清單載入和重新連接行為。
將 Element Web 部署為靜態站點,將其指向您的 Matrix 主伺服器,新增 HTTPS,並配置 Nginx 以提供更新而不會出現過時的檔案。
在 64 位元 Raspberry Pi 4 上設定 Conduit,使其具有持久性資料、HTTPS 聯合身份驗證、受保護的註冊以及對正常工作的家庭伺服器的檢查。
使用 Element 或 Matrix API,在您的網域上為 Matrix 房間分配一個易於共享的地址,並檢查權限、Synapse 命名和聯合。
使用匹配的 TURN 憑證配置 coturn 和 Synapse,打開所需的中繼端口,並驗證 Matrix 用戶端是否可以取得中繼候選位址。
使用 Docker Compose、PostgreSQL、私人配置和檢查來設定持久的 Synapse 主伺服器,然後再透過 HTTPS 公開它。
為您的 Element Web 部署設定品牌名稱、自訂色彩和登入資源,同時了解哪些部分仍保留 Element 品牌。
診斷 Synapse 是否達到其每個程序開啟檔案上限,為正確的服務或工作進程設定 systemd drop-in,並驗證即時限制。
確定錯誤是否僅限於一個瀏覽器或一個事件,然後使用 Element 的恢復金鑰或受信任的設備,而不會危及您剩餘的加密歷史記錄。