如何使用 Docker Compose 安裝 Synapse Matrix 伺服器

舉例說明：假設有一個小型志工團隊想要在某個位址部署自己的 Matrix 伺服器chat.example.com。這只是一個假設的設置，並非實際測試過的伺服器報告。同樣的步驟可以應用到實際的域名，但務必謹慎選擇 Matrix 伺服器名稱：Synapse 會將其用於使用者 ID，並且之後無法更改。

本指南使用 Docker Compose 建立 Synapse 服務和 PostgreSQL 資料庫。 Synapse 的官方 Docker 映像預設使用 SQLite，方便進行臨時試用；Synapse 的 Docker 文件建議在生產環境中使用 PostgreSQL。因此，本範例首先產生 Synapse 的配置，將其資料庫設定變更為 PostgreSQL，然後啟動這兩個容器。官方鏡像為 [此處應填寫鏡像名稱] ghcr.io/element-hq/synapse。說明和鏡像詳情已於 2026 年 10 月 6 日根據最新的官方文件進行核對；鏡像標籤和支援的軟體版本可能會發生變化，因此在進行長期部署之前，請務必查看相關文件。

安裝前需要準備什麼

一台安裝了 Docker Engine 和 Docker Compose 外掛程式的 Linux 伺服器或其他支援 Docker 的主機。確認 Compose 可用docker compose version。請依照 Docker 官方針對您作業系統提供的安裝說明進行操作。
指向伺服器的網域名稱或子網域。在本例中，` chat.example.com<synapse-server-name>` 是 Synapse 伺服器名稱，因此本機使用者 ID 將類似於 `<synapse-server-name>` @alex:chat.example.com。在產生配置之前，請將其替換為您控制的網域。
用於公共用途的反向代理或其他 TLS 終止方法。 Synapse 預設的 HTTP 監聽器（連接埠號碼為 8）8008並非針對 Internet 的 HTTPS 端點。此 Compose 範例將該連接埠綁定到主機的回環接口，以便同一台機器上的反向代理可以存取它。

名稱SYNAPSE_SERVER_NAME並非一定是每個用戶端連線的 URL。如果您希望使用較短的 ID（例如，@alex:example.com在為來自特定網域的用戶端提供服務時）chat.example.com，則需要進行特定的網域名稱和發現設定。請在建立帳戶之前確定此配置。

1. 建立工作目錄和資料庫密碼

在伺服器上，建立目錄用於存放 Compose 專案和 Synapse 持久化檔案：

mkdir -p ~/matrix-synapse/data
cd ~/matrix-synapse

建立一個.envDocker Compose 可以讀取的本機檔案。使用密碼管理器或本機安全性產生器產生一個長隨機密碼，並將其放在 `<your-password>` 標籤之後POSTGRES_PASSWORD=。為了避免後續 YAML 轉義問題，本範例中請使用字母和數字。請勿將此文件提交至公共倉庫，並限制其權限：

umask 077
nano .env

該文件應僅包含一行，例如“ POSTGRES_PASSWORD=replace-with-a-long-random-value”。此文字僅為佔位符，並非可重複使用的密碼。請保留此密碼，以便在步驟 3 中設定 Synapse 資料庫時使用。

2. 定義 Synapse 和 PostgreSQL 服務

compose.yaml在專案目錄中建立：

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SYNAPSE_SERVER_NAME: chat.example.com
      SYNAPSE_REPORT_STATS: "no"
    volumes:
      - ./data:/data
    ports:
      - "127.0.0.1:8008:8008"

volumes:
  postgres_data:

請替換chat.example.com為您最終選擇的伺服器名稱。 PostgreSQL 健康檢查允許 Compose 等待資料庫報告就緒後再啟動 Synapse。命名資料庫磁碟區和主機掛載./data目錄在容器替換後仍然存在；單獨刪除容器不會刪除它們。docker compose down -v除非您有意要刪除資料庫卷，否則請避免執行此操作。

此範例旨在:latest簡化首次拉取操作。對於維護良好的伺服器，請選擇並記錄特定的 Synapse 版本標籤或鏡像摘要，然後在查看版本說明後，透過規劃升級流程進行更新。請勿假設可變latest標籤會保持相同的版本。

3. 產生 Synapse 的設定並將其指向 PostgreSQL

運行一次官方鏡像，使其進入配置生成模式。由於 Compose 掛載./data在`/ /dataetc/config/config/config`，產生的設定和簽署金鑰將保留在主機上：

docker compose run --rm synapse generate

此命令使用 Compose 環境中的伺服器名稱和匿名統計資料選項。 Synapse 也會建立一個簽署金鑰；請將其儲存在資料目錄中，並將其包含在受保護的備份中。請勿在常規容器更新期間重新產生或丟棄此金鑰。

打開data/homeserver.yaml並替換生成的database:部分，使用以下設定。請使用實際密碼取代.env佔位符：

database:
  name: psycopg2
  args:
    user: synapse
    password: 'replace-with-the-same-random-value'
    dbname: synapse
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10

保持 YAML 周圍的縮進，並確保只有一個活動database:部分。主機名稱postgres是 Compose 服務名稱，容器可以在其共享的預設網路上解析該名稱。配置使用 Synapse 文件中記錄的 PostgreSQL 引擎名稱，psycopg2以及資料庫參數名稱，包括dbname。

在這個簡單的範例中，資料庫密碼同時出現在 Synapse 設定和受保護的.env檔案中。請將這兩個文件都視為機密信息，限制主機訪問權限，如果您的部署環境需要，請使用專門的機密信息管理方法。切勿將真實密碼貼到日誌、螢幕截圖或支援請求中。

4. 使用 Docker Compose 啟動 Synapse

在後台啟動堆疊：

docker compose up -d

檢查服務狀態並讀取啟動日誌：

docker compose ps
docker compose logs --tail=100 synapse

請等待 Synapse 完成首次啟動資料庫設定。容器運行僅表示其進程處於活動狀態；在繼續操作之前，請檢查日誌是否存在配置、資料庫或權限錯誤。若要即時查看日誌，請使用docker compose logs -f synapse並按下Ctrl+C停止按鈕，即可在不停止容器的情況下停止查看日誌。

5. 驗證本機 API 並配置公共訪問

從 Docker 主機請求 Synapse 用戶端 API 版本端點：

curl -fsS http://127.0.0.1:8008/_matrix/client/versions

成功的回應是描述支援的 Matrix 用戶端 API 版本的 JSON 資料。這確認 HTTP 監聽器正在本地回應；但並不能證明 DNS、HTTPS 或聯盟配置正確。

設定主機反向代理，將對所選網域的請求轉送至指定位址http://127.0.0.1:8008並取得有效的 TLS 憑證。代理程式時保留 Matrix 請求路徑。然後檢查公共端點：

curl -fsS https://chat.example.com/_matrix/client/versions

請將範例主機名稱替換為您的實際主機名稱。如果用戶端需要從單獨的使用者 ID 網域發現主伺服器，請為該設計發佈對應的 Matrix 已知資訊發現記錄。聯盟還需要正確的公共路由和 DNS 配置；8008僅開放本地端連接埠並不能實現完整的公共部署。在公開服務之前，請先查閱 Synapse 的反向代理和聯盟指南。

6. 建立第一個管理員帳戶

Synapse 預設禁用公共註冊。對於私有伺服器，請保持此預設設置，並透過命令列建立帳戶。暫時在設定檔registration_shared_secret中新增一個強值data/homeserver.yaml，然後重新啟動 Synapse 使其讀取變更：

docker compose restart synapse

在容器內執行註冊工具。它會提示輸入使用者名稱和密碼；設定完成--admin後將建立第一個管理員：

docker compose exec synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  --admin

帳戶建立完成後，請將其registration_shared_secret從配置中移除並重新啟動 Synapse。保留密鑰配置後，任何獲取該密鑰的人都可以透過註冊介面註冊標準帳戶或管理員帳戶。使用支援自訂主伺服器的 Matrix 用戶端，並輸入反向代理提供的伺服器 URL 進行登入。

備份、升級和常見修復

備份正確的資料：停止或定期對 PostgreSQL 資料進行快照並備份./data，包括配置、媒體和簽署金鑰。compose.yaml僅備份一份 PostgreSQL 資料無法還原主伺服器。將備份儲存在與伺服器不同的位置，並定期確認您可以讀取這些備份。
Synapse 無法寫入/data：請檢查主機擁有權和權限./data。官方鏡像的運行時用戶需要讀取配置和寫入資料的權限。請謹慎調整主機所有權，而不是將目錄設定為全域可寫入。
資料庫連線失敗：請檢查資料庫配置是否正確host: postgres，密碼是否匹配.env，以及docker compose logs postgres資料庫狀態是否正常。 Compose 的depends_on就緒狀態可以減少啟動競爭，但不會修復錯誤的憑證。
本機 API 運作正常，但用戶端無法連線：請檢查您所選網域配置的 DNS 記錄、TLS 憑證、反向代理上游設定以及發現記錄。僅使用環回埠對映是針對相同主機代理程式的有意設計；位於其他容器中的代理程式需要共用的 Docker 網路和不同的路由設計。
升級：docker compose pull先備份，檢視 Synapse 發行說明，更新固定鏡像標籤，然後重新建立服務docker compose up -d。保持相同的資料目錄、資料庫磁碟區、伺服器名稱和簽章金鑰。