如何在 HAProxy 負載平衡器後執行 ONLYOFFICE 文件伺服器

最重要的規則是：對於單後端來說，將 ONLYOFFICE 文件伺服器部署在 HAProxy 後非常簡單，但對於多節點編輯器叢集來說，簡單的輪詢機制遠遠不夠。 ONLYOFFICE 目前的 API 文件指出，在協作編輯過程中，對相同文件的請求必須到達同一個文件伺服器節點。對於現代集成，建議的機制是shardkey使用查詢參數，負載平衡器可以利用該參數實現文件感知親和力。

如果您只有一個文件伺服器，並且希望使用 HAProxy 進行 HTTPS 終止、穩定的公用主機名稱或集中式健康檢查，則設定會比較簡單。如果您有兩個或多個文件伺服器節點，則可以使用相同的代理基本原理，但需要添加基於特定策略的路由，shardkey而不是假設普通的輪詢路由就足夠了。

以下範例已對照ONLYOFFICE 代理文件、ONLYOFFICE 分片鍵文件和HAProxy WebSocket 指南進行了檢查。

當這種設定非常合適時

當您需要一個公用 URL（例如 HAProxy）https://docs.example.com、在負載平衡器上進行 TLS 終止、啟用主動健康檢查，或希望在一個端點後部署多個文件伺服器節點時，HAProxy 是一個不錯的選擇。此外，如果您的 Nextcloud、ownCloud、自訂 DMS 或應用程式不應該直接連接到任何單一文件伺服器節點，HAProxy 也非常實用。

本指南假定：

HAProxy 可以透過內部網路存取每個文檔伺服器。
在引入負載平衡器之前，每個文件伺服器都已直接運作。
公用主機名稱解析到 HAProxy。
您的TLS憑證涵蓋公用主機名稱。
如果運行多個節點，它們將部署為受支援的 ONLYOFFICE 多伺服器架構，而不是碰巧共享負載平衡器的不相關的獨立伺服器。

步驟 1：在新增 HAProxy 之前，請先驗證每個文件伺服器。

不要從負載平衡器入手。首先，從 HAProxy 主機驗證每個後端是否運作正常。 ONLYOFFICE 文件/healthcheck是檢查編輯器可用性的端點。運作正常的伺服器會傳回true；該檢查涵蓋核心依賴項，例如資料庫、訊息代理、Redis 連線和儲存。

curl -sS http://10.0.10.21/healthcheck
curl -sS http://10.0.10.22/healthcheck

預期結果：

true
true

Ubuntu 終端機顯示兩個 ONLYOFFICE 文件伺服器後端節點的健康檢查結果，HTTP 狀態碼為 200，且均為 true。 — 在配置負載平衡之前，請直接從 HAProxy 主機檢查每個後端。負載平衡器無法彌補文件伺服器節點的故障。

如果某個後端出現故障，請先排查該節點的問題。常見原因包括防火牆規則、內部連接埠錯誤、文件伺服器服務未運作或支援服務不可用。

步驟 2：設定允許編輯器連線的 HTTP 模式和逾時時間

ONLYOFFICE 是一個 HTTP 應用程序，在編輯過程中使用長時間保持的 WebSocket 連線。 HAProxy 可以在 HTTP 升級後自動代理 WebSocket，但其逾時策略仍然至關重要。 HAProxy 的官方文件建議timeout tunnel為升級後的 WebSocket 連線設定一個合適的逾時值。

一個切實可行的基準是：

global
    log /dev/log local0
    log /dev/log local1 notice
    daemon
    maxconn 4096

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

終端機中顯示的 HAProxy 配置，包括 HTTP 模式、用戶端和伺服器連線逾時時間，以及 WebSocket 的一小時隧道逾時時間。 — WebSocket 隧道逾時時間應比普通請求逾時時間長，以避免空閒的協作編輯會話過早斷開。

一小時的隧道超時時間只是一個範例，並非普遍適用的要求。請根據貴組織的編輯習慣、安全策略和資源限制選擇一個合適的逾時值。如果編輯人員經常斷開連接，請將該逾時時間與 HAProxy 以及任何上游防火牆或反向代理的空閒逾時時間進行比較。

步驟 3：終止 HTTPS 連線並保留原始請求上下文

ONLYOFFICE 在代理伺服器後運作時，明確要求轉送標頭。具體來說，X-Forwarded-Proto它會告知文件伺服器原始客戶端使用的是 HTTP 還是 HTTPS，同時X-Forwarded-Host保留客戶端請求的主機名稱。

一個簡潔的 HAProxy 前端介面可以如下所示：

frontend onlyoffice_http
    bind *:80
    mode http
    http-request redirect scheme https code 301

frontend onlyoffice_https
    bind *:443 ssl crt /etc/haproxy/certs/docs.example.com.pem
    mode http
    option httplog

    http-request set-header X-Forwarded-Proto https
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]

    default_backend onlyoffice_docs

HAProxy 前端配置顯示了連接埠 443 上的 HTTPS、X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-For 以及 ONLYOFFICE 後端。 — 在 HAProxy 處終止 TLS，並轉送原始方案和主機，以便 ONLYOFFICE 可以產生外部正確的 URL。

通常情況下，在現代 HAProxy HTTP 模式下，您無需手動重新建立 NGINX 風格Upgrade的Connection請求頭規則。 HAProxy 會自動辨識 HTTP 到 WebSocket 的升級，並將連線切換到隧道模式。關鍵在於不要插入任何會剝離或破壞升級請求的規則。

若要查看客戶端 IP 位址，需要option forwardfor在後端新增對應功能。這樣會X-Forwarded-For根據客戶端來源位址產生一個頭部資訊。

步驟 4：新增健康檢查並選擇合適的平衡規則

單一文件伺服器

如果 HAProxy 只負責一個文件伺服器，那麼後端可以很簡單：

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    server ds1 10.0.10.21:80 check

在這個設計中，HAProxy 主要是一個反向代理、TLS 端點和健康門。

多個文件伺服器節點

對於真正的多節點部署，不要依賴簡單的輪詢機制進行協作編輯。 ONLYOFFICE 目前的文件指出，所有屬於同一文件的請求必須傳送到同一伺服器。瀏覽器到伺服器的編輯器請求會自動包含分片鍵，應用程式應?shardkey=<document-key>在文件中明確說明的情況下，將分片鍵新增至命令、轉換和文件建構器請求中。

HAProxy 支援對 URL 查詢參數進行雜湊處理，因此適用於標準 ONLYOFFICE Docs API 的後端是：

backend onlyoffice_docs
    mode http
    option forwardfor
    option httpchk GET /healthcheck
    http-check expect status 200
    timeout tunnel 1h

    balance url_param shardkey

    server ds1 10.0.10.21:80 check
    server ds2 10.0.10.22:80 check

HAProxy 後端配置包含兩個 ONLYOFFICE 節點、健康檢查、逾時機制，並說明多節點協作編輯需要文件感知親和性。 — 健康檢查會將故障節點排除在輪調之外，而文件感知親和性則用於多節點協作編輯。`shardkey`對於標準 Docs API，請使用基於路由的機制，而不是簡單的輪詢路由。

HAProxy 的url_param演算法會對選定的查詢字串參數進行雜湊處理。如果缺少該參數，HAProxy 將回退到普通的負載平衡行為。因此，您的整合必須在 ONLYOFFICE 建議的情況下，在請求中發送分片鍵，這一點尤其重要。

WOPI 有所不同。 ONLYOFFICE指出，WOPI 整合使用WOPISrc查詢參數來實現相同的路由目的。請勿將balance url_param shardkey線路原封不動地複製到 WOPI 設計中，並想當然地認為它能提供所需的關聯性。

安全地驗證並重新載入 HAProxy。

重新載入服務之前，請先驗證配置：

sudo haproxy -c -f /etc/haproxy/haproxy.cfg

僅在語法驗證成功後重新載入：

sudo systemctl reload haproxy
sudo systemctl status haproxy

如果您的發行版使用不同的服務管理員或設定路徑，請相應調整這些命令。如果您的 HAProxy 軟體包支援優雅的配置重載，則重新載入配置比不必要的強制重啟更可取。

測試時應使用公用 URL，而非僅從後端網路內部進行測試。

現在測試一下使用者和您的文件管理平台實際上能夠觸達哪些使用者：

curl -sS https://docs.example.com/healthcheck

預期內文為：

true

然後驗證TLS證書：

openssl s_client -connect docs.example.com:443   -servername docs.example.com </dev/null 2>/dev/null   | openssl x509 -noout -subject -issuer -dates

最後，透過整合應用程式開啟一個實際文件。健康檢查僅證明文件伺服器端點已準備就緒；它並不能證明回調 URL、JWT 配置、文件下載、保存回調或多節點親和性等所有功能均正確無誤。

編輯器載入後斷開連接或儲存失敗時，應該檢查哪些方面？

症狀	可能需要檢查的層	有用的行動
公眾`/healthcheck`失敗	HAProxy 路由、TLS 或後端健康狀況	直接測試每個後端，然後檢查 HAProxy 狀態和日誌。
編輯器框架載入完畢後斷開連線。	WebSocket 路徑或空閒逾時	檢查`timeout tunnel`瀏覽器和 HAProxy 之間是否有防火牆或代理程式。
產生的 URL 使用 HTTP 而不是 HTTPS。	轉發的頭部	核實`X-Forwarded-Proto: https`並`X-Forwarded-Host`。
多節點編輯行為不一致	文件親和力	確認資料`shardkey`存在，且 HAProxy 對其哈希處理一致。
健康檢查正常，但保存失敗	整合回調/網路路徑	驗證文檔伺服器是否可以存取儲存應用程式的回調和文檔 URL。
有些節點反覆離開旋轉。	後端依賴項或健康檢查	`/healthcheck`直接在受影響的節點上查詢並檢查其文件伺服器日誌。

你需要會話保持功能嗎？

對於 ONLYOFFICE 而言，傳統的基於來源 IP 位址的黏性機制並非最佳預設方案。多個使用者編輯同一文件時可能擁有不同的客戶端 IP 位址，而且一個使用者也可能開啟多個文檔，這些文檔無需位於同一節點上。基於 ONLYOFFICE 分片鍵的文檔感知親和機制更為精確，因為路由鍵代表的是正在編輯的文檔，而非使用者的網路位址。

同樣的差異也解釋了為什麼簡單的基於 cookie 的會話保持機制不應被視為 ONLYOFFICE 文件中所描述的路由行為的替代方案。建置多節點 Docs API 部署時，請使用應用程式文件中記錄的分片鍵。