如何備份與還原 Matrix Synapse PostgreSQL 資料庫

可靠的 Synapse 復原始於一個可讀取的 PostgreSQL 轉儲檔案、一個乾淨的目標資料庫以及匹配的 homeserver 檔案。對於典型的單一資料庫安裝，Synapse 官方備份指南建議使用 PostgreSQL 的自訂轉儲格式，並排除 /etc/synapse.conf 檔案的內容e2e_one_time_keys_json。將資料還原到新建的空資料庫中；不要將轉儲檔案覆寫先前安裝遺留的資料表。然後確認 Synapse 可以從復原的資料庫啟動，且本機媒體和簽署金鑰都已存在。

本演練假設主機為 Linux，PostgreSQL 資料庫名稱為 `<database_name>` synapse，資料庫角色名稱為 `<database_role>` synapse_user。請根據您的部署環境取代資料庫、角色、備份路徑、服務名稱和配置路徑。 Docker Compose、Kubernetes、託管 PostgreSQL 和多資料庫 Synapse 部署需要針對其環境執行對應的命令。

資料庫轉儲能夠保護什麼，又不能保護什麼，這些內容將受到哪些保護，以及它們將無法保護哪些內容 ...

pg_dump它會將一個 PostgreSQL 資料庫捕獲到一致的快照中，因此 PostgreSQL 和 Synapse 可以在轉儲運行時保持在線。-Fc可以使用 `synapse.txt` 指令檢查和還原自訂格式的歸檔pg_restore檔案。 Synapse 指南特別建議排除一次性金鑰表資料：復原舊的已使用金鑰可能會導致用戶端再次收到金鑰，從而導致訊息解密錯誤。表定義仍然可能出現在歸檔文件中；檢查歸檔清單時，請尋找表資料條目，而不是假設列出的表包含行。

僅備份資料庫並不完整。還應保留資料庫homeserver.yaml及其引用的所有檔案、伺服器簽署金鑰和媒體儲存目錄。 Synapse 的備份指南指出，本地上傳的媒體非常重要，因為家庭伺服器可能只會保存一份備份。如果您的設定使用了多個資料庫條目，請為 Synapse 使用的每個資料庫都建立備份。

開始之前

確認已配置的資料庫名稱、使用者、主機、端口，以及 Synapse 使用的是單一資料庫還是多個資料庫。
檢查 PostgreSQL 用戶端實用程式pg_dump、、pg_restore和createdb是否psql已安裝並與您的 PostgreSQL 伺服器相容。
選擇一個有足夠可用空間的受保護備份目標位置。備份檔案可能包含私人訊息和帳戶資料；限制存取權限，並對靜態和傳輸中的備份進行加密。
記錄 Synapse 設定目錄、簽章金鑰路徑等資訊media_store_path。備份金鑰，但不要將其暴露在 shell 歷史記錄、聊天記錄或日誌中。
確定恢復測試方法。在隔離主機或測試資料庫上進行復原測試比單獨執行成功的轉儲命令更有說服力。

建立並檢查 PostgreSQL 備份

1. 確認目標資料庫和角色

在自行管理的 PostgreSQL 主機上，以 PostgreSQL 管理員身分連接並檢查資料庫清單和關係。不要依賴從範例配置中複製的假定名稱。如果您的主伺服器使用遠端或託管資料庫，請使用其認可的連線方式，並驗證轉儲帳戶是否具有所需的讀取權限。

PostgreSQL 終端機列出了 Synapse 資料庫關係和 synapse_user 擁有者。 — 透過終端查看 Synapse 關係及其所有者，有助於確認備份命令將以目標資料庫為目標。

2. 產生自訂格式的轉儲文件

建立一個只有備份帳戶或管理員才能讀取的目錄。以下範例pg_dump以本機 PostgreSQL 作業系統帳戶身分執行，並寫入受保護的路徑。請將路徑變更為在您的環境中存在且可寫入的路徑。

sudo -u postgres pg_dump -Fc \
  --exclude-table-data e2e_one_time_keys_json \
  synapse -f /var/backups/synapse/synapse.dump

如果您的資料庫是遠端的，請使用您環境中允許的方式提供連接設置，例如透過受保護的.pgpass檔案或 libpq 環境變數。避免直接在命令列中輸入密碼。除非您有明確且有據可查的理由需要對一次性密鑰表進行特殊處理，否則請保留排除選項。

終端以自訂格式執行 pg_dump，排除 e2e_one_time_keys_json 數據，然後列出檔案。 — 備份指令會排除一次性金鑰數據，並寫入自訂格式的歸檔文件，以便稍後使用 pg_restore 進行檢查。

3. 檢查存檔並儲存校驗和

確認轉儲檔案存在、大小不為零且可以作為 PostgreSQL 歸檔檔案讀取。成功列出文件是一個有用的初步檢查，但這並不能證明恢復操作會完成，也不能證明整個主伺服器可以服務所有使用者。

sudo -u postgres pg_restore --list /var/backups/synapse/synapse.dump
sha256sum /var/backups/synapse/synapse.dump

將校驗和儲存在備份記錄旁邊，然後將備份檔案複製到單獨的系統或備份服務。複製後重新計算校驗和並比較結果。對於生產環境復原目標，應定期安排備份，保留多個備份版本，對其進行加密，並定期執行復原演練。

還原到乾淨的資料庫

4. 停止 Synapse 並準備一個空的目標位置

要進行恢復，請先停止 Synapse 服務，以防止在資料庫替換或測試期間它重新連接。以下服務名稱在某些軟體包安裝中很常見，但具體名稱可能有所不同；Docker 使用者應透過其 Compose 專案停止 Synapse 服務，而編排部門應使用其常規維護流程。 PostgreSQL 本身無需停止。

Linux 終端機顯示 Synapse 服務在資料庫復原之前已停止。 — 在將 Synapse 應用程式的資料庫切換到復原副本之前，請先停止該應用程式；使用主機上配置的服務名稱。

請使用全新的空資料庫進行復原。切勿覆寫現有的 Synapse 資料庫或已包含資料表的資料庫。如果需要保留目前資料庫以便回滾，請保持其完整，並使用臨時資料庫名稱進行恢復，然後在變更 Synapse 配置之前進行驗證。

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

資料庫擁有者和區域設定應符合 Synapse 設定的要求。如果目標名稱已存在，請停止操作並確認您打算使用的資料庫；不要想當然地認為刪除它是安全的。請先建立所有必要的 PostgreSQL 角色。單一資料庫pg_dump不包含叢集範圍的角色，因此遷移到新 PostgreSQL 叢集的管理員可能還需要使用 . 工具建立單獨受保護的全域備份pg_dumpall --globals-only。

終端機建立了一個空的 UTF8 PostgreSQL 資料庫，具有 C 語言環境、template0 和 synapse_user 所有權。 — 建立目標資料庫時，請使用 Synapse 所需的編碼、區域設定和擁有者，並將目標資料庫設為空。

5. 恢復存檔並處理一次性密鑰

將自訂歸檔檔案載入到該空目標位置。顯式錯誤選項會在遇到錯誤時停止還原過程，而不是繼續進行並留下容易被忽略的不完整結果。

sudo -u postgres pg_restore --exit-on-error \
  --dbname=synapse /var/backups/synapse/synapse.dump

如果您的備份檔案未排除該表e2e_one_time_keys_json，請連接到已還原的資料庫，並在啟動 Synapse 之前截斷該表。這是 Synapse 針對包含這些行的備份檔案所提供的復原保障措施。請勿隨意對運行中的資料庫執行此命令：它會刪除該表中的所有行。

PostgreSQL 終端機執行 pg_restore 將自訂格式的 Synapse 歸檔檔案載入到 Synapse 資料庫中。 — 只有在創建了一個全新的空目標資料庫之後才能恢復存檔，並且在繼續操作之前檢查任何錯誤輸出。

連接到 Synapse 的 psql 終端顯示 TRUNCATE e2e_one_time_keys_json。 — 僅當復原的轉儲包含一次性鍵行時才使用此方法；在清除表之前，Synapse 應保持停止狀態。

sudo -u postgres psql -d synapse \
  -c 'TRUNCATE e2e_one_time_keys_json;'

如果使用了建議的排除項，則復原作業不會包含舊的一次性鍵行，因此無需執行此截斷步驟。表條目pg_restore --list可以表示不包含資料的表定義。TABLE DATA查看歸檔內容時，請檢查是否存在此類條目；最安全的操作記錄是所使用的確切轉儲命令。

恢復 Synapse 並驗證恢復情況

6. 恢復配套檔案並啟動 Synapse

重新啟動前，請確保復原的配置指向目標資料庫，且 Synapse 進程可以存取所需的簽署金鑰和媒體儲存。如果您使用臨時資料庫名稱進行恢復，請安全地更新資料庫設置，驗證文件，然後使用常規部署流程啟動它。在新的實例通過檢查之前，請保留舊資料庫和先前的配置。

使用適合您部署環境的命令啟動服務。在 systemd 主機上，檢查服務狀態和最近的日誌。在容器中，檢查容器的運作狀況和日誌。進程正在運行只是一個初始訊號，並不代表使用者可以閱讀聊天室、發送訊息或檢索附件。

終端機正在查看 PostgreSQL 歸檔列表，並顯示 Synapse 啟動和服務狀態命令。 — 恢復後，檢查歸檔日誌和服務日誌，然後驗證實際客戶端操作，然後宣布恢復完成。

7. 測試使用者所依賴的功能

確認 Synapse 啟動時沒有資料庫遷移、權限、區域設定或連線錯誤。
使用測試帳號登入並閱讀現有房間；如果您的維護計劃允許，請發送測試訊息。
檢查聯合身份驗證和應用程式服務行為，看看這些功能是否包含在您的部署中。
開啟一個已知的本機上傳附件或頭像，測試媒體庫是否與復原的資料庫相符。
檢查 Synapse 日誌和 PostgreSQL 日誌，查看啟動後是否有重複錯誤，而不僅僅是第一次成功的健康檢查。

即使缺少媒體檔案、引用的配置或角色，恢復操作在技術上也可能成功。如果使用者發現附件缺失，請驗證已設定的媒體儲存空間並還原對應的本機媒體備份。如果 Synapse 無法連接，請比較已復原的資料庫擁有者、憑證、主機、資料庫名稱、區域設定和活動設定檔。

常見故障訊號及何時改變方法

訊號	接下來要檢查什麼
`pg_restore`報告現有關係或所有權錯誤	確認目標資料庫為空且所需角色存在。恢復到全新資料庫；不要將`--clean`其用作快捷方式，因為您需要保留現有資料庫的內容。
dump 指令傳回非零值或產生不可讀文件	檢查客戶端/伺服器相容性、權限、磁碟空間、目標權限以及 PostgreSQL 日誌。產生一個新的轉儲文件，並在使用前進行驗證。
Synapse 啟動了，但舊的一次性金鑰仍然包含在內。	在允許 Synapse 為用戶端提供服務之前，請先停止 Synapse 並依照文件中記錄的截斷程序進行操作。
房間功能正常，但本地附件缺失	恢復匹配的本地媒體儲存和配置；PostgreSQL 轉儲不包含已上傳的媒體檔案。
復原時間或資料庫大小超出可接受範圍。	根據您的復原點和復原時間目標，評估 PostgreSQL 的其他備份方法，例如基本備份和使用 WAL 歸檔的時間點復原。

對於許多中小型部署來說，邏輯轉儲便攜且操作簡便，但隨著資料庫規模的成長，復原速度可能會變慢。對於大型或高可用性服務，請參考 PostgreSQL 的最新備份文檔，並制定經過測試的實體備份或時間點復原方案。如果邏輯轉儲有其他便攜性或審計需求，則應將其單獨保留。除非單獨備份，否則這兩種方法都無法保護儲存在 PostgreSQL 外部的檔案。