如何在 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

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

步驟 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 以及任何上游防火牆或反向代理的空閒逾時時間進行比較。

步驟 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 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 的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 配置、文件下載、保存回調或多節點親和性等所有功能均正確無誤。

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

你需要會話保持功能嗎？

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

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

最終配置檢查清單

• 每個文檔伺服器在新增至 HAProxy 之前都會傳回true相同的資料。/healthcheck
• HAProxy 以 HTTP 模式運行，用於 ONLYOFFICE 前端和後端。
• HTTPS 連線使用對公用文件伺服器主機名稱有效的憑證終止。
• X-Forwarded-Proto並X-Forwarded-Host已正確轉發。
• WebSocket隧道超時時間夠長，可以滿足實際的編輯會話需求。
• 後端健康檢查會將故障節點從服務中移除。
• 多節點文件 API 流量使用shardkey基於親和性的機制，而不是簡單的輪詢機制。
• WOPI部署使用適合的路由WOPISrc。
• 公共衛生檢查功能正常，並且可以透過整合開啟、編輯和保存真實文件。

對於單一文檔伺服器而言，HAProxy 主要是一個簡潔的反向代理和 TLS 層。而對於多個文件伺服器節點，關鍵差異在於文檔感知路由。首先圍繞這一需求建立代理，然後再添加健康檢查、HTTPS 和超時調優等功能。