使用 PostgreSQL 轉儲安全地還原 Matrix Synapse

使用 PostgreSQL 的自訂轉儲格式備份 Synapse 資料庫,排除一次性金鑰表,並將備份還原到新建的空資料庫。僅備份資料庫並不完整:還需保留 Synapse 的設定、簽署金鑰和本機媒體。 Synapse 官方備份指南(2026 年 10 月 10 日更新)特別警告不要覆蓋現有表,也不要恢復舊的端對端加密一次性金鑰。

資料庫備份包含哪些內容,不包含哪些內容。

已驗證: pg_dump在 PostgreSQL 保持在線的情況下創建一致的快照;轉儲運行時無需停止 Synapse。僅資料庫轉儲不包含 Synapse 媒體儲存中的檔案、homeserver.yaml引用的設定檔或伺服器簽署金鑰。請將這些檔案保存在單獨的受保護備份集中。 Synapse 會將本機上傳的內容以及(在停用動態縮圖時)本機縮圖識別為需要保留的資料。遠端媒體和 URL 預覽快取通常可以取得或重建。

操作:在製定復原計畫之前,請確定活動資料庫名稱、PostgreSQL 角色、Synapse 設定目錄、簽章金鑰路徑和媒體儲存路徑。請使用伺服器上配置的路徑;這些路徑會因軟體包、容器和部署方式而異。

常見誤解: SQL 轉儲成功並不代表整個家庭伺服器都能恢復。應對措施:備份資料庫、配置、簽署金鑰和所需的本地介質,並定期測試它們是否能一起復原。

建立並檢查自訂格式轉儲

以下命令假設主機為 Linux,已安裝 PostgreSQL 命令列工具,資料庫名稱為 `<database_name>` synapse,並且擁有以作業系統帳戶執行 PostgreSQL 命令的權限postgres。請將資料庫名稱和路徑替換為您實際部署中的值。將轉儲檔案儲存在具有足夠可用空間的受保護儲存裝置上;其中可能包含私人訊息和帳戶資料。

  1. 建立轉儲文件,但排除 Synapse 認為不能從舊備份重播的表格的內容:

    sudo -u postgres pg_dump -Fc --exclude-table-data=e2e_one_time_keys_json synapse > /secure-backups/synapse.dump

    -Fc選擇 PostgreSQL 的自訂歸檔格式,這種格式更適合pg_restore且通常比純 SQL 更小。此排除操作會影響表數據,但不會刪除表定義。

  2. 檢查檔案是否存在且不為空,然後列出已存檔的目錄:

    ls -lh /secure-backups/synapse.dump
    sudo -u postgres pg_restore --list /secure-backups/synapse.dump

    清單顯示 PostgreSQL 可以讀取歸檔結構,但並不能證明每一行資料都能恢復,也不能證明其他備份檔案完整。為了更嚴格地驗證,請將轉儲檔案複製到單獨的備份儲存位置,並在傳輸後驗證其校驗和。

常見誤解:每次進行快照都需要停止 Synapse 服務pg_dump。 Synapse 官方頁面指出,常規pg_dump快照無需停止 Synapse 或 PostgreSQL 服務即可保持資料一致性。建議:在進行邏輯備份時保持 Synapse 服務在線,但需安排維護視窗以進行完整還原。

恢復到空資料庫

恢復操作屬於替換操作。首先停止 Synapse 及其所有工作進程,以確保在復原過程中沒有任何程式連接到目標資料庫或向目標資料庫寫入資料。在執行資料庫變更指令之前,請確認目標資料庫名稱和轉儲檔案。

  1. 建立一個使用 UTF-8 編碼且擁有者與 Synapse 配置一致的新資料庫。以下範例使用範例角色synapse_user:

    sudo -u postgres createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse

    如果資料庫名稱已存在,請勿盲目地將其還原到該資料庫中。請先確認舊資料庫的內容,並確保擁有單獨的可恢復備份,然後再依照復原流程保留或刪除舊資料庫。

  2. 將歸檔檔案載入到空資料庫中:

    sudo -u postgres pg_restore --dbname=synapse /secure-backups/synapse.dump

    檢查指令的退出狀態和 PostgreSQL 輸出。在啟動 Synapse 之前,請先排查錯誤。避免使用諸如--clean直接恢復已填充資料的生產資料庫之類的快捷方式;Synapse 會警告說,預先存在的表可能會導致錯誤或不易察覺的不一致。

  3. 如果轉儲檔案未排除一次性密鑰數據,請在啟動前清除這些數據。連接到已復原的資料庫並執行以下命令:

    sudo -u postgres psql --dbname=synapse -c 'TRUNCATE e2e_one_time_keys_json;'

    Synapse 記錄了此例外情況,因為恢復舊的一次性金鑰可能會導致用戶端重複使用已使用的金鑰,從而導致訊息解密問題。清除這些金鑰會提示用戶端上傳新金鑰。如果您遵循了建議的排除規則,則表中沒有已復原的行,因此無需進行此額外的截斷操作。

常見誤解:所有資料庫表都可以安全地一起回滾。正確做法:e2e_one_time_keys_json在備份過程中排除某些表,或在復原後截斷這些表,並且必須在任何 Synapse 程序啟動之前執行此操作。

將家庭伺服器恢復並進行驗證。

盡可能從相同復原點恢復符合的設定、簽署金鑰和所需的本機媒體檔案。保留原始簽署金鑰:Synapse 使用它來簽署事件和聯合請求。如果必須更換,請遵循 Synapse 的簽署金鑰指南,並將舊公鑰配置為舊簽署金鑰。從不同時間點復原的資料庫、媒體和配置可能會描述不同的狀態,因此請檢查復原計畫的一致性。

僅在復原和一次性金鑰處理完成後才啟動 Synapse 及其工作進程。檢查服務日誌,尋找資料庫連線故障、缺少的架構或權限錯誤以及後台更新問題。然後使用測試帳戶登錄,檢查已知房間的近期歷史記錄,並開啟本地上傳的附件。如果您的部署依賴聯合身份驗證和應用程式服務,請檢查這些服務。這些檢查是實際的冒煙測試,並不能保證所有房間或媒體對像都已恢復。

具體情況取決於您的部署:命令路徑、服務名稱、資料庫角色、容器編排和備份保留策略均與安裝相關。本流程涵蓋 PostgreSQL 的邏輯轉儲和恢復,但不涉及時間點恢復、PostgreSQL 叢集範圍的角色或高可用性故障轉移設計。對於生產系統,請查閱Synapse 備份文檔和PostgreSQL 備份與恢復文檔,以找到與您的 PostgreSQL 版本和恢復目標相符的方法。記錄復原測試的日期、軟體版本和結果;切勿假設未經測試的歸檔檔案是可復原的備份。

留下評論

使用 PostgreSQL 轉儲安全地還原 Matrix Synapse

使用 pg_dump 備份 Synapse,保護其簽章金鑰和介質,並將其還原到乾淨的 PostgreSQL 資料庫中,而無需重複使用過時的一次性金鑰。

使用 Docker 將 Mjölnir 運行為 Matrix Room 管理機器人

使用 Docker 將 Mjölnir 運行為 Matrix Room 管理機器人

使用專用 Matrix 帳戶、加密管理室、Docker Compose、政策清單和權限檢查來設定 Mjölnir。

啟用原生矩陣滑動同步,加快行動端載入速度

啟用原生矩陣滑動同步,加快行動端載入速度

跳過已停用的代理,配置 Synapse 內建的滑動同步功能。檢查客戶端發現情況,然後在相容的手機上測量房間清單載入和重新連接行為。

Host Element Web 運行在 Nginx 上,並附有自訂 Homeserver。

將 Element Web 部署為靜態站點,將其指向您的 Matrix 主伺服器,新增 HTTPS,並配置 Nginx 以提供更新而不會出現過時的檔案。

在樹莓派 4 上執行輕量級矩陣家庭伺服器

在 64 位元 Raspberry Pi 4 上設定 Conduit,使其具有持久性資料、HTTPS 聯合身份驗證、受保護的註冊以及對正常工作的家庭伺服器的檢查。

在您自己的網域上設定自訂矩陣房間別名

使用 Element 或 Matrix API,在您的網域上為 Matrix 房間分配一個易於共享的地址,並檢查權限、Synapse 命名和聯合。

設定可靠的矩陣語音和視訊通話的 coturn

使用匹配的 TURN 憑證配置 coturn 和 Synapse,打開所需的中繼端口,並驗證 Matrix 用戶端是否可以取得中繼候選位址。

使用 Docker Compose 和 PostgreSQL 部署 Matrix Synapse

使用 Docker Compose 和 PostgreSQL 部署 Matrix Synapse

使用 Docker Compose、PostgreSQL、私人配置和檢查來設定持久的 Synapse 主伺服器,然後再透過 HTTPS 公開它。

自訂 Element Web 的主題和品牌

為您的 Element Web 部署設定品牌名稱、自訂色彩和登入資源,同時了解哪些部分仍保留 Element 品牌。

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

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

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