使用獨立橋接器將 Matrix 連接到 WhatsApp、Telegram 和 Discord

要連接 WhatsApp、Telegram 和 Discord,需要執行三個獨立的橋接程序,將每個程式註冊為應用程式服務,並透過各自的登入流程進行登入。成功意味著每個機器人都會報告已驗證的會話,並且測試訊息可以在門戶房間內雙向傳輸;機器人僅顯示在線狀態是不夠的。

這是為允許應用程式服務的家庭伺服器管理員準備的。除非 matrix.org 的管理員提供,否則您無法將自架橋接新增至 matrix.org;請使用您控制的伺服器或可用的託管橋接。專案文件已於 2026 年 10 月 10 日審核。

1. 確定要連接的設備並準備伺服器

這是三項獨立的服務,各自擁有獨立的配置、註冊、資料庫和登入流程。 Mautrix 主要採用 Puppeting 技術:訊息透過您關聯的遠端帳戶傳輸,並在 Matrix 中以該帳戶的身份顯示。中繼機器人則有所不同;只有當您希望使用共享的機器人身份而非個人帳戶時才選擇它。

你需要一台支援應用服務的主伺服器、管理員權限以及與每個網橋的網路連線。 Docker 的相關文件已發布。為每個網橋分配獨立的資料目錄,並選擇一個維護良好的版本標籤;Mautrix 指出,該標籤latest可能追蹤的是最新提交而非發布版本。

每個橋接器使用獨立的資料庫;PostgreSQL 伺服器可以共享,但資料庫本身不能與其他橋接器或 Synapse 共用。對於小型實例,可以使用 SQLite。登入前請確定是否啟用端對橋接器加密,因為之後為現有入口網站房間啟用加密會比較困難。

終端目錄列表,其中包含單獨的 mautrix-whatsapp、mautrix-telegram 和 mautrix-discord 資料夾,每個資料夾都顯示自己的配置和資料庫檔案。
在啟動容器之前,將每個橋接器的配置和資料庫保存在各自的工作目錄中。

2. 配置並註冊所有三個應用程式服務

  1. 為每個網橋產生初始配置。請依照該網橋的 Docker 設定頁面進行操作,並掛載其自身的資料目錄來執行一次容器。在正常啟動之前,編輯產生的配置。填寫主伺服器網域名稱和位址、橋接器位址、資料庫 URI 和權限。這些值特定於您的部署;請勿將範例金鑰貼到生產環境中。
  2. 使用容器可存取的位址。當 Synapse 和橋接器共用 Docker 網路時,橋接器的 homeserver 位址可以使用 Synapse 的服務名稱,例如 `<service-name> http://synapse:8008`。應用程式服務位址必須指向該橋接器的服務名稱和監聽連接埠。localhost在橋接器容器內部使用 `<service-name>` 指向的是該容器本身,而不是 Synapse 或其他橋接器,因此通常會導致通訊中斷。如果 homeserver 位於 Docker 容器外部,則應發布或路由所需的橋接器連接埠。
  3. 為每個網橋產生並安裝一個註冊文件。運行每個橋接器的設定命令以產生其註冊 YAML 文件,然後將這三個文件放置在 Synapse 可以讀取的位置。在 ` homeserver.yaml<path>` 中,加入它們的路徑app_service_config_files,例如:
app_service_config_files:
  - /data/appservices/mautrix-whatsapp-registration.yaml
  - /data/appservices/mautrix-telegram-registration.yaml
  - /data/appservices/mautrix-discord-registration.yaml

如果 Synapse 運行在 Docker 容器中,請將註冊檔案掛載到 Synapse 容器內。編輯清單後,請重新啟動 Synapse。 YAML 檔案中的拼字錯誤、路徑錯誤、掛載點無法讀取或橋接位址不符都可能導致註冊失敗或 Synapse 無法啟動。如果您之後更改了與註冊相關的橋接設置,請重新產生相應的註冊檔案並再次重新啟動 Synapse。

程式碼編輯器顯示了 Synapse homeserver.yaml,其中包含 WhatsApp、Telegram 和 Discord 的三個獨立的應用程式服務註冊路徑。
Synapse 需要為每個橋接器提供單獨的可讀註冊路徑,然後重新啟動 homeserver。
容器狀態面板顯示 Synapse 和三個 mautrix bridge 容器正在共用的 Matrix 網路上運作。
檢查 Synapse 和所有三個橋接容器是否在服務名稱可以解析的網路上執行。

3. 新增服務特定的憑證並登入

WhatsApp

啟動 mautrix-whatsapp,並開啟一個與橋接機器人(通常是)的 Matrix 直接訊息@whatsappbot:your.server。傳送訊息login qr,然後掃描手機上 WhatsApp「已關聯裝置」畫面上的二維碼。等待機器人確認身份驗證;橋接文件指出,門戶房間可能需要大約一分鐘才能顯示。 WhatsApp 是以裝置的形式關聯的,因此它不是一個獨立的雲端帳戶。橋接文件指出,如果手機離線超過兩週,關聯的設備將會斷開連線。如果您無法保持手機處於活動狀態,請在將其用於重要聊天之前,請考慮此橋接是否滿足您的可靠性需求。

電報

在登入 Telegram 之前,請在my.telegram.org/apps建立一個 API 應用,並將其 API 值新增api_id至api_hashmautrix-telegram 的配置中。這些 API 值允許橋接器連接到 Telegram 的 API;它們本身並不能驗證 Telegram 帳戶。然後發送訊息@telegrambot:your.server並使用login qr驗證碼,在 Telegram 行動應用程式中依序點擊「設定」、「裝置」和「​​關聯桌面裝置」掃描驗證碼。驗證碼選項可能會發送到現有的 Telegram 會話中,而不是透過簡訊發送,橋接器可能會提示您輸入兩步驟驗證密碼。如果匯入舊訊息很重要,請在登入前檢查橋接器的回填設定;在建立入口網站房間後變更設定可能為時已晚。

Discord

對於伺服器,請使用專用的 Discord 機器人,而不是自動化您的個人帳戶:Discord 禁止使用自建機器人,並可能終止帳戶。在開發者入口網站中建立應用程式和機器人,僅啟用橋接器所需的、您的應用程式可以獲得的特權意圖,然後使用 OAuth2 機器人權限範圍和最低頻道權限邀請它。意圖存取受策略控制;如果沒有必要的訊息內容或成員存取權限,則某些功能可能無法正常運作。在 Matrix 中,請私訊@discordbot:your.server並依照 mautrix-discord 的機器人代幣登入說明進行操作。機器人無法提供與使用者帳戶橋接器相同的個人私訊存取權限。

橋接設定編輯器顯示 Synapse 服務位址、mautrix-whatsapp 服務位址和不同的橋接資料庫名稱。
檢查每個橋接器本身配置中的服務主機名稱、橋接器監聽器和唯一資料庫詳細資訊。

4. 測試交付,然後僅根據結果進行調整

私訊每個橋接機器人並確認其身份驗證狀態。在每個服務的專用入口網站房間中,從 Matrix 發送測試訊息,並從遠端應用程式回覆。驗證訊息和回覆是否都到達了正確的房間。對於群組或 Discord 頻道,請先確認橋接帳戶存在且具有讀取/發送權限。僅成功登入並不能證明訊息已送達。

如果機器人沒有反應,請檢查其日誌,以查看是否有缺失值、資料庫錯誤或伺服器連線問題。如果登入成功但房間未顯示,請檢查入口網站和回填設定。如果 Discord 頻道訊息缺失,請檢查機器人成員資格、權限和意圖存取。如果 Synapse 啟動失敗,請驗證 YAML 縮排和註冊檔案掛載是否正確。

功能支援因橋接版本和帳戶類型而異;通話、反應、加密聊天、媒體和歷史記錄匯入可能存在差異或不支援。在將某個橋接器作為唯一存取點之前,請務必查看其目前功能清單。限制對註冊文件和憑證的訪問,安全備份橋接器數據,並在會話或令牌洩露時立即撤銷關聯會話或令牌。

請使用最新的mautrix Docker 說明、註冊指南、設定參考以及WhatsApp、Telegram和Discord 的身份驗證頁面來取得特定版本的命令。請查看 Discord 的自建機器人政策。

留下評論

無需猜測即可提高 Synapse 的 Systemd 檔案限制

無需猜測即可提高 Synapse 的 Systemd 檔案限制

診斷 Synapse 是否達到其每個程序開啟檔案上限,為正確的服務或工作進程設定 systemd drop-in,並驗證即時限制。

元素顯示“解密失敗”?恢復遺失的房間鑰匙

元素顯示“解密失敗”?恢復遺失的房間鑰匙

確定錯誤是否僅限於一個瀏覽器或一個事件,然後使用 Element 的恢復金鑰或受信任的設備,而不會危及您剩餘的加密歷史記錄。

清理舊的 Synapse 訊息和媒體檔案而不遺失數據

使用 Synapse 的歷史記錄和媒體清除 API 或保留設定安全地刪除過期數據,然後驗證完成情況和磁碟空間恢復情況。

使用 Simple-Matrix-Bot-Lib 在 Python 中建立矩陣迴聲機器人

使用 Simple-Matrix-Bot-Lib 在 Python 中建立矩陣迴聲機器人

安裝目前庫,連接專用 Matrix 帳戶,並運行一個小型 !echo 機器人,該機器人具有更安全的憑證處理和清晰的測試。

使用獨立橋接器將 Matrix 連接到 WhatsApp、Telegram 和 Discord

使用獨立橋接器將 Matrix 連接到 WhatsApp、Telegram 和 Discord

設定三個 Mautrix 橋接器,分別進行註冊、登入和測試-避免 Docker 網路、帳號原則和同步方面的意外情況。

無需破壞共用檔案即可回收 Synapse 媒體磁碟空間

尋找 Synapse 儲存空間佔用情況,設定安全媒體保留策略,並在不直接從磁碟刪除檔案的情況下清除遠端快取。

停用不活躍的矩陣用戶,而不刪除房間歷史記錄

停用不活躍的矩陣用戶,而不刪除房間歷史記錄

查看裝置活動,透過管理 API 停用已確認的非活動 Synapse 帳戶,並了解可選的擦除標誌實際刪除了哪些內容。

降低 Matrix Synapse 中的 PostgreSQL 記憶體壓力

找出 PostgreSQL 記憶體消耗是來自查詢工作、共享緩衝區、連接還是維護,然後進行有針對性的、Synapse 安全的變更。

為什麼 Matrix Synapse 會議室加入速度慢——以及需要檢查哪些方面

為什麼 Matrix Synapse 會議室加入速度慢——以及需要檢查哪些方面

在變更 Synapse 設定之前,請追蹤 Matrix 房間加入速度慢的原因,例如遠端 homeserver、聯盟退避、本機資料庫載入或出站傳送佇列。

關閉 Synapse 上的 Matrix 註冊或要求使用邀請令牌

停止在自架 Synapse 伺服器上建立公開帳戶,或保持註冊僅限邀請,並限制註冊令牌的使用次數。