在 Docker 中為 ONLYOFFICE Docs 配置 HTTPS

若要直接連接到 ONLYOFFICE Docs，請發佈容器連接埠 443，將憑證檔案持久化到已掛載的資料目錄下，並將容器指向這些檔案。如果反向代理程式已提供 HTTPS，請保留該代理程式的 TLS，並將原始主機和協定轉送到 ONLYOFFICE，而不是預設啟用第二個 TLS 端點。

例如，如果公用主機名為 `<public hostname>` docs.example.com，首先要確定它是直接指向文件伺服器還是指向代理伺服器。請僅使用以下符合的配置。

1. 確定 HTTPS 的結束位置

TLS 連線在 HTTPS 解密處終止：要麼在 ONLYOFFICE 容器內，要麼在反向代理。請選擇接收公共連線的組件。

直接存取：用戶端連接到https://docs.example.com主機連接埠 443，該連接埠對應到容器連接埠 443。文件伺服器容器需要憑證及其相符的私鑰。
代理存取：客戶端透過 HTTPS 連接到代理伺服器；代理伺服器將流量轉送到內部網路的文檔伺服器。在這種設定下，憑證通常位於代理伺服器上。 ONLYOFFICE 的代理指南要求使用 `HTTPS`X-Forwarded-Proto和 `HTTPS`X-Forwarded-Host標頭，以便應用程式能夠識別公共請求方案和主機名稱。

連接埠映射443:443不會建立 HTTPS 連線；它只是映射連接埠。要實現直接訪問，容器還必須讀取憑證和金鑰。如果代理伺服器擁有公用 URL，請使用 ONLYOFFICE 的官方反向代理指南。

檔案管理器在持久性憑證資料夾中僅顯示 onlyoffice.crt 和 onlyoffice.key 這兩個檔案。 — 持久性憑證資料夾包含一個憑證檔案和一個單獨的私鑰檔案。

2. 在 Docker Compose 中設定直接 HTTPS

當容器直接提供 HTTPS 服務時，請使用此路徑。對於公共訪問，請使用用戶端信任的憑證來驗證公用主機名稱。自簽名證書可以加密流量，但除非用戶端單獨配置為信任該證書，否則用戶端會發出身份警告。

ONLYOFFICE Docs 預設將憑證儲存在以下位置/var/www/onlyoffice/Data/certs，其目前的 Docker 配置列出了tls.crt預設tls.key的憑證和金鑰路徑。文件範例中並非總是使用相同的文件名，因此本範例明確地設定了這兩個路徑。

services:
  documentserver:
    # Keep your existing image, environment, networks, and other settings.
    ports:
      - "443:443"
    volumes:
      - ./documentserver-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、網路和磁碟區設定。相對於 Compose 文件，將憑證放置在 `<certificate_name>` ./documentserver-data/certs/tls.crt，將其匹配的金鑰放置在 `<key_name> ./documentserver-data/certs/tls.key`。包含您的提供者提供的憑證鏈，並確保憑證涵蓋 `<key_name>` docs.example.com。

綁定掛載將檔案置於可替換容器之外。限制私鑰訪問，同時確保容器可以讀取私鑰；否則，HTTPS 可能無法啟動。切勿在支援請求中共用金鑰。

一段 Docker Compose 設定片段對應了連接埠 443，並將 documentserver-data 掛載到 ONLYOFFICE 資料目錄中。 — Compose 摘錄映射主機連接埠 443，並將主機端資料目錄提供給容器。

3. 套用變更時，請勿意外替換部署。

備份 Compose 檔案和憑證目錄，然後確認憑證和金鑰是否與公用主機名稱相符。
在現有服務中變更連接埠、磁碟區和路徑。請勿使用相同的主機連接埠啟動第二個容器，也不要為了套用 TLS 而丟棄現有磁碟區。
如果您變更了服務的連接埠、掛載點或環境，請重新建立該服務。使用 Compose 時，請docker compose up -d documentserver從包含 Compose 檔案的目錄執行指令，並將 `<service_name>` 替換為您的實際服務名稱。如果您僅替換了已掛載目錄中的憑證文件，請重新啟動現有容器，以便伺服器重新載入這些文件docker restart <container_name>。
如果 HTTPS 無法啟動，請檢查啟動日誌：docker logs <container_name>在變更無關設定之前，請先尋找缺少檔案、權限或憑證/金鑰的錯誤。

重新啟動服務無法新增掛載點或變更已發佈的連接埠；需要進行這些變更時，請重新建立服務。替換現有持久掛載點中的檔案不需要使用 Compose 進行變更。

終端機顯示 ONLYOFFICE 文件伺服器容器的 docker 重新啟動命令 — 取代已掛載憑證目錄中的檔案後，重新啟動現有容器。

4. 當反向代理程式已經服務於該網域時，保持反向代理程式上的 TLS 連線。

如果反向代理程式已終止https://docs.example.com，請將其私鑰保留在代理伺服器上。透過受控網路轉送流量，並將公網主機名稱設定為X-Forwarded-Proto: https「plus」X-Forwarded-Host。請使用代理軟體的正式範例。

瀏覽器鎖形圖示僅保護客戶端到代理程式的連接，並非每個內部躍點。在受控的 Docker 網路上使用 HTTP 可能適用於某些部署；如果代理程式到容器的躍點跨越不受信任的網絡，則必須確保其安全性。

另一個限制是：更改 TLS 憑證並不能修復無效的 JWT、被封鎖的防火牆連接埠或整合設定中錯誤的公共文件伺服器位址。如果憑證有效但文件載入或編輯仍失敗，請檢查相關的應用程式和代理程式日誌，而不是重複重新產生憑證。

docs.example.com 的瀏覽器憑證面板顯示了主機名稱和憑證詳細資訊。 — 在瀏覽器中，檢查證書詳細信息，並確認其標識的主機名稱與地址欄中使用的主機名稱相同。

驗證結果

從能夠存取公共服務的用戶端開啟https://docs.example.com並檢查瀏覽器的憑證詳細資訊。確認主機名稱符合、憑證在有效期限內，且瀏覽器沒有報告不受信任的發行者或名稱不符。您也可以使用終端機檢查 TLS 握手curl -Iv https://docs.example.com；查看憑證和連線輸出，而不只是依賴頁面是否載入。

最後，從整合應用程式中開啟文件。瀏覽器成功僅確認公共端點，而非所有整合設定或內部路由。對於憑證警告，請重新檢查主機名稱、憑證鏈、路徑、權限和 TLS 終止。如果 HTTPS 驗證通過但編輯失敗，請檢查日誌以及驗證或路由設定。

有關支援的 Docker 路徑、憑證變數和內建 Let's Encrypt 選項的詳細信息，請參閱ONLYOFFICE 的 Docker 安裝和 HTTPS 文件。更新現有部署的特定命令取決於其最初的建立方式；在套用相關的 TLS 變更時，請保留該部署的目前磁碟區和整合設定。