如何在自架的 Matrix 伺服器上限制使用者註冊

在自架的 Matrix 伺服器上，「限制註冊」可以指從完全禁止公開註冊到僅允許擁有邀請碼的使用者註冊等各種情況。對於 Synapse 來說，最簡單的選擇是停用公開註冊。如果您仍然希望新用戶加入，可以要求用戶使用註冊令牌，並為每位用戶分配一個有效期有限的令牌。這些控制措施會影響本機新帳戶的建立；它們不會刪除現有使用者或停用 Matrix 聯盟。

選擇適合您伺服器的控件

以下範例適用於 Synapse。 Dendrite、Conduit 和其他 HomeServer 實作使用不同的設定和管理介面。在套用 Synapse 設定之前，請先查閱伺服器本身的文件。

方案一：關閉公開註冊

對於私人家庭伺服器、小型組織或管理員配置每個帳戶的伺服器，請在目前 Synapse 設定中停用用戶端註冊：

enable_registration: false

Synapse 文件顯示此設定預設為停用狀態。請編輯您的服務或容器實際載入的設定文件，驗證 YAML 文件，然後使用常規的服務管理流程重新啟動 Synapse。 Docker 部署可能會從主機路徑掛載配置，因此在容器內編輯同名檔案可能不會變更啟動時使用的檔案。

關閉註冊功能後，使用者無法透過常規用戶端註冊流程建立新帳戶。管理員仍然可以透過受支援的管理方式建立帳戶。 Synapse 特別警告，registration_shared_secret即使此設定enable_registration設為 false，仍允許使用該金鑰建立帳戶。請將其視為高風險憑證：切勿將其儲存在程式碼庫、聊天記錄和公共環境轉儲檔案中；限制存取權限；並且僅在管理工作流程需要時才保留。任何擁有此金鑰的人都可以建立帳戶，包括管理員帳戶。

如果您使用 OIDC、CAS 或其他 SSO 集成，也請檢查該提供者的自動註冊設定。 Synapse 會記錄提供者層級的註冊設置，因為否則使用者可能會在首次成功 SSO 登入後自動建立。對於 OIDC，請oidc_providers[].enable_registration同時查看其常規註冊設定。

方案二：僅允許使用令牌註冊

當成員需要能夠建立自己的帳戶，但註冊請求需要由管理員批准或分發時，請使用註冊令牌。在 Synapse 配置中，設定以下兩個值：

enable_registration: true
registration_requires_token: true

兩者都需要：令牌設定需要在註冊時提供令牌，同時註冊功能也必須啟用。應用變更並重新啟動 Synapse。更改此設定不會刪除現有帳戶和先前建立的令牌。

創建限時使用令牌

Synapse 提供了一個註冊令牌管理 API。請求需要管理員存取令牌。例如，下列請求會建立一個可以完成一次註冊的令牌：

curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/registration_tokens/new" \
  -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"uses_allowed": 1}'

將環境變數替換為您的主伺服器基本 URL 和管理員存取權杖。請務必妥善保管管理員令牌，避免將包含真實憑證的命令貼到共享日誌或支援貼文中。 API 也接受以 Unix 紀元以來的毫秒數為單位的過期時間。對於單一邀請，請使用一次性令牌，並在您的工作流程能夠可靠地計算和維護過期時間時設定過期時間。省略限制的令牌可能具有無限次使用次數和永久過期時間，因此在分發令牌之前，請務必檢查返回的欄位。

若要檢查令牌，管理員可以呼叫對應的 API GET /_synapse/admin/v1/registration_tokens。回應內容包括允許的使用次數、待處理的註冊、已完成的註冊、過期時間。如果令牌洩露，請將其允許的使用次數更新為零，或透過文件中提供的管理員 API 將其刪除。令牌是註冊憑證，而非 Matrix 房間邀請；它不會自動將新帳戶加入房間。

重要相容性提示：啟用 Matrix Authentication Service (MAS) 整合後，Synapse 的註冊令牌管理 API 將會停用。在這種情況下，請改用部署文件中提供的 MAS 管理 API 或 MAS CLI。請勿假設 Synapse 令牌命令可以直接用於 MAS。

方案三：在公共登記中增加檢查環節

如果您希望任何人都能申請帳戶，那麼要求提供令牌可能過於嚴格。 Synapse 的設定文件中也提到了驗證碼 (CAPTCHA) 和第三方識別碼 (3PID) 作為可能的驗證方式。驗證碼依賴於配置正確的服務提供者，並且可能會增加可訪問性和隱私方面的成本。要求提供電子郵件地址或電話號碼會增加設定和驗證的依賴；這與批准每個帳戶並不相同。在將 3PID 要求作為門檻之前，請確認您的版本和用戶端流程實際支援哪些驗證服務。

速率限制與這些控制措施配合使用非常有用，因為它能減少重複請求，但它並不能決定哪些使用者可以註冊。請監控註冊嘗試和伺服器日誌，並根據您的流量和部署情況調整限制。切勿在未檢查已安裝的 Synapse 版本的情況下複製舊的設定片段：註冊和身分識別服務選項會隨時間而變更。

登記終止會改變什麼，又不會改變什麼

• 它控制著本地新帳戶的創建。停用註冊功能會阻止您主伺服器上的正常帳戶建立流程。
• 它不會刪除帳戶。現有用戶將保留其帳戶，除非您單獨暫停或停用他們的帳戶。
• 它不會關閉聯盟。其他伺服器上的用戶仍然可以與本地用戶和房間通信，但需遵守房間成員資格和聯盟設置。
• 它不會將房間設置為僅限邀請。房間加入規則是單獨的設定；註冊令牌不能取代房間邀請。
• 它並非一定會阻止所有配置路徑。管理 API、已設定的共用金鑰、應用程式服務和 SSO 帳戶建立設定需要單獨審查。

隱藏註冊 URL 的反向代理規則可以作為額外的網路層控製手段，但它很容易破壞客戶端流程，並且不會取代主伺服器本身的配置。建議使用應用層設定作為主要控製手段，並在每次代理更改後測試實際部署情況。

驗證結果

1. 檢查有效配置來源，包括任何容器綁定掛載或產生的配置，以確認其註冊值是否正確。
2. 重新啟動 Synapse 並查看啟動日誌，尋找 YAML 錯誤或不支援的設定。
3. 從未登入的 Matrix 用戶端嘗試發起新的註冊。如果註冊功能已停用，則註冊流程不應提供可用的公開註冊入口。如果啟用了需要令牌的註冊功能，則缺少有效令牌的請求不應完成。
4. 對於令牌註冊，請使用一次性臨時令牌進行測試，並確認該令牌僅用於建立單一帳戶。檢查管理員 API 回應中的令牌completed、pending令牌和過期資訊。
5. 測試單獨配置的 SSO 路徑和所有帳戶配置腳本。確認它們的行為符合您的存取策略。

除非您打算使用真實的邀請令牌，否則請勿將其用於測試帳戶。如果設定似乎無效，請先確認您已更改 Synapse 實際載入的文件，並且服務已重新啟動。然後檢查是否存在共用註冊金鑰、SSO 自動註冊或其他受信任的設定機制。

官方參考資料

• Synapse 1.160 設定手冊：註冊設置
• Synapse 註冊令牌管理 API
• Synapse 安裝指南：註冊用戶
• Synapse共享金鑰註冊API
• 矩陣客戶端-伺服器 API 規範

Synapse 的版本化設定和管理 API 文件是選項名稱和請求欄位的權威來源。以上說明並未預設特定的作業系統、容器映像、反向代理程式或 Matrix 用戶端；請在套用變更前確認這些部署相關的具體細節。