如何在 Matrix 中設定橋接器：WhatsApp、Telegram 和 Discord

若要將 Matrix 與 WhatsApp、Telegram 或 Discord 連接起來，請在您的主伺服器旁執行相容的橋接服務，將該服務註冊為 Matrix 應用程式服務，然後連結或授權外部帳戶。每個網路都需要自己的橋接配置和憑證。僅運行進程並不能證明房間已橋接：設定完成後，請測試雙向訊息。

本指南使用mautrix-whatsapp和mautrix-telegram，以及 Matrix.org 專案的matrix-appservice-discord（用於 Discord）。橋接器是一個獨立的伺服器端程序，而不是 Element 中的開關。 Matrix 規範將這種整合稱為應用程式服務：它接收相關的 homeserver 事件，並且可以在為其註冊的命名空間內建立使用者或房間。請參閱Matrix 技術概述和應用程式服務 API 規格。

應該自行託管橋接器還是使用公共執行個體？

自託管網路橋接服務讓您可以控制橋接服務的運作位置、日誌和憑證的儲存方式以及哪些使用者可以連線。這也意味著您需要維護三項服務，負責更新、保護資料庫以及排查連線故障。公共橋接服務可能速度更快，但其營運商控制可用性、存取策略和資料處理。在選擇實例之前，請務必查看橋接服務的最新文件和支援中心；可用性和功能可能會變更。

這些連線並不等同於訊息服務的原生支援。橋接功能可能因網路而異，語音/視訊通話、表情反應、編輯、主題、已讀回執、歷史記錄或群組管理等功能可能不完整。在遷移重要對話之前，請務必測試您的社群實際依賴的功能。

安裝任何設備前需要準備什麼？

• Matrix 主伺服器支援應用程式服務，並允許管理員註冊這些服務。以下範例使用 Synapse；其他主伺服器有各自的註冊流程。
• 主伺服器與每個網橋之間需要一條可達的網路路徑。在 Docker 中，localhost「容器內部」指的是容器本身；當主伺服器需要存取另一個容器時，請使用共用的 Docker 網路以及網橋服務的網路名稱。
• 每個網橋都需要獨立的配置、註冊檔案、持久化資料位置和金鑰儲存。請遵循目前專案說明，了解支援的資料庫、執行時間版本和容器鏡像；具體要求可能有所不同且會發生變化。
• 對於 WhatsApp，需要一部已登入您計劃關聯的帳號的手機。對於 Telegram，需要已透過官方 Telegram 用戶端登入的帳號。對於 Discord，需要 Discord 應用程式/機器人以及伺服器擁有者或管理員的許可。

如何在 Synapse 中註冊橋接器？

1. 一次部署一個橋接器。首先使用最新版本及其範例配置。根據該專案的指南設定主伺服器位址、公用伺服器名稱、橋接器監聽器位址、資料庫和儲存路徑。避免不相關的橋接器服務共用同一個資料庫。
2. 產生註冊文件。橋接器的設定程序會建立一個包含應用程式服務身分和認證令牌的註冊 YAML 檔案。請像對待密碼一樣對待這些令牌：限製檔案權限，不要將其提交到 Git，也不要將其貼到公共聊天室、螢幕截圖或支援貼文中。
3. 確保 Synapse 可以存取該檔案。複製或掛載註冊檔案到 Synapse 程序可以讀取的位置。app_service_config_files在 Synapse 的 ` <path>` 中新增該檔案的路徑homeserver.yaml。為每個橋接服務新增一個單獨的清單條目；不要覆蓋其他服務的條目。 Mautrix應用程式服務註冊指南描述了此流程，並指出註冊清單變更後必須重新啟動 Synapse。
4. 重新啟動並檢查日誌。註冊資訊變更後重新啟動 Synapse，然後啟動橋接。如果 Synapse 啟動失敗，請先檢查 YAML 縮排、容器內檔案路徑和讀取權限。如果橋接啟動但無法連接，請檢查 homeserver URL、網路路由、TLS 憑證和監聽器位址。

對於 Docker 部署，橋接器配置的應用程式服務位址必須能夠從 homeserver 容器存取。 mautrix的初始設定說明解釋了為什麼共用網路上的容器名稱有時有效，有時無效。 Discord 專案也在上游 README 文件localhost中記錄了其自身的註冊流程和範例配置。

如何關聯WhatsApp帳號？

mautrix-whatsapp 註冊並運行後，打開一個包含其橋接機器人的私人 Matrix 聊天視窗並發送驗證碼login qr。在擁有該帳號的手機上開啟 WhatsApp，前往「已關聯裝置」，掃描橋接機器人顯示的驗證碼。橋接機器人的文件中還介紹了一種使用手機號碼配對碼的方法；請使用您目前安裝的版本支援的方法。請勿將登入碼或二維碼複製到公共聊天室。

配對期間請保持手機和帳號可用，並在開啟入口網站房間前確認橋接器報告登入成功。此操作透過類似伴侶設備的方式連接帳號；它不會將橋接器轉換為官方的 WhatsApp Business API 整合。 WhatsApp 可能會變更裝置連線行為，因此請遵循目前的 mautrix-whatsapp 驗證說明。橋接器可能只會同步外部服務提供給已連接設備且橋接器已實現的歷史記錄。

如何連接 Telegram？

與 mautrix-telegram 機器人發起私聊。此橋接器支援二維碼登入和向已登入的 Telegram 用戶端發送的六位登入碼；它不會註冊新的 Telegram 帳戶。若要使用二維碼登錄，請在手機上開啟 Telegram，依序進入「設定」>「裝置」>「關聯桌面裝置」，然後向橋接機器人發送login qr驗證碼並掃描其二維碼。如果您的 Telegram 帳戶已啟用兩步驟驗證，請按照機器人的提示操作。

請使用已建立的帳戶並遵守 Telegram 的登入規則。橋接維護者提醒，Telegram 可能會將使用第三方用戶端的新帳戶視為可疑帳戶；這是平台層面的風險，Matrix 管理員無法保證完全消除。登入前請閱讀mautrix-telegram 驗證指南，並將所有一次性驗證碼或密碼保存在私密機器人聊天中。

如何配置Discord？

matrix-appservice-discord 專案使用 Discord 應用程式和機器人。請在Discord 開發者入口網站建立應用，建立/配置機器人用戶，並使用專案目前的範例在橋接配置中設定機器人憑證。請勿公開機器人令牌。執行橋接文件中提供的 authorization-link 命令或流程，然後由 Discord 伺服器擁有者僅授予橋接所需的權限，授權機器人存取目標伺服器。

對於特定頻道，請使用 Discord 支援的開發者工具取得其伺服器 ID 和頻道 ID，邀請 Matrix 端橋接機器人加入 Matrix 房間，並使用該橋接機器人文件中提供的房間指令。上游 README 文件提供了一個範例!discord bridge ServerID ChannelID；可能需要管理員批准才能完成連結。請勿使用範例中的 ID：請將其替換為實際的標識符，並根據您已安裝版本的 README 檔案確認命令和權限。

Discord 對機器人權限和伺服器策略的依賴性很高。如果機器人可以加入但訊息無法發送，請檢查頻道是否對機器人可見，是否已授予所需的訊息權限，以及橋接器是否已完成任何管理員確認。此專案在其 README 文件中標明為 beta 版，因此請確認專案的當前狀態和支援的功能，而不是假設 Discord 的所有功能都已完全復刻。

如何驗證橋樑是否正常運作？

首先使用小型私人測試房間和低風險頻道。從 Matrix 發送一條唯一的純文字訊息，並確認該訊息出現在遠端服務中；然後從遠端回覆該訊息，並確認回覆出現在 Matrix 中。如果歸屬、回覆線程、附件、編輯和反應等因素對您的使用場景至關重要，請分別檢查這些功能。綠色進程狀態僅表示程式正在運行，並不代表登入成功、機器人擁有頻道存取權限或房間到頻道的對應正確。

測試失敗時，請將訊息的確切時間與橋接器和主伺服器日誌進行比較。共享日誌前，請編輯存取權杖、電話號碼、敏感的 Discord ID 和聯絡人姓名。對於容器部署，也要檢查登錄檔案是否已掛載到 Synapse 中，橋接器端點是否在共用網路上解析，以及防火牆是否封鎖了已設定的監聽器。

關於加密和隱私，您應該了解哪些內容？

應用程式服務會在其配置處理的命名空間和房間中接收事件。請勿假定所有網橋都能自動讀取加密的 Matrix 房間。某些 Mautrix 橋接器支援端對端加密，這需要進行專門配置，並且有其自身的金鑰管理要求；請參閱Mautrix 端對端加密指南並確認特定網橋是否支援此功能。 Discord 橋接器的加密功能可能有所不同。如果某個網橋無法處理房間的加密模式，請使用合適的未加密測試房間，或選擇一個有文件支援的網橋，而不是透過猜測來削弱生產房間的安全性。

最後，請記住，訊息內容和帳戶憑證會經過您或公共橋接營運商營運的軟體。限制橋接機器人的邀請權限，保護資料庫和備份，如果令牌洩漏則進行輪換，並查看橋接當前的隱私和安全指南。升級前請重新檢視上游文件：設定金鑰、登入流程、依賴項和平台策略都可能獨立變更。

快速決策清單

• 選擇您信任的電信業者和存取原則的橋接執行個體。
• 分別註冊每個橋接器並保護每個產生的令牌。
• 部署完成後，驗證 homeserver 是否可以連接到橋接位址。
• 將 WhatsApp/Telegram 帳號私下關聯，並由伺服器管理員授權 Discord 機器人。
• 測試雙向訊息傳遞，然後僅測試您需要的額外功能。
• 在依賴橋接器進行敏感或重要通訊之前，請確認是否支援加密、歷史行為和維護狀態。