在您自己的網域上設定自訂矩陣房間別名
使用 Element 或 Matrix API,在您的網域上為 Matrix 房間分配一個易於共享的地址,並檢查權限、Synapse 命名和聯合。
將 Synapse 作為 Docker Compose 專案運行,並配置持久化配置目錄和 PostgreSQL 資料庫。以下設定會產生 Synapse 的簽章金鑰homeserver.yaml,將其連接到 PostgreSQL,並將 HTTP 監聽器保留在本機上,以便您可以在將伺服器開放給網際網路之前,將 HTTPS 和聯合驗證放在反向代理程式之後。
Synapse 是 Matrix 的主伺服器:它儲存伺服器的帳戶、房間、事件和媒體。 Docker Compose 透過一個 YAML 檔案運行 Synapse 和 PostgreSQL 容器。這只是一個單機啟動方案,並非完整的公共 Matrix 部署。
安裝 Docker Engine 和 Docker Compose 插件,然後確認docker compose version運作正常。 Docker Desktop 在 Windows 和 macOS 系統上已內建 Compose;Linux 使用者可以從 Docker 的軟體包倉庫安裝 Compose 外掛程式。請參閱Docker 的 Compose 安裝說明。
在產生設定之前,請選擇永久的 Matrix 伺服器名稱。該名稱會出現在使用者 ID 中,例如@alex:matrix.example.org`<user_id>`,之後變更它並非常規的主機名稱編輯。在本例中,matrix.example.org`<server_id>` 既是 Matrix 伺服器名稱,也是公用主機名稱。對於公用伺服器,請將其 DNS 記錄指向您的主機,並規劃一個 HTTPS 反向代理。 Synapse 在 8008 連接埠產生的 HTTP 監聽器適用於本機測試;其安裝文件指出,實際使用需要 HTTPS。
在 Docker 主機上,建立工作目錄和持久化資料夾。工作synapse目錄將存放產生的配置和簽署金鑰;持久化資料夾data/postgres將存放資料庫檔案。
mkdir -p ~/matrix-synapse/synapse ~/matrix-synapse/data/postgres
cd ~/matrix-synapse
umask 077
openssl rand -hex 32
將指令的輸出複製到一個.env名為 `.composep.php` 的新檔案中DB_PASSWORD=...。請將此文件設為私密文件,並進行安全備份。 Compose 會讀取.envCompose 檔案中的替換項目;Synapse 不會自動展開這些變數homeserver.yaml。您將在步驟 3 中在該設定中輸入相同的密碼。

在專案目錄中建立docker-compose.yml。本範例使用 Element HQ 發布的官方 Synapse 映像和 PostgreSQL 16。 Synapse 連接埠綁定到環回接口,而不是每個網路介面。健康檢查有助於 Compose 在啟動 Synapse 之前等待 PostgreSQL 完成。
services:
synapse:
image: ghcr.io/element-hq/synapse:latest
restart: unless-stopped
environment:
SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
volumes:
- ./synapse:/data
ports:
- "127.0.0.1:8008:8008"
depends_on:
db:
condition: service_healthy
db:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_USER: synapse
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: synapse
POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C
volumes:
- ./data/postgres:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
interval: 10s
timeout: 5s
retries: 5
DB_PASSWORD=your-generated-value使用步驟 1 中產生的隨機值進行輸入。.env請勿將此文件提交至原始碼控制系統。如果之後更改 PostgreSQL 的主版本號,請遵循 PostgreSQL 的升級流程,而不是簡單地將新版本鏡像指向現有資料目錄。
在掛載目錄中產生初始配置和簽署金鑰synapse。使用與上面選擇的伺服器名稱相同的名稱。明確設定統計資訊選項;如下所示no。
docker compose run --rm --no-deps \
-e SYNAPSE_SERVER_NAME=matrix.example.org \
-e SYNAPSE_REPORT_STATS=no \
synapse generate
官方容器generate模式會建立homeserver.yaml所需的簽章金鑰。開啟synapse/homeserver.yaml並取代其 SQLite 資料庫部分,替換為以下內容。將替換PASTE_THE_SAME_DB_PASSWORD_HERE為儲存在中的確切值.env。此欄位是 Synapse 配置的實際值,而非 Compose 插值。
database:
name: psycopg2
args:
user: synapse
password: PASTE_THE_SAME_DB_PASSWORD_HERE
dbname: synapse
host: db
port: 5432
cp_min: 5
cp_max: 10

請將產生的註冊表單registration_shared_secret保密。 Synapse 會將其用於命令列使用者註冊工具;任何取得該註冊表單的人都可以建立帳戶,包括管理員。除非您有意提供公開註冊功能並已審查相關的濫用控制措施,否則請保持停用狀態。
從包含該檔案的目錄中docker-compose.yml,驗證 Compose 檔案並啟動服務:
docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100 synapse db
第一條指令檢查 Compose 是否可以解析檔案並解決問題DB_PASSWORD。下一條命令在後台啟動資料庫和主伺服器。檢查日誌,查看是否有資料庫連線錯誤或設定檔缺失。由於此設定使用綁定掛載方式掛載本機資料夾,因此即使容器重新創建,資料庫和 Synapse 配置也會保留。

從 Docker 主機執行 Matrix 用戶端版本請求。如果收到 JSON 回應,表示用戶端 API 正在回應;如果收到空回應、連線被拒絕或 HTTP 錯誤,則應檢查 Synapse 日誌並確認連接埠 8008 是否正在監聽。
curl -fsS http://127.0.0.1:8008/_matrix/client/versions
系統回應後,以互動方式建立初始使用者。此命令會提示輸入使用者名稱和密碼;除非您確實需要管理員帳戶,否則請選擇「否」以停用管理員帳戶。
docker compose exec synapse register_new_matrix_user \
-c /data/homeserver.yaml http://localhost:8008

僅限本地主機的連接埠對映是故意的:它防止直接向公共伺服器存取未加密的 HTTP 監聽器。對於遠端用戶端,請設定具有有效 TLS 憑證的反向代理,並將 Matrix 路徑轉送至 Synapse。代理程式必須傳遞 `<host>`X-Forwarded-For和 ` X-Forwarded-Proto<host>` 標頭;在產生的監聽器設定中,x_forwarded: true為連接埠 8008 啟用 `<host>`。請勿將容器化的 Synapse 監聽器設定為僅綁定到 `<host>` 127.0.0.1,因為這會阻止代理容器存取它。如果反向代理也是容器化的,請將其與 Synapse 放在共用的 Docker 網路中,並將代理程式指向服務名稱 `<service name>` synapse:8008。
聯盟部署獨立於本地啟動。其他 Matrix 伺服器需要發現並連接到您的伺服器,通常透過 8448 連接埠或委託的 HTTPS 發現機制。 DNS、反向代理路由以及任何必要的.well-known記錄必須與所選伺服器名稱相符。在發佈公用主伺服器之前,請遵循 Synapse 的反向代理文件和安裝指南。語音和視訊通話也需要 TURN 伺服器以確保可靠的媒體連線。
如果 Synapse 無法連線到 PostgreSQL,請驗證Compose 服務名稱host是否正確,兩個密碼是否完全匹配,以及資料庫容器是否運作正常。如果無法存取端點,請檢查Synapse 日誌,並確認是否有其他服務正在使用主機連接埠 8008。備份 PostgreSQL 資料目錄以及 Synapse 設定和簽署金鑰;簽名金鑰對於伺服器的身份至關重要。dbdocker compose ps
有關 PostgreSQL 配置的詳細信息,請參閱Synapse 的 PostgreSQL 指南。有關容器選項和使用者創建,請使用Synapse 官方 Docker 文件。
使用 Element 或 Matrix API,在您的網域上為 Matrix 房間分配一個易於共享的地址,並檢查權限、Synapse 命名和聯合。
使用匹配的 TURN 憑證配置 coturn 和 Synapse,打開所需的中繼端口,並驗證 Matrix 用戶端是否可以取得中繼候選位址。
使用 Docker Compose、PostgreSQL、私人配置和檢查來設定持久的 Synapse 主伺服器,然後再透過 HTTPS 公開它。
為您的 Element Web 部署設定品牌名稱、自訂色彩和登入資源,同時了解哪些部分仍保留 Element 品牌。
診斷 Synapse 是否達到其每個程序開啟檔案上限,為正確的服務或工作進程設定 systemd drop-in,並驗證即時限制。
確定錯誤是否僅限於一個瀏覽器或一個事件,然後使用 Element 的恢復金鑰或受信任的設備,而不會危及您剩餘的加密歷史記錄。
使用 Synapse 的歷史記錄和媒體清除 API 或保留設定安全地刪除過期數據,然後驗證完成情況和磁碟空間恢復情況。
安裝目前庫,連接專用 Matrix 帳戶,並運行一個小型 !echo 機器人,該機器人具有更安全的憑證處理和清晰的測試。
設定三個 Mautrix 橋接器,分別進行註冊、登入和測試-避免 Docker 網路、帳號原則和同步方面的意外情況。
尋找 Synapse 儲存空間佔用情況,設定安全媒體保留策略,並在不直接從磁碟刪除檔案的情況下清除遠端快取。