如何在樹莓派 4 上使用 Conduit 設定 Matrix 伺服器

樹莓派 4 可以建造一個實用的小型 Matrix 伺服器，適用於家庭、私人團體或實驗室，而 Conduit 的設計也充分考慮了輕量化硬體的需求。 Matrix 是一種用於去中心化通訊的開放協定：使用者連接到伺服器，伺服器儲存他們的帳戶和房間數據，而聯盟機制則允許該伺服器與其他 Matrix 伺服器交換事件。

本指南使用 Docker 中的 Conduit，並在其前端部署 NGINX 以實現 HTTPS 連線。這樣可以確保 Matrix 服務在樹莓派上隔離運行，同時僅暴露公共 Web 連接埠。本指南的說明已根據 2026 年 10 月發布的 Conduit、Matrix、樹莓派、Docker 和 NGINX 文件進行核對。首先需要注意一個重要的限制：Conduit 目前仍處於beta測試階段，因此最適合那些能夠接受某些 Matrix 功能和舊版房間可能無法像在成熟的 Synapse 部署中那樣完美運行的用戶。在 Conduit 將用於關鍵服務之前，請務必查看官方的 Conduit 專案文件。

桌面上的樹莓派4單板計算機 — 如果搭配可靠的儲存、電源和網絡，樹莓派 4 可以運行一個小型 Conduit Matrix 家庭伺服器。

1. 安裝任何設備之前，請務必了解安裝設定。

最終路徑很簡單：Matrix 用戶端（例如 Element）連接到伺服器https://matrix.example.com；NGINX 終止 TLS 連線並將請求轉發到樹莓派上的 Conduit；Conduit 將其資料庫儲存在持久化的 Docker 儲存中。如果啟用了聯盟，其他家庭伺服器也可以存取同一個公共 HTTPS 端點。

您需要一台樹莓派 4、一個可靠的電源、一張 microSD 卡或固態硬碟 (SSD) 以及一個 64 位元作業系統。如果您打算長期使用伺服器，建議使用 SSD，因為 Matrix 會持續寫入資料庫和媒體資料。如果伺服器需要從公共互聯網訪問，您還需要一個網域名稱。

截至 2026 年 9 月 15 日，目前 64 位元版本的 Raspberry Pi OS 是基於 Debian 13 “Trixie”，而 Raspberry Pi OS Lite 則適用於 Pi 4。請造訪Raspberry Pi OS 官方下載頁面。對於這台伺服器而言，Lite 版本非常合適，因為它避免了不必要的桌面環境。

請仔細選擇 Matrix 伺服器名稱

在本指南中，伺服器名稱matrix.example.com為 `< @alice:matrix.example.comserver name=" ...

2. 安裝 Raspberry Pi 作業系統並更新 Pi

使用 Raspberry Pi Imager 將 Raspberry Pi OS Lite 64 位元系統映像寫入記憶卡或固態硬碟，如果需要無頭安裝，請在鏡像過程中啟用 SSH，然後啟動樹莓派。確認您的系統是 64 位元 ARM 系統：

uname -m
cat /etc/os-release

uname -m應該會正常報告aarch64。然後安裝最新更新：

sudo apt update
sudo apt full-upgrade -y
sudo reboot

樹莓派終端機顯示 apt update、apt upgrade 和 reboot 指令 — 在安裝 Docker 和 Conduit 之前，請更新 Raspberry Pi 作業系統，以便伺服器能夠從目前的系統軟體包啟動。

3. 安裝 Docker Engine 和 Compose

Docker 的文檔指出，64 位元 Raspberry Pi OS 使用者應該使用受支援的 Debian ARM64 軟體包，而不是舊的 32 位元 Raspberry Pi OS 軟體包。權威的步驟請參閱Docker Engine for Debian 頁面。以下倉庫設定遵循此方法：

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg   -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io   docker-buildx-plugin docker-compose-plugin

sudo docker run --rm hello-world

如果最後一條指令輸出 Docker 的 hello-world 確認訊息，則表示容器執行時正在執行。您可以繼續sudo docker按照本指南的其餘部分進行操作。將您的帳戶新增至該docker群組是可選的，但請記住，Docker 群組成員資格實際上授予了主機的 root 權限。

4. 建立導管配置

Conduit 可以透過 TOML 檔案或環境變數進行設定。官方的Conduit 配置參考文件server_name將 `<your-name>` 、database_backend`<your-name>` 和`<your-name>`列為必填database_path字段，並推薦使用 RocksDB。

建立工作目錄：

sudo mkdir -p /opt/conduit
sudo chown "$USER":"$USER" /opt/conduit
cd /opt/conduit
nano conduit.toml

使用此初始配置，並取代主機名稱和註冊令牌：

[global]
server_name = "matrix.example.com"
database_backend = "rocksdb"
database_path = "/var/lib/matrix-conduit/"
address = "0.0.0.0"
port = 6167

allow_registration = true
registration_token = "replace-with-a-long-random-secret"
allow_federation = true
trusted_servers = ["matrix.org"]

為什麼選擇0.0.0.0這裡？在容器內部，Conduit 必須監聽容器接口，以便 Docker 可以存取它。主機端的連接埠仍然只綁定到主機127.0.0.1，因此連接埠 6167 不會直接暴露在網際網路上。

Nano 編輯器顯示 Conduit 伺服器名稱、RocksDB 路徑、連接埠、註冊資訊和聯盟設置 — 最小的 Conduit 配置定義了 Matrix 伺服器身分、RocksDB 儲存、本機服務連接埠以及註冊和聯合行為。

5. 使用 Docker Compose 運行 Conduit

創造/opt/conduit/docker-compose.yml：

services:
  conduit:
    image: registry.gitlab.com/famedly/conduit/matrix-conduit:latest
    container_name: matrix-conduit
    restart: unless-stopped
    ports:
      - "127.0.0.1:6167:6167"
    volumes:
      - ./conduit.toml:/etc/conduit.toml:ro
      - conduit-data:/var/lib/matrix-conduit/
    environment:
      CONDUIT_CONFIG: /etc/conduit.toml

volumes:
  conduit-data:

官方 Conduit Docker 文件推薦使用穩定的 GitLab Registry 映像。請勿從其他教學課程複製舊鏡像標籤；請使用官方鏡像倉庫，並在升級前仔細閱讀版本說明。

編輯器顯示了 Conduit Matrix 伺服器的 Docker Compose 服務 — Docker Compose 將 Conduit 容器定義、持久性儲存和網路配置保存在一個可重現的檔案中。

啟動服務並進行檢查：

cd /opt/conduit
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=100 conduit

您希望容器保持Up運作狀態，避免反覆重新啟動。在配置 NGINX 之前，請先驗證本機 API：

curl http://127.0.0.1:6167/_matrix/client/versions

終端機顯示 `docker compose up` 和 `docker compose ps` 指令的輸出，而 Conduit 容器正在運作。 — 正在運行的 Conduit 容器應該保持運行狀態，並且只將其內部連接埠發佈到 Raspberry Pi 回環介面。

6. 將 DNS 指向樹莓派，並在 Conduit 前端部署 NGINX。

建立一條指向您的公網 IPv4 位址的A記錄matrix.example.com。如果您發布了AAAA記錄，請確保 IPv6 流量能夠到達樹莓派；即使 IPv4 流量正常，損壞的 IPv6 記錄也可能導致用戶端連線失敗。

在普通的家用路由器上，將 TCP 連接埠 80 和 443 轉送到樹莓派。如果您的 ISP 使用電信商級 NAT (CGNAT)，則普通的入站連接埠轉送可能無法運作；在這種情況下，您需要一個公用位址、VPS/反向隧道方案或其他託管方案。

安裝 NGINX：

sudo apt install -y nginx

創造/etc/nginx/sites-available/matrix：

server {
    listen 80;
    server_name matrix.example.com;

    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:6167;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

NGINX官方反向代理指南文件proxy_pass以及此處使用的轉送標頭。

sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/matrix
sudo nginx -t
sudo systemctl reload nginx

NGINX 配置顯示了 HTTPS 代理和 Matrix 已知端點 — NGINX 是面向公眾的層：它終止 HTTPS 請求並將 Matrix 請求轉送到 Conduit。 Matrix 的常用端點可以代理到 Conduit，也可以明確地提供服務。

7. 啟用 HTTPS 和 Matrix 發現

Matrix 要求正常的公共部署使用有效的 HTTPS。只有在 DNS 解析到樹莓派且 80 連接埠可存取後，才能取得憑證。 Debian Trixie 提供了 Certbot 軟體包，同時 Certbot 專案也在certbot.eff.org上發布了最新的平台特定說明。

Debian/NGINX 的常見路由方式是：

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d matrix.example.com

Certbot 更新 NGINX 虛擬主機後，請再次測試設定：

sudo nginx -t
sudo systemctl reload nginx

/.well-known由於本指南對 Matrix 伺服器名稱和公用端點使用了相同的主機名，Conduit 可以透過反向代理程式回應 Matrix發現路徑。 Matrix 規格定義了這些端點，以便用戶端和其他伺服器能夠發現正確的 homeserver URL。請參閱Matrix 用戶端-伺服器規格。

8. 建立第一個帳戶，然後驗證伺服器

Conduit 的 Docker 文件指出，在新 homeserver 上建立的第一個帳戶將成為管理員帳戶。開啟支援註冊令牌的 Matrix 用戶端，選擇自訂 homeserver，然後輸入：

https://matrix.example.com

使用提供的令牌註冊第一個帳戶conduit.toml。請在服務上線後儘快執行此操作。如果您不希望進行後續註冊，請編輯配置allow_registration = false並重新啟動容器：

cd /opt/conduit
sudo docker compose restart conduit

包含建立帳戶、登入或變更伺服器選項的登入頁面元素 — 在 Element 等 Matrix 用戶端中，註冊或登入前，請選擇自訂 homeserver URL 而不是預設的公共伺服器。

現在，從任何可以存取該網域的機器上執行以下三個檢查：

curl https://matrix.example.com/_matrix/client/versions

curl https://matrix.example.com/.well-known/matrix/client

curl https://matrix.example.com/.well-known/matrix/server

第一個請求應傳回描述受支援的 Matrix 用戶端 API 版本的 JSON 資料。常用請求應傳回有效的 JSON 發現資訊。對於聯盟，也請使用Matrix 聯盟測試器，並嘗試使用新帳號加入聯盟房間。

終端機顯示 curl 檢查 Matrix 用戶端版本以及常用的用戶端和伺服器發現端點。 — 來自 Matrix 版本和知名 URL 的成功 JSON 回應是 HTTPS 路由和發現的有用最終檢查。

導致樹莓派 Matrix 伺服器無法正常運作的常見錯誤

沒有必要使用 32 位元作業系統：對於 Pi 4，請使用 Raspberry Pi OS 64 位元和 Docker 支援的 Debian ARM64 軟體包。
直接暴露 Conduit：將連接埠 6167 綁定到127.0.0.1主機，並透過 NGINX 暴露 HTTPS。
註冊功能未加保護：在初始設定期間使用強註冊令牌，如果不需要註冊功能，則停用註冊。
發佈錯誤的 DNS：如果同時發佈 IPv4 和 IPv6 記錄，則兩者都必須指向一個可用的端點。
忘記路由器或防火牆規則：正確的容器無法彌補被封鎖的入站 TCP 80/443。
假設訊息傳遞和語音通話功能相同： Matrix 訊息功能可以正常運作，但通話功能可能會失敗。 Conduit 的文檔指出，語音通訊需要 TURN 伺服器，例如 Coturn。
跳過備份： Conduit 的常見問題解答建議，除非使用合適的檔案系統快照，否則在對資料庫進行常規檔案系統複製之前，應先停止 Conduit 服務。升級前，請備份 Docker 捲和您的配置。

成功安裝的樣子是什麼樣的？

當以下所有條件都滿足時，測試就完成了：Conduit 容器在重新啟動後仍然運行；https://matrix.example.com/_matrix/client/versions返回 JSON；Matrix 用戶端可以註冊或登入您的自訂 homeserver；帳戶可以建立房間並傳送訊息；並且，如果啟用了聯合，則聯合測試人員可以存取伺服器，使用者可以與另一個 homeserver 上的帳戶通訊。

對於小型樹莓派部署而言，這只是一個乾淨的基線，而非管理工作的終點。請監控可用儲存空間，確保樹莓派作業系統和 Docker 修補程式及時更新，備份資料庫，並在啟用額外功能前閱讀Conduit 官方文件。 Conduit 仍然是樹莓派級硬體的輕量級且極具吸引力的選擇，但其測試版狀態是一個不容忽視的實際操作考慮因素。