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

若要為 Matrix 房間指派位址(例如 `<room_alias_name>`)#support:example.com,請在設定伺服器名稱為 `<homeserver_name>` 的主伺服器上建立一個本機房間別名example.com,然後在 Element 中選擇該別名為房間的主位址。您無需為每個房間別名單獨建立 DNS 記錄,但不能僅透過 DNS 指向現有主伺服器來變更其別名網域。

了解自訂網域控制的內容

房間別名是一個可讀地址,它解析為 Matrix 房間的永久房間 ID,通常以 `<room_id>` 開頭!。一個房間可以有多個別名,例如 `<room_id>`#support:example.com和#help:example.com`<room_id>`,它們都指向同一個房間。冒號後面的文字標識負責解析該別名的 homeserver,而不是託管所有參與者的伺服器。

Matrix 將別名定義為 `<your_name>` #localpart:server-name。對於 Synapse 而言,此server_name設定決定了本地建立的房間地址所使用的域名,Synapse 文件指出,此設定在初始設定後無法變更。如果您的現有伺服器名為 `<your_name>` ,即使您擁有 `<your_name> matrix.example.com`,Element 也不會將其本機別名變更為 `<your_name>` 。請參閱Matrix 識別碼規格和Synapse 設定手冊。#support:example.comexample.com

查看先決條件

  • 一個可正常運作的 Matrix 主伺服器:此範例假設 Synapse 已在https://matrix.example.com設定server_name完成後開始處理用戶端 API 要求example.com。客戶端 URL 和伺服器名稱可能有所不同。
  • 現有房間:如有必要,請先建立房間。確定一個簡短易記的別名 localpart,例如support。別名在創建它的伺服器上必須是唯一的。
  • 管理位址權限:使用有權建立本機別名並變更房間主地址的帳戶登入。伺服器的別名建立策略和房間的權限等級可能會限制這些操作。
  • 測試方法:保留第二個 Matrix 帳戶,最好在另一個主伺服器上,這樣您就可以獨立於管理員會話檢查發現情況。

在 Element Web 中建立別名

以下路徑與 2026 年 10 月檢查的Element 房間設置文件中的房間設置術語相符。選單位置在不同的 Element 版本和其他 Matrix 用戶端之間可能有所不同。

1. 開啟房間設置

在 Element Web 或 Element Desktop 中,開啟目標會議室。從「會議室資訊」面板中選擇「會議室設定」,或使用會議室的三點選單並選擇「設定」。如果您稍後需要內部會議室 ID 以進行故障排除,請查看「進階」部分並複製它,不要更改任何字元。

2. 新增本地地址

在「常規設定」頁面,找到「房間地址」,然後找到「本地地址」support 。在「房間地址」欄位中輸​​入別名 localpart,例如` <your_homeserver_name>`,然後選擇「新增」或對應的儲存按鈕。確認產生的完整位址為 ` <your_homeserver_name> #support:example.com`。如果位址以 `<your_homeserver_name>` 結尾:matrix.example.com,則停止操作:這是 homeserver 名稱的問題,而不是房間設定可以修正的拼字錯誤。

3. 選擇主地址

仍在「房間地址」下,找到「已發佈地址」 ,並將「主地址」設為#support:example.com「」。 Element 的文檔指出,通常情況下,第一個建立的本機位址會被自動選為主位址。如果房間已經有多個別名,則明確選擇主地址會很有用。

主地址是房間的規範別名:即在房間狀態中發布的首選地址。建立別名和選擇規範別名是相關但不同的操作。 Matrix 也支援其他已發佈的別名。規範別名在發布之前必須已解析到該房間。

4. 確定房間是否應列入名錄

只有當您確實需要目錄被發現時,才啟用「將此房間發佈到公共房間目錄」選項。設定地址本身並不會將房間公開,發布房間與其加入規則是相互獨立的。私人房間或僅限邀請的房間可以擁有易於記憶的別名,而無需授予所有人加入權限。對於公共社區房間,在廣泛分享地址之前,請同時檢查目錄設定和房間的加入規則。

如果用戶端無法新增位址,請使用 Matrix API。

管理員和自動化工具可以使用標準的Matrix 用戶端-伺服器 API。以下範例建立相同的別名;如果 Element 已創建,請勿#support:example.com執行此範例。請將範例替換為真實的房間 ID 和有效的存取令牌,該令牌應為主伺服器別名策略允許的使用者。請將此令牌視為密碼。

curl --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data '{"room_id":"!yourRoomId:example.com"}' \
  'https://matrix.example.com/_matrix/client/v3/directory/room/%23support%3Aexample.com'

成功的請求會傳回200一個包含空 JSON 物件的 HTTP 回應。 `<your-name>`%23和 ` <your-location>`%3A部分是 `<your-location> #` 和 `<your-location>`的 URL 編碼:。 PUT 請求會建立一個別名到房間的對應;它不一定會更改房間的規範別名。在僅透過 API 建立房間後,如果您希望將該別名作為主要地址發布,請傳回 Element 的主位址控制項。請勿將真實的 bearer token 貼到共享的 shell 命令、螢幕截圖或支援工單中。

檢查映射是否解析

目錄查找無需登入。請將 URL 主機替換為您自己的可存取用戶端 API 端點:

curl --fail-with-body --silent --show-error \
  'https://matrix.example.com/_matrix/client/v3/directory/room/%23support%3Aexample.com'

回應應包含與room_id目標房間相符的字串和一個servers陣列。此測試用於驗證別名解析,而非確認每個遠端伺服器是否都能與您的伺服器建立聯盟。

解決常見故障

別名網域錯誤

請驗證 Synapse 的設定server_name。切勿在已建立的伺服器上變更此值以嘗試重新命名其別名:伺服器的身分和現有的 Matrix 識別碼都依賴此值。對於新部署,請在建立使用者和房間之前規劃所需的伺服器名稱。如果您已使用其他名稱,則使用其實際別名網域可能會更安全,除非您可以安排一個名稱合適的 homeserver 來擁有新的別名。

建立失敗,傳回 403 或 409 錯誤

HTTP403通常表示權限被拒絕或存在適用的伺服器原則。請檢查使用者的房間權限和 Synapse 的規則alias_creation_rules;規則會依序評估,如果清單為空,則會封鎖所有別名的建立。 HTTP409表示別名已存在。請選擇其他本地部分或檢查現有映射,而不是盲目覆蓋它。 Synapse 設定手冊中記錄了別名原則選項。

其他伺服器上的用戶找不到房間

首先檢查別名是否能在本地解析。如果本地查找成功但外部發現失敗,請檢查別名網域的聯盟,包括 HTTPS 憑證、相關/.well-known/matrix/server委派以及公開的聯盟監聽器。用於用戶端流量的主機名稱不會自動為不同的 Matrix 伺服器名稱建立聯盟。 Matrix伺服器-伺服器 API 文件描述了伺服器發現和委派。此外,也要確認是否允許遠端使用者加入;僅限邀請的房間可能解析成功,但會拒絕任何加入要求。

核實自訂房間地址

  1. 檢查「本機位址」#support:example.com下是否顯示該位址,以及該位址是否為 Element 中的預期主位址。
  2. 執行上述未經身份驗證的目錄 GET 請求,並將其與 Element高級房間設定room_id中顯示的 ID進行比較。
  3. 使用另一個帳號嘗試開啟連結https://matrix.to/#/%23support%3Aexample.com。連結應該會跳到預期的房間;帳號能否加入仍取決於房間的訪問規則。

Matrix 的房間別名和 matrix.to 格式參考定義了編碼後的共享連結格式。如果所有三個檢查都通過,則新地址即可共享,而原始房間 ID 保持不變。

留下評論

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

使用 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,並驗證即時限制。

元素顯示“解密失敗”?恢復遺失的房間鑰匙

元素顯示“解密失敗”?恢復遺失的房間鑰匙

確定錯誤是否僅限於一個瀏覽器或一個事件,然後使用 Element 的恢復金鑰或受信任的設備,而不會危及您剩餘的加密歷史記錄。

清理舊的 Synapse 訊息和媒體檔案而不遺失數據

使用 Synapse 的歷史記錄和媒體清除 API 或保留設定安全地刪除過期數據,然後驗證完成情況和磁碟空間恢復情況。

使用 Simple-Matrix-Bot-Lib 在 Python 中建立矩陣迴聲機器人

使用 Simple-Matrix-Bot-Lib 在 Python 中建立矩陣迴聲機器人

安裝目前庫,連接專用 Matrix 帳戶,並運行一個小型 !echo 機器人,該機器人具有更安全的憑證處理和清晰的測試。

使用獨立橋接器將 Matrix 連接到 WhatsApp、Telegram 和 Discord

使用獨立橋接器將 Matrix 連接到 WhatsApp、Telegram 和 Discord

設定三個 Mautrix 橋接器,分別進行註冊、登入和測試-避免 Docker 網路、帳號原則和同步方面的意外情況。

無需破壞共用檔案即可回收 Synapse 媒體磁碟空間

尋找 Synapse 儲存空間佔用情況,設定安全媒體保留策略,並在不直接從磁碟刪除檔案的情況下清除遠端快取。