如何為 ONLYOFFICE Docker 設定 HTTPS 和 SSL 憑證

若要在 Docker 中將 ONLYOFFICE Docs 置於 HTTPS 之後，請使用與公網主機名稱相符的證書，將其置於容器內部，並發佈容器的 HTTPS 連接埠。 HTTPS 是加密的 Web 連線；TLS 憑證可協助瀏覽器驗證是否已連線到預期的伺服器。本指南使用您已從受信任的憑證授權單位 (CA) 取得的憑證和私鑰。如果您使用反向代理，請按照下面的單獨選項進行操作，因為代理可能會處理 HTTPS。

哪種 HTTPS 配置方案最適合您的部署？

ONLYOFFICE Docs 可以直接從其 Docker 容器提供 HTTPS 服務，也可以使用 NGINX 或 Traefik 等反向代理來接收 HTTPS 請求並將其轉送到 Docs。對於擁有可用公網連接埠 80 和 443 的獨立伺服器，直接使用 TLS 是一個簡單直接的選擇。如果其他 Web 服務已經佔用這些端口，或者多個站點共享一台伺服器，那麼使用反向代理通常會更簡單。切勿盲目配置兩層：務必確定哪個元件負責終止 TLS 連接，並記錄代理程式到容器的連接是 HTTP 還是 HTTPS。

本教學將引導您使用 CA 所發出的憑證設定直接 HTTPS。 ONLYOFFICE 也介紹了使用 Let's Encrypt 的自動設定選項LETS_ENCRYPT_DOMAIN；LETS_ENCRYPT_MAIL該選項要求 80 和 443 連接埠可存取且未被代理程式佔用。自簽名憑證適用於私人測試網絡，但公共瀏覽器和連接的儲存服務不會自動信任它。

首先該準備什麼？

安裝了 Docker Engine 和 Docker Compose 外掛程式的 Linux 主機。
為主機名稱新增一則 DNS A 記錄，例如`<hostname> docs.example.com`，指向主機的公有 IPv4 位址。只有在配置了 IPv6 且 IPv6 可存取時，才會新增 AAAA 記錄。
入站防火牆和雲端防火牆規則允許 TCP 443 連接埠。如果您要求或續訂具有 HTTP 驗證的證書，可能還需要 TCP 80 連接埠。
包含與主機名稱完全匹配的憑證鍊及其對應的私鑰。憑證授權單位通常會提供完整的憑證鏈文件和私鑰文件。
ONLYOFFICE 資料磁碟區的持久主機目錄和一個強 JWT 金鑰。 JWT（JSON Web Token）是一個共用金鑰，用於驗證 Docs 與整合應用程式之間的請求。

Linux 終端機顯示 docs.example.com 解析到一個 IP 位址，並在 TCP 連接埠 443 上有一個監聽器。 — 在變更容器之前，請檢查 DNS 解析並確認 Docker 主機可以監聽 HTTPS 連接埠 443。

步驟 1：將憑證和私鑰放置在主機上

在本範例中，主機將持久性資料保存在 `<hostname>` 下/srv/onlyoffice/data。請將範例主機名稱和路徑替換為您自己的主機名稱和路徑。將憑證的完整鏈儲存在 `<certificate_chain>` 下tls.crt，並將符合的私鑰儲存在 ` <private_key>` 下，儲存tls.key在certs子目錄中：

sudo mkdir -p /srv/onlyoffice/data/certs
sudo install -m 0644 /path/to/fullchain.pem /srv/onlyoffice/data/certs/tls.crt
sudo install -m 0600 /path/to/privkey.pem /srv/onlyoffice/data/certs/tls.key
sudo chown root:root /srv/onlyoffice/data/certs/tls.key

私鑰應僅對需要它的帳戶或服務可讀。切勿將其貼到 Compose 檔案、問題報告或公共程式碼庫中。如果 Docker 由於所有權或權限問題無法讀取金鑰，請僅在容器運行時限制其存取權限，而不是將其設定為全域可讀。

啟動服務前，請檢查憑證的日期和主機名稱：

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -noout -subject -issuer -dates -ext subjectAltName

主題備用名稱 (SAN) 清單應包含使用者將要存取的確切主機名稱。您可以比較從憑證派生的公鑰和私鑰；這兩個雜湊值應該符合：

openssl x509 -in /srv/onlyoffice/data/certs/tls.crt -pubkey -noout | openssl sha256
openssl pkey -in /srv/onlyoffice/data/certs/tls.key -pubout | openssl sha256

終端機列出了 ONLYOFFICE 憑證目錄中的 tls.crt、tls.key 和 dhparam.pem，其中金鑰的權限受到限制。 — 將憑證及其相符的金鑰保存在主機的持久性憑證目錄中；使用嚴格的權限保護私鑰。

步驟 2：設定 Docker Compose 服務

ONLYOFFICE 的 Docker 文件將憑證放置在 `<host>` 目錄下/var/www/onlyoffice/Data/certs。其目前環境變數清單中預設的憑證檔案名稱分別為 `<host>`tls.crt和tls.key`<container>`，而範例安裝說明也使用了 ` <host>`onlyoffice.crt和 ` onlyoffice.key<container>`。明確設定路徑可以避免依賴檔案名稱約定。主機目錄會綁定掛載到對應的容器資料目錄中，連接埠 443 會作為主機連接埠 443 發布。

建立一個compose.yaml類似這樣的文件，將範例 JWT 值替換為您安裝環境產生的金鑰。下面的鏡像標籤是一個範例版本；請查看官方鏡像列表，並使用您打算長期維護的版本。

services:
  documentserver:
    image: onlyoffice/documentserver:9.4.0
    container_name: onlyoffice-documentserver
    restart: unless-stopped
    ports:
      - "443:443"
    volumes:
      - /srv/onlyoffice/data:/var/www/onlyoffice/Data
    environment:
      SSL_CERTIFICATE_PATH: /var/www/onlyoffice/Data/certs/tls.crt
      SSL_KEY_PATH: /var/www/onlyoffice/Data/certs/tls.key
      JWT_SECRET: replace_with_a_long_random_secret

產生一個強密鑰，並將openssl rand -hex 32其放置在環境變數檔案或 Compose 配置中，並設定適當的權限。如果其他應用程式與文件集成，請使用相同的 JWT 金鑰和公共 HTTPS 位址配置該應用程式。如果這是現有安裝，請在編輯現有 Compose 檔案時保留其磁碟區、網路、其他環境變數和整合設定；不要用此最小範例取代正在執行的服務定義。

從包含 Compose 檔案的目錄啟動或重新建立服務：

docker compose up -d
docker compose ps
docker compose logs --tail=100 documentserver

程式碼編輯器顯示 Docker Compose 服務發布連接埠 443，並為 ONLYOFFICE Docs 設定憑證和私鑰路徑。 — Compose 服務發佈 HTTPS 並將 ONLYOFFICE Docs 指向掛載在其資料目錄下的憑證檔案。

步驟 3：測試 HTTPS 和憑證

在瀏覽器中打開https://docs.example.com，並將主機名稱替換為您的主機名稱。檢查瀏覽器是否顯示安全連接，且沒有報告名稱不符、憑證過期或不受信任的頒發者等問題。確認 ONLYOFFICE Docs 歡迎頁面已載入。當 Docs 連接到 Nextcloud、ownCloud 或其他平台時，也請測試開啟和儲存文件的功能；僅憑瀏覽器鎖定圖示並不能證明整合的回調請求或 JWT 配置正常運作。

從 shell 中，向伺服器請求其 TLS 憑證並測試 HTTPS 回應：

openssl s_client -connect docs.example.com:443 -servername docs.example.com </dev/null
curl -I https://docs.example.com/

此-servername選項使用伺服器名稱指示 (SNI) 傳送主機名，以便伺服器在多個主機名稱共用相同位址時選擇正確的憑證。憑證日期、頒發者和 SAN 應與您安裝的憑證相符。docker compose logs如果瀏覽器無法連線或容器重複重啟，請檢查此問題。

瀏覽器網址列顯示 https://docs.example.com，旁邊有一個鎖形圖標，顯示通用的 ONLYOFFICE Docs 歡迎畫面。 — 部署完成後，存取公共 HTTPS 主機名，並確認頁面載入時沒有憑證警告。

如果反向代理程式已經處理了 HTTPS 呢？

如果 NGINX、Traefik、Caddy 或託管網關已經佔用了公網連接埠 80 和 443，則最好在該代理伺服器上安裝公網憑證。在這種拓撲結構中，僅將 Docs 容器發佈到私人 Docker 網絡，或將其 HTTP 連接埠綁定到回環位址，然後配置代理伺服器轉送所需的請求和 WebSocket 流量。將整合應用程式的 ONLYOFFICE 位址設定為公網https://URL。請遵循代理伺服器和 ONLYOFFICE 目前的轉送標頭和上游 TLS 配置說明；不要將容器的 443 連接埠發佈到代理伺服器已使用的相同主機連接埠上。

當一個代理伺服器為多個服務路由流量時，請選擇此模式。如果文件需要擁有公共 HTTPS 端點且所需連接埠空閒，請使用上述直接容器配置。如果代理伺服器透過 HTTP 連接到容器，則該內部躍點未加密；請將其置於受信任的私有網路中，或者如果您的安全性需求需要，請設定上游 TLS。

常見問題及解決方法

瀏覽器提示憑證無效。請檢查 SAN 主機名稱、憑證過期時間、完整憑證鏈，以及 DNS 是否指向目標主機。裸域名的憑證不會自動涵蓋子網域。
容器報告缺少憑證或密鑰。請驗證主機來源路徑、綁定掛載目標、確切的檔案名稱以及這兩個SSL_..._PATH值。 Docker--mount語法要求來源路徑存在；Compose 綁定掛載也應指向預期的現有目錄。
連接埠 443 已被佔用。請停止衝突的服務，使用反向代理，或選擇其他公網連接埠並確保 URL 和防火牆配置正確。如果前端使用了代理伺服器，通常情況下，代理伺服器應該會佔用公網連接埠 443。
HTTPS 連線正常，但文件編輯失敗。請檢查整合 URL、兩個服務上的 JWT 金鑰、代理轉發規則，以及 Docs 是否可以存取儲存平台。測試實際的開啟和儲存操作。
證書已續期，但網站仍在使用舊證書。請確認續期作業已更新主機掛載的文件，且 ONLYOFFICE 已重新載入該文件。如有必要，請在續期後重新啟動服務，例如使用docker compose restart documentserver從 Compose 專案目錄執行的 Certbot 部署鉤子。在依賴自動化流程之前，請使用 Certbot 的 dry-run 選項來測試續約。

保持證書有效

HTTPS 設定只有在計畫續期後才算完成。記錄憑證的頒發者和續期者、私鑰的儲存位置、將續期檔案複製到掛載目錄的進程，以及服務如何重新載入這些檔案。每次續期後，執行續期客戶端的試運行測試，監控憑證到期情況，並驗證公共端點。如果您使用 ONLYOFFICE 內建的 Let's Encrypt 變數而不是主機管理的證書，請按照 Docker 中針對該方法的說明進行操作，並針對您執行的映像和部署檢查其續期行為。

參考資料，請參閱ONLYOFFICE Docs 的 Docker 安裝和 HTTPS 指南、Docker 綁定掛載文件、Docker Compose 文件、ONLYOFFICE 官方 Docker 映像標籤以及Certbot 的官方說明。可用標籤和介面詳情可能會有所變更；請在準備新部署時進行檢查。