如何在 Nginx 上託管自訂元素 Web 用戶端

如果您可以開放您的 Matrix 伺服器，但不希望使用者依賴公共 Element 網站，您可以將 Element Web 作為靜態網站託管在您自己的 Nginx 伺服器上。文件由 Nginx 提供服務；Matrix 伺服器仍然是一個獨立的服務，負責處理帳戶、房間、訊息和聯盟。這種區別至關重要：將 Web 用戶端指向 Synapse 並不會安裝或設定 Synapse。

本入門教學使用 ` <Element>` 和 `<homeserver> chat.example.org` 作為 Element 網站和matrix.example.org家庭伺服器的名稱。請將兩者替換為您真實的伺服器主機名稱。命令假設伺服器運行的是 Debian 或 Ubuntu 等 Linux 發行版；軟體包路徑和服務名稱會因發行版而異。

開始之前你需要準備什麼

修改伺服器檔案前，請準備好以下物品：

Web 用戶端的網域或子域名，DNS 指向 Nginx 主機。
一個可透過 HTTPS URL 存取的 Matrix 主伺服器，例如https://matrix.example.org。
Nginx 已安裝，並已獲得編輯其網站配置和重新載入服務的權限。
有效的 Web 用戶端主機名稱的 TLS 憑證。使用者應透過 HTTPS 登錄，因為瀏覽器會將憑證和會話令牌傳送到網站。
這是 Element Web 官方專案提供的最新穩定版本存檔。除非您明確打算執行開發軟體，否則請避免將開發版本部署到公共服務。

Element Web 是一個由靜態檔案組成的瀏覽器應用程式。該專案目前的安裝說明建議下載發佈版本，將其解壓縮到伺服器上，將 Web 伺服器指向解壓縮後的文件，並進行設定config.json。在 Debian 和 Ubuntu 系統上，該專案還提供了一個 Element Web 軟體包，該軟體包會將 Web 根目錄安裝在 `/etc/ElementWeb/` 下/usr/share/element-web，並將設定檔安裝在 `/etc/ElementWeb/` 下/etc/element-web/config.json。以下步驟使用發布版本，因此您可以選擇專用的文檔根目錄。

在選擇版本之前，請先查看 Element Web 的安裝說明和官方版本資訊。如果您使用的是 Debian 軟體包，請將 Nginx 指向該軟體包文件中指定的 Web 根目錄，並編輯軟體包設定檔；請勿直接複製下列歸檔路徑。

1. 下載並安裝 Element Web 文件

文檔根目錄是 Nginx 在訪客開啟您的網站時提供的目錄。建立一個專用的根目錄並將發布版本解壓縮到該目錄中。請替換為您下載的實際壓縮包和目錄名稱；發布版本會隨時間而變化。

sudo install -d -o root -g www-data -m 0755 /var/www/element
tar -xzf element-vX.Y.Z.tar.gz
ls

壓縮包通常會解壓縮到一個有版本號碼的目錄中。將該目錄中的內容（包括index.htmlJavaScript 套件、字型、圖片和範例設定）複製到 Nginx 文件根目錄。例如，如果解壓縮後的目錄名為element-vX.Y.Z：

sudo cp -a element-vX.Y.Z/. /var/www/element/
sudo find /var/www/element -type d -exec chmod 755 {} \;
sudo find /var/www/element -type f -exec chmod 644 {} \;
ls -l /var/www/element/index.html /var/www/element/config.sample.json

在複製指令中使用實際的版本化目錄名稱。 Nginx 需要對這些檔案擁有讀取權限，而不是寫入權限。升級前請保留目前版本和配置的副本，以便在部署失敗時進行復原。

2. 設定客戶端以使用您的主伺服器

Element 需要主伺服器位址才能啟動。複製範例檔案並設定預設的 Matrix 用戶端 API URL。在本例中，Synapse 可透過以下位址存取https://matrix.example.org：

cd /var/www/element
sudo cp config.sample.json config.json
sudoedit /var/www/element/config.json

編輯/var/www/element/config.json並確保其中包含有效的 JSON 對象default_server_config，例如：

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.org"
    }
  }
}

此設定將指定 Element 預設提供的伺服器。它不會建立 Synapse 帳戶，也不會強制每個使用者選擇此伺服器。目前的 Element 設定指南已default_server_config將此方法作為提供 homeserver 連線資訊的首選方式。舊default_hs_url選項已被棄用。如果您打算將使用者限制為只能使用一個伺服器，Element 提供了單獨的disable_custom_urls設定；請在啟用該設定之前，請確定它是否適合您的社群。

您還可以使用文件中提供的 Element 選項來配置一些有限的自訂設置，例如預設主題或某些品牌細節。這與完全的白標替換不同：該項目記錄的是選定的自訂設置，而不是無限制的品牌重塑。請查看配置指南，以了解您安裝的版本支援的選項；切勿在未檢查的情況下從其他版本複製設定。

請參閱 Element Web 的目前設定參考文件。develop文件會隨著專案的演進而而變化，因此請根據您部署的版本確認所有選用鍵。

3. 為 Web 用戶端新增 Nginx 站點

為您的客戶端主機名稱建立網站配置。本範例假設您已擁有位於所示證書路徑的證書chat.example.org。憑證授權過程未包含在內，因為正確的方法取決於您的主機、DNS 提供者和現有的 TLS 設定。

server {
    listen 80;
    server_name chat.example.org;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name chat.example.org;

    ssl_certificate     /etc/letsencrypt/live/chat.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/chat.example.org/privkey.pem;

    root /var/www/element;
    index index.html;

    # Revalidate the client files after deployments.
    add_header Cache-Control "no-cache" always;

    # Element Web hosting security headers.
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Content-Security-Policy "frame-ancestors 'self'" always;

    location / {
        try_files $uri $uri/ =404;
    }
}

將此程式碼區塊放入適用於您發行版的相應站點檔案中，如果需要，請啟用該站點，並檢查全域 Nginx 配置是否載入了標準mime.types檔案。 Nginx 使用 MIME 類型來告知瀏覽器回應是 JavaScript、CSS、JSON 還是其他類型的檔案。root必須指向直接包含該檔案的目錄index.html。

上述 no-cache 標頭是一個簡單的、方便部署的基準：瀏覽器會在更新後重新驗證文件，而不是繼續使用過時的用戶端程式碼。 Element 的託管說明明確要求/config.*.json`<head>` /i18n、` /version<head>`、`<head>` 和/index.html`<head>` 不應緩存，並建議對站點根目錄進行重新驗證。如果您之後為大型靜態資源添加了更長期的緩存，請確保這些路徑保持最新，並在建立快取規則之前驗證發布版本的資源命名。

Element 的 Web README 建議為自架網站啟用反框架和內容類型標頭。如果您已在其他地方設定了內容安全策略 (CSP)，請將frame-ancestors 'self'其新增至現有策略中，而不是傳送第二個 CSP 標頭。限制性 CSP 可能會阻止必要的應用程式腳本，因此請勿在未針對已部署的用戶端進行測試的情況下複製範圍過廣的策略。

請閱讀 Element Web 的託管和快取要求以及Nginx 的官方核心模組文檔，root以了解、try_files和靜態文件處理的行為。

4. 驗證設定並重新載入 Nginx

在套用配置之前先進行測試。如果 Nginx 報告錯誤，請在修復報告的檔案和行時保持目前進程運行；不要重新載入已損壞的設定。

sudo nginx -t
sudo systemctl reload nginx
curl -I https://chat.example.org/
curl -I https://chat.example.org/config.json

測試應報告語法正確且配置測試成功。 HTTPS 請求應到達目標主機並傳回成功回應。同時，請確認設定檔本身也是有效的 JSON 格式：

curl -fsS https://chat.example.org/config.json | python3 -m json.tool

然後https://chat.example.org用瀏覽器開啟。你應該會看到 Element 的登入或歡迎介面，預設伺服器是你的 Matrix homeserver。嘗試使用測試帳號，檢查瀏覽器開發者工具是否有網路請求失敗的情況，並確認登入、房間清單載入和訊息傳送功能是否正常。頁面載入成功僅證明 Nginx 服務於 Web 用戶端，並不能證明 homeserver 可存取或設定正確。

5. 確保在需要時能夠發現主伺服器

如果您的 Matrix ID 使用類似 `<server name>` 的伺服器名稱，example.org而 Synapse API 的位址為 `<server matrix.example.orgname>`，則 Matrix 用戶端可以使用位於 `<client well-known response>` 的用戶端已知回應https://example.org/.well-known/matrix/client來發現 API URL。此選用的發現端點位於 Matrix ID 的網域中，而不是 Element Web 用戶端主機名稱中。一個最小的響應如下所示：

{
  "m.homeserver": {
    "base_url": "https://matrix.example.org"
  }
}

以 JSON 格式提供，並包含瀏覽器用戶端所需的 CORS 標頭。 Synapse 的安裝文件提供了一個 Nginx 範例，並指出其public_baseurlURL 應與用戶端存取 Synapse 時使用的 URL 相符。如果您的 Element 配置直接設定了正確的 homeserver URL，並且您的使用者輸入了該用戶端特定的設置，則對於此基本設置，可能不需要進行服務發現。

請遵循 Synapse 用戶端的常用指南，並在預期使用者 ID 發現功能正常運作之前測試最終 URL curl。為了確保安全隔離，Synapse 的安全指南建議，在可行的情況下，將主伺服器託管在與敏感 Web 應用程式不同的註冊網域上；雖然使用單獨的子網域可以提供一定的保護，但使用單獨的註冊網域才是更強的建議做法。

需要避免的常見問題

Nginx 顯示 403：檢查檔案和目錄的讀取權限，並確認 Nginx 工作進程可以遍歷每個父目錄。
頁面空白或 JavaScript 傳回 404 錯誤：請確保root指向已解壓縮的發布目內容，而不是其上一層或下一層目錄。檢查 Nginx 錯誤日誌和存取日誌。
元素已載入但無法連線或登入：請檢查base_url設定config.json、主伺服器的 HTTPS 憑證、防火牆存取權限以及 Synapse 端的 CORS 或反向代理程式設定。 CORS 由瀏覽器強制執行；Nginx 靜態站點本身無法修復主伺服器的來源原則。
最近的變更沒有顯示：檢查快取標頭中的/、/index.html、/config.json、/version和/i18n，然後在確認已部署的檔案被替換後強制刷新瀏覽器。
登入頁面僅支援 HTTP：在邀請使用者登入之前，完成 TLS 設定並將 HTTP 重新導向至 HTTPS。