如何在您的網域上配置自訂矩陣房間別名

Matrix 房間別名賦予房間一個易於理解的地址，例如 `<room_alias_name> #support:example.org`。冒號後面的部分是主伺服器的伺服器名稱，即擁有別名命名空間的網域名稱。它並非可以透過新增 DNS 記錄來變更的任意網域標籤。要使用您自己的域名，必須將該域名配置為主伺服器的伺服器名稱；然後可以將聯合身份驗證委託給單獨的主機。

本指南使用 ` example.org<domain>` 作為域名，matrix.example.org`<Synapse host>` 作為 Synapse 主機，` #support:example.org<target alias>` 作為目標別名。請將這些佔位符替換為您自己的值。本指南主要針對自架 Synapse。如果您使用託管的 Matrix 供應商，請檢查是否允許您使用自訂伺服器名稱；許多託管帳戶只能在提供者的網域下建立別名。

矩陣房間別名的作用

主伺服器是 Matrix 伺服器，用於儲存使用者的房間資料並連接到其他伺服器。房間 ID（例如 `< room ID>`）!opaqueid:example.org用於技術上標識房間。房間別名（例如 `< room #support:example.orgalias>`）是一個可讀的目錄條目，它解析為房間 ID 以及可以幫助使用者加入房間的伺服器清單。

別名不會重新命名房間、更改其隱私設置，也不會保證房間出現在公共房間目錄中。這些是單獨的房間設置。一個房間可以有多個別名。規範別名是用戶端顯示或共享的首選位址；它會作為房間狀態發布，而主伺服器則維護別名到房間的對應關係。 Matrix 規範提醒，別名對應關係可能會發生變化，因此在使用位址之前請務必先進行解析。

開始之前

控制您想要使用的域名，例如example.org，包括在該域名上提供 HTTPS 內容的能力。
運行 Synapse 等家庭伺服器，並將其矩陣server_name設為example.org。此值在伺服器設定時選擇，以後不應隨意變更：使用者 ID 和別名將其用作命名空間。
必須擁有有效的 TLS 憑證和聯合路由。受委託的 Matrix 主機（例如matrix.example.org）必須提供有效的憑證。
加入房間並擁有更改房間地址所需的權限。 Synapse 還具有伺服器端規則，可以允許或拒絕建立別名。

如果伺服器已經以不同的伺服器名稱執行，例如provider.net，則建立#support:example.org別名並非網域名稱對應的捷徑。請諮詢服務提供者是否支援自訂域名，或計劃單獨部署和遷移主伺服器。 Matrix 沒有定義允許一個主伺服器在另一個伺服器的命名空間中建立別名的流程。

步驟 1：選擇伺服器名稱和聯合路由

在設定主伺服器之前，請確定冒號後顯示的名稱。在本例中，Synapse 使用 `<your_server_name>`example.org作為其伺服器名稱，而其用戶端和聯合服務運行在 ` <your_client_name> matrix.example.org`。 DNS 記錄會將 `<your_server_name>` 的流量傳送matrix.example.org到主機或反向代理。 DNS 記錄本身並不能建立別名命名空間；Synapse 的伺服器名稱才能建立別名命名空間。

當無法透過example.org預設的聯盟連接埠 8448 直接存取主伺服器時，Matrix 需要一種方法來發現其聯盟端點。常用的方法是使用`.well-known` 委託：在伺服器名稱網域發送簡短的 HTTPS JSON 回應，將聯盟流量指向實際的 Matrix 主機。此回應應發送至https://example.org/.well-known/matrix/server：

{
  "m.server": "matrix.example.org:443"
}

請確保回應為有效的 JSON 格式，並透過 HTTPS 提供服務，並且目標主機擁有有效的證書，並將聯合請求路由到 Synapse。如果聯合端點使用 8448 端口，則可以省略端口號；在本例中，端口號 443 是明確指定的。如果 Synapse 已經在伺服器名稱網域的 8448 連接埠上提供聯合服務，則可能不需要進行委派。客戶端/.well-known/matrix/client檔案是一種不同的發現機制，不能取代伺服器委派。

Synapse 目前的設定文件包含一個serve_server_wellknown選項，用於將對伺服器名稱網域的 443 連接埠請求路由到 Synapse。僅當您的代理程式和網域路由符合文件中的要求時才使用此選項。否則，請在您的 Web 伺服器或代理程式上設定 JSON 回應。

步驟 2：檢查 Synapse 的別名策略

Synapse 可以限制誰可以建立別名以及允許使用哪些房間地址。在配置中homeserver.yaml，檢查alias_creation_rules別名建立請求是否被拒絕。 Synapse 會依序評估已設定的規則；第一個符合的規則決定請求是否被批准，如果沒有符合的規則，則拒絕該要求。空列表會拒絕所有別名建立請求。如果清單為空或省略，則預設允許建立別名，但需進行其他檢查。

另請檢查require_membership_for_aliases，預設情況下要求使用者必須在房間內。如果您變更了 Synapse 配置，請遵循部署的正常驗證和重新啟動流程，並避免過度放寬策略。房間的功率等級和用戶端的可用控制功能也會影響一般會員是否可以設定首選別名。

步驟 3：為房間建立別名

在 Matrix 用戶端中加入目標房間，並開啟房間設定。找到位址或別名欄；客戶端的措詞和佈局可能因版本而異。輸入完整地址，包括開頭的域名#和主伺服器域名，例如 `<your-role-name> #support:example.org`。將其新增為房間地址，如果用戶端提供此選項，則將其設定為規範別名或首選別名。儲存更改。

如果您的用戶端未提供別名控制，則可以透過用戶端-伺服器 API 請求建立對應。經過驗證的PUT /_matrix/client/v3/directory/room/{roomAlias}端點需要在請求正文中包含房間 ID。例如，已授權的房間成員或伺服器帳戶可以向擁有以下房間的 homeserver 發送請求example.org：

curl -X PUT \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org" \
  -H "Authorization: Bearer $MATRIX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"room_id":"!yourRoomId:example.org"}'

請將範例房間 ID 替換為實際房間的 ID，並使用具有必要授權的有效存取令牌。請像對待密碼一樣對待此令牌：切勿發布、貼上到支援貼文或將其提交到原始碼控制系統。 URL 編碼#和:HTTP 路徑中的百分號 (%) 會進行轉義。成功響應表示映射已建立。「已存在」回應表示該名稱已被佔用；在更改或刪除任何內容之前，請確認其所有者。

第四步：核實地址並分享

使用公共客戶端-伺服器 API 解析別名。此查找不需要身份驗證：

curl -i \
  "https://matrix.example.org/_matrix/client/v3/directory/room/%23support%3Aexample.org"

成功的回應應包含預期的房間 IDroom_id和servers清單。將傳回的房間 ID 與目標房間進行比較。 404 表示該別名在處理該命名空間的伺服器上沒有對應。 400 表示位址格式無效。然後，在第二個 Matrix 帳戶或用戶端中測試完整的別名，以確認房間可以解析並能夠根據其加入規則加入。

如果您設定了規範別名，請再次檢查房間詳情，並確認首選地址是您打算發布的地址。只有在確認別名或 Matrix 永久連結指向正確的房間後，才能分享該連結。請記住，公開別名不會將私有房間公開；使用者仍然需要獲得權限才能加入。

需要避免的常見問題

使用主伺服器不擁有的網域名稱：別名中的伺服器名稱必須與建立它的主伺服器命名空間相符。僅憑 DNS CNAME 記錄無法授權其他伺服器的網域名稱。
混淆網域名稱和主機：網域 example.org可以是別名命名空間，而matrix.example.org主機是服務主機。請有意設定 Synapse 伺服器名稱和委派。
客戶端發現文件放置位置錯誤：聯合委託使用/.well-known/matrix/server客戶端發現文件，其路徑和用途與聯合委託不同。
假設別名公開發布房間：別名解析和公開房間目錄發布是受不同策略約束的獨立操作。
在已部署環境中變更伺服器名稱：現有的 Matrix ID 依賴於該命名空間。請將網域變更視為架構遷移，而不是簡單的別名設定。
分享時未檢查映射關係：發布前請解析別名並比較傳回的房間 ID。雖然位址易於理解，但伺服器的映射關係決定了位址指向哪裡。