將 ONLYOFFICE Docs 置於 HAProxy 之後而不影響編輯功能

在 HAProxy 後運行 ONLYOFFICE Docs，方法是在代理伺服器端終止 HTTPS 連接，轉送原始主機和協議，並允許建立長時間的 WebSocket 連接。首先，只需一台運作正常的文件伺服器；只有當您的 ONLYOFFICE 部署配置為支援多節點操作時，才新增更多後端伺服器，而不僅僅是因為 HAProxy 可以分發請求。

HAProxy 能否對兩台獨立的文檔伺服器進行負載平衡？

HAProxy 可以將 HTTP 請求分發到各個節點，但這並不意味著兩個獨立的 ONLYOFFICE 安裝就能組成一個協同編輯叢集。編輯器會話具有持久連接和應用程式狀態。官方的 ONLYOFFICE 主動-主動模式範例使用後端健康檢查和持久性 cookie；這些是路由機制，並不能取代您的版本所需的共享服務和應用程式級架構。

對於傳統的單一伺服器安裝，請僅docs1在以下後端使用。對於雙節點安裝，請先查閱 ONLYOFFICE 部署文件或諮詢供應商支持，確認叢集架構、支援的版本、共用依賴項、版本相容性和 JWT 配置。範例位址（例如 `<example_address>`10.0.10.21和10.0.10.22`<example_address>`）是範例私人 IP 位址，並非實際發現的主機。

在修改 HAProxy 之前，哪些功能必須正常運作？

公共名稱docs.example.com應解析到您的 HAProxy 端點。 HAProxy 需要入站 TCP 連接埠 80 和 443，以及透過私人網路存取每個文件伺服器的連接埠 80。您的文件管理應用程式也必須能夠存取公用文件位址，同時 ONLYOFFICE 必須能夠取得文件並向應用程式傳送回呼。請保持後端 HTTP 通訊的私密性；如果後端躍點跨越不受信任的網絡，則需要單獨加密該躍點。

1. 從代理主機檢查每個文檔伺服器。運行curl -i http://10.0.10.21/healthcheck命令，如果存在，則執行相應curl -i http://10.0.10.22/healthcheck的操作。正常運作狀態端點通常會傳回 HTTP 200 狀態碼，並包含回應體true。如果路由、防火牆或伺服器運作狀況故障，請在設定負載平衡之前先進行檢查。
2. 確認 JWT 密鑰是否固定。文件伺服器及其連接器必須就令牌金鑰達成協議。對於 Docker 安裝，ONLYOFFICE 文件中已說明JWT_SECRET環境變數；自 Docs 7.2 版本起，依賴自動產生的金鑰可能會導致在重新建置或重新啟動後整合失敗。在支援的多節點部署中，請根據供應商的架構在各個節點之間保持一致的金鑰。

這些檢查遵循供應商的Docker 安裝指南和JWT 配置說明。請勿僅為了規避代理錯誤而停用 JWT。

如何配置HTTPS並轉送正確的標頭？

第一步：準備證書

取得涵蓋目標網域的可信任證書docs.example.com。在本 Linux 範例中，HAProxy 讀取一個包含憑證鍊和私鑰的 PEM 檔案。如果憑證已存在於其他位置，請替換為對應的路徑。限制對合併後的 PEM 文件的訪問，並在證書續期時重新建構該文件。

sudo install -d -m 700 /etc/haproxy/certs
sudo sh -c 'umask 077; cat /etc/letsencrypt/live/docs.example.com/fullchain.pem /etc/letsencrypt/live/docs.example.com/privkey.pem > /etc/haproxy/certs/docs.example.com.pem'

步驟二：新增前端和後端

請備份現有配置/etc/haproxy/haproxy.cfg，並根據以下部分進行調整，而不是盲目替換特定於發行版的日誌記錄或服務設定。這是一個適用於現代 HAProxy 版本的範例設定。它僅接受 HTTP 重定向，在 443 連接埠終止 HTTPS 請求，轉送公共主機和協議，並監控應用程式運行狀況端點。

global
    log /dev/log local0

defaults
    mode http
    log global
    option httplog
    option forwardfor
    timeout connect 5s
    timeout client 60s
    timeout server 60s
    timeout tunnel 1h

frontend docs_http
    bind :80
    http-request redirect scheme https code 301

frontend docs_https
    bind :443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]
    default_backend docs_nodes

backend docs_nodes
    option http-server-close
    balance roundrobin
    cookie SERVERID insert indirect nocache
    option httpchk GET /healthcheck
    http-check expect string true
    server docs1 10.0.10.21:80 check cookie docs1
    server docs2 10.0.10.22:80 check cookie docs2

docs2除非第二個節點確實準備就緒，否則請移除該行。持久性 cookie 有助於後續 HTTP 請求返回其選取的節點。 HAProxy 無需特殊的 URL 重寫即可處理 HTTP WebSocket 升級；timeout tunnel 1h允許空閒的升級連線保持開啟的時間比普通請求更長。 HAProxy WebSocket 文件對此行為進行了解釋。

此處設定正確X-Forwarded-Proto，https因為此前端會終止公共 HTTPS 連線。請勿信任用戶端在面向網際網路的邊緣提供的任意轉送方案或主機。 ONLYOFFICE代理文件明確要求X-Forwarded-Proto保留X-Forwarded-Host外部 URL 上下文。

應該如何重新加載和測試負載平衡器？

步驟 3：切換流量前進行驗證

重新載入前請檢查語法。非零退出狀態表示您必須先解決報告的設定或憑證錯誤才能繼續：

sudo haproxy -c -f /etc/haproxy/haproxy.cfg
sudo systemctl reload haproxy
curl -i https://docs.example.com/healthcheck

true當後端運作狀況良好時，公開的健康檢查回應應顯示 HTTP 200。 HAProxy使用 ` option httpchkand`http-check expect指令將故障節點從新請求輪替中移除；請參閱其健康檢查參考文件。通過檢查並不代表文件編輯或回調傳遞功能正常。

步驟 4：確認編輯、WebSocket 連線並儲存

透過整合應用程式（例如連接到 ONLYOFFICE Docs 的文件管理系統）開啟文件。在瀏覽器開發者工具中，使用「網路」面板檢查 WebSocket 連線：升級握手應該會成功，通常 HTTP 狀態碼為101 Switching Protocols0。進行少量編輯，關閉編輯器，重新開啟文檔，並確認變更已儲存。對於支援完善的雙節點部署，還應測試第二個協作節點，並在維護視窗期間進行規劃內的單節點資料清除。

如果公共健康檢查正常，但編輯器出現載入延遲或斷開連接，請檢查混合內容警告、WebSocket 故障、JWT 不匹配，以及文件應用程式是否可以存取已發佈的文件 URL。如果文件開啟但始終無法儲存，請檢查文件伺服器到來源應用程式的回呼可達性，而不是變更 HAProxy 的輪詢策略。中斷的活動 WebSocket 會話可能仍需要客戶端重新連線；後端健康檢查並不能保證編輯功能無縫故障轉移。

最終驗證：公共衛生端點和實際編輯並重新開啟測試均應通過。僅保留已驗證且受支援的節點進行輪換，確認憑證續期能夠重新載入正確的 PEM 文件，並監控 HAProxy 日誌，以防出現重複的 502/503 回應或意外的 WebSocket 斷開連線。