如何透過管理員 API 在 Matrix Synapse 中刪除不活躍使用者帳戶

在 Matrix Synapse 中，刪除不活躍帳號和停用帳號之間有重要差異。 Synapse 官方文件中的管理 API 並未提供通用的硬刪除端點，該端點會移除與使用者關聯的所有資料庫記錄。目前支援的管理工作流程是：識別帳戶、審核帳戶，然後呼叫停用端點。您可以選擇性地設定"erase": true移除個人資料資訊並將使用者標記為已刪除。

因此，理想的結果並非「使用者 ID 從所有 Synapse 表中消失」。理想的結果應該是：使用者無法再進行身份驗證，已啟動的令牌和裝置被移除，帳戶從房間中移除，第三方識別碼被移除，並且——如果您的策略要求——個人資料被刪除。已上傳的媒體檔案和歷史訊息屬於獨立事項，不會因帳號停用而自動刪除。

本指南使用截至 2026 年 10 月的最新 Synapse 管理 API 文件。請務必將範例與您伺服器上執行的 Synapse 版本的文件進行比較，尤其是在您執行長期部署或使用 Matrix 驗證服務時。權威參考文件包括Synapse 使用者管理 API 文件、Synapse 管理 API 概述和Synapse 媒體管理 API 文件。

你該追求什麼樣的結果？

在進行任何更改之前，請先定義清理策略。 「非活動」並非 Synapse 帳戶狀態；它是您根據last_seen_ts帳戶類型、管理狀態和業務上下文等欄位建立的規則。

如果您不確定某個帳戶是否已被棄用，請不要last_seen_ts僅以此作為判斷標準。服務帳戶、應用程式服務使用者、緊急管理員、機器人、支援帳戶以及透過單一登入 (SSO) 關聯的使用者可能具有異常的登入模式。可靠的清理流程應包含明確的排除清單和審核步驟。

步驟 1：列出本地用戶並收集活動數據

管理員 API 請求需要伺服器管理員的存取令牌，這與房間管理員的存取令牌不同。請盡可能將令牌放在 HTTPAuthorization: Bearer標頭中傳送，而不是放在 URL 或 shell 歷史記錄中。

Synapse 將 V3 使用者清單端點描述為：

GET /_synapse/admin/v3/users

一個基本的請求如下圖所示：

export SYNAPSE_URL="https://matrix.example.com"
export ADMIN_ACCESS_TOKEN="REDACTED"

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v3/users?limit=100"

使用者列表 API 支援分頁。當回應中包含 `<page>` 時next_token，請使用該值作為參數請求下一頁from。請勿假定第一頁代表伺服器的全部內容。

該 API 公開了一些用於清理決策的實用字段，包括帳戶是否為管理員、使用者類型、是否已停用、建立時間以及最後存取時間。文件將最後存取時間定義last_seen_ts為自 Unix 紀元以來使用者的最後活動時間戳記（以毫秒為單位）。

什麼才算「不活躍」？

常見的策略是“180天內不得進行任何活動”，但適當的期限取決於具體情況。小型私人伺服器可能90天即可。而大學、季節性組織或校友服務可能需要365天或更長。

使用絕對截止時間戳，而不是比較格式化日期。例如，可以使用 Python 作業以毫秒為單位計算閾值：

from datetime import datetime, timezone, timedelta

cutoff = datetime.now(timezone.utc) - timedelta(days=180)
cutoff_ms = int(cutoff.timestamp() * 1000)

只有當帳戶處於活動狀態、非管理帳戶、未受策略保護且帳戶建立時間last_seen_ts超過閾值時，才將使用者視為不活躍用戶。

對於缺失或為空的最後訪問時間值，應謹慎處理。這可能意味著該帳戶從未產生過您預期的活動數據，但不一定意味著可以安全地將其刪除。在刪除之前，請交叉檢查建立時間、帳戶類型、SSO 對應和業務所有權。

步驟 2：建立一個不活躍候選列表，而不是一個自動刪除列表

這一步驟的品質比 API 呼叫的速度更重要。你的目標應該是產生一個經過審核的候選帳戶列表，其中只包含可以安全停用的帳戶。

至少應排除：

• 家庭伺服器管理員；
• 已知的應用程式服務和整合帳戶；
• 故意處於休眠狀態的機器人和客服帳號；
• 緊急帳戶或緊急帳戶；
• 列入法定保留或留存例外清單的帳戶；
• 最近更改身分提供者或帳戶對應的使用者；
• 除非您正在審核先前的清理工作，否則已停用的使用者將無法使用。

一個簡單的候選記錄應包含 Matrix 使用者 ID、last_seen_ts建立時間戳記、管理員標記、帳戶類型以及其通過不活躍規則的原因。保留這些資訊可以大大簡化後續的審核和回溯決策。

你怎麼知道候選人篩選是否夠好？

注意以下三個跡象：

• 完整性：您的腳本已對整個本機使用者清單進行分頁。
• 可解釋性：每個候選人都有一個可見的原因，例如「上次出現是在 242 天前，非管理員，非服務帳戶」。
• 誤報風險低：特殊帳戶和業務例外情況在進行任何破壞性呼叫之前都會被過濾掉。

如果無法滿足這些檢查要求，請在繼續操作之前變更流程。例如，增加人工審核環節、發送不活躍警告，或先暫停帳戶而不是停用帳戶。

步驟三：停用帳戶前檢查每個帳戶

Synapse 文件針對特定本機使用者記錄如下：

GET /_synapse/admin/v2/users/<user_id>

例子：

USER_ID="@olduser:example.com"

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v2/users/$USER_ID"

回應內容可能包括帳戶的管理狀態、停用和刪除標記、建立時間戳記和最後存取時間戳記、外部身分以及第三方識別碼。此時需要驗證該帳戶是否為您想要操作的帳戶。

應該使用 erase true 還是 erase false？

當操作目標是在保留個人資料資訊的同時停用存取權限時，請使用此功能"erase": false。根據 Synapse 目前的文檔，正常的停用操作會移除活動存取權杖、密碼雜湊、裝置和端對端加密金鑰、推送程式、第三方 ID、房間成員身分、帳戶資料、待處理的邀請以及相關的帳戶有效性資訊。

"erase": true當您的策略也要求移除顯示名稱、頭像 URL、自訂個人資料欄位並將使用者標記為已刪除時，請使用此功能。刪除並不意味著所有歷史記錄都會被銷毀。 Synapse 已明確說明，此 API 不會刪除先前傳送的訊息，也不會自動刪除已上傳的媒體檔案。

這種區別至關重要。如果您的保單要求刪除的內容不僅限於刪除個人資料，僅停用帳戶是不夠的。

步驟 4：試運轉、停用並驗證

在執行變更之前，請將最終使用者 ID 寫入純文字或 JSON 檔案並進行審核。在變更期間，試運行應該保持不變：如果在停用使用者的過程中候選使用者產生腳本發生更改，請停止操作並重新產生已核准清單。

對於每個已核准的本機用戶，呼叫文件中記錄的停用端點：

POST /_synapse/admin/v1/deactivate/<user_id>

不刪除個人資料的範例：

curl -sS -X POST   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   -H "Content-Type: application/json"   --data '{"erase": false}'   "$SYNAPSE_URL/_synapse/admin/v1/deactivate/@olduser:example.com"

刪除個人資料範例：

curl -sS -X POST   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   -H "Content-Type: application/json"   --data '{"erase": true}'   "$SYNAPSE_URL/_synapse/admin/v1/deactivate/@olduser:example.com"

之後，再次查詢該帳戶：

curl -sS   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v2/users/@olduser:example.com"

成功的操作結果應該會顯示出來"deactivated": true。如果您要求了刪除操作，也請進行驗證"erased": true。不要僅以「API 返回 HTTP 2xx」作為成功標準；更改後請讀取使用者記錄。

停用操作究竟會移除哪些內容？

Synapse 目前的文件列出了停用帳戶的幾個影響。其中包括移除活動存取權杖、第三方識別碼、裝置、端對端加密金鑰、推播器、密碼雜湊值、房間成員身分、待處理的邀請以及帳戶資料。此外，也會從使用者目錄中刪除該使用者。

Synapse也會erase: true刪除顯示名稱、頭像 URL、自訂個人資料字段，並將帳戶標記為已刪除。

Synapse 也會記錄一些重要項目，這些項目不會被此操作刪除。其中包括已發送和已接收的訊息、已上傳的媒體檔案、SSO 映射、建立時間戳記、速率限制覆蓋、每月活躍用戶記錄以及部分用戶許可資訊。此清單並非詳盡無遺，因此請將停用視為帳戶關閉，而非徹底清除所有資料。

您還需要刪除用戶上傳的媒體檔案嗎？

如果您的保留策略要求刪除使用者上傳的本機儲存媒體，Synapse 提供了一個單獨的端點：

DELETE /_synapse/admin/v1/users/<user_id>/media

例子：

curl -sS -X DELETE   -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"   "$SYNAPSE_URL/_synapse/admin/v1/users/@olduser:example.com/media"

使用者媒體 API 會刪除 Synapse 媒體庫中儲存的本機媒體檔案和縮圖。文件中提到了兩個重要的操作限制。首先，儲存在外部媒體庫中的媒體檔案不受此 API 的影響。其次，如果您未設定限制，則每次請求會刪除 100 個文件，因此擁有大量媒體文件的使用者可能需要重複使用此 API。

除非您的保留策略另有規定，否則請勿自動刪除媒體檔案。自動刪除比停用帳戶更具破壞性，並且可能會影響歷史記錄中仍然引用的媒體檔案。

什麼情況下應該使用懸浮液？

Synapse 也提供了帳戶暫停 API 的文檔。暫停帳戶會阻止發送訊息、加入聊天室、發送邀請、更改個人資料資訊以及大多數編輯操作，同時保留與停用帳戶不同的恢復路徑。

當您需要可逆的管理限制、無法確定使用者是否處於不活躍狀態，或離職審核仍在進行中時，暫停帳戶是更合適的選擇。如果需要終止存取權限並刪除令牌、設備、會議室會員資格和帳戶數據，則停用帳戶是更可靠的選擇。

對於自動化清理而言，分階段策略通常更安全：

1. 帳戶達到不活躍閾值後將其標記為不活躍帳戶；
2. 通知或審查；
3. 如果所有權不確定，則暫停執行；
4. 僅在保留或批准期限過後才停用。

如何安全地實現自動化清理？

將發現和停用操作作為獨立的任務。發現任務應為唯讀任務，並產生候選文件。執行任務應僅使用已批准的文件，並記錄每個請求和回應狀態。

高品質的生產流程也應包括：

• 遵循所有分頁標記；
• 對批量請求進行速率限制，而不是同時發送數千個請求；
• 預設排除伺服器管理員和指定服務帳戶；
• 以UTC格式儲存時間戳記；
• 記錄選擇每個帳戶的清理策略版本；
• 出現身份驗證、授權或伺服器反覆出錯時停止；
• 停用用戶後重新查詢每個用戶；
• 將管理存取令牌排除在原始碼和日誌之外。

如果變更後驗證結果與要求狀態不符，請勿盲目地繼續處理剩餘批次。應調查首次失敗的案例，並確定問題出在權限、API 版本相容性、代理配置、矩陣身份驗證服務集成，還是特定於帳戶的條件。

最終檢查清單

• 使用伺服器管理員持有者令牌。
• 列出所有本機使用者頁面，而不僅僅是前 100 位使用者。
• 用明確的閾值和排除項來定義不活躍狀態。
• 在採取行動之前，請逐一檢查高風險帳戶。
• 產生並核准演練清單。
• 請使用停用端點，而不是假設 Synapse 支援完全硬刪除帳戶。
• erase: true僅當刪除使用者設定檔是策略的一部分時才選擇此項目。
• 必要時單獨處理上傳的媒體檔案。
• 每次更改後deactivated，如適用，請進行核實。erased

最可靠的清理方式是事後可以解釋清楚的：哪個不活動規則選擇了某個帳戶，檢查了哪些例外情況，執行了哪些 API 操作，以及哪個更改後字段證明了帳戶狀態符合預期。這種標準比簡單地追求單次運行處理的帳戶數量最大化更有用。