HAProxyロードバランサーの背後でONLYOFFICEドキュメントサーバーを実行する方法

最も重要なルールは次のとおりです。単一のバックエンドであれば、ONLYOFFICE Document ServerをHAProxyの背後に配置するのは簡単ですが、マルチノードのエディタークラスタでは、単純なラウンドロビン以上のものが必要です。ONLYOFFICEの現在のAPIドキュメントには、共同編集中に同じドキュメントへのリクエストは同じDocument Serverノードに到達しなければならないと記載されています。最新の統合では、shardkeyロードバランサーがドキュメント認識アフィニティに使用できるクエリパラメータが推奨されるメカニズムです。

ドキュメントサーバーが1台のみで、HTTPS終端、安定したパブリックホスト名、または集中型ヘルスチェックにHAProxyを使用したい場合は、設定は簡単です。ドキュメントサーバーノードが2台以上ある場合は、プロキシの基本原理は同じですが、shardkey通常のラウンドロビンで十分だと想定するのではなく、ルーティングを追加する必要があります。

以下の例は、最新のONLYOFFICE プロキシのドキュメント、ONLYOFFICE シャードキーのドキュメント、および最新のHAProxy WebSocket ガイダンスと照らし合わせて検証されています。

この設定が適している場合

HAProxy は、単一のパブリック URL (例: ) を使用したい場合https://docs.example.com、ロードバランサーでの TLS 終端、アクティブなヘルスチェック、または単一のエンドポイントの背後に複数の Document Server ノードを配置したい場合などに、適切なフロントエンドです。また、Nextcloud、ownCloud、カスタム DMS、またはアプリケーションが個々の Document Server ノードに直接接続する必要がない場合にも役立ちます。

このガイドは以下を前提としています。

• 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 tunnelWebSocket接続に推奨される値が記載されています。

実用的な基準値は以下のとおりです。

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

トンネルタイムアウトを1時間とするのは一例であり、普遍的な要件ではありません。組織の編集行動、セキュリティポリシー、およびリソース制限に合った値を選択してください。編集者が非常に規則的な間隔で切断する場合は、その間隔を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

Upgrade最新のHAProxy HTTPモードでは、通常、NGINXスタイルのヘッダールールを手動で再作成する必要はありませんConnection。HAProxyはHTTPからWebSocketへのアップグレードを認識し、接続をトンネルモードに切り替えます。重要なのは、アップグレード要求を削除したり、破損させたりするルールを挿入しないことです。

クライアントIPアドレスを可視化するには、option forwardforバックエンドに以下の項目を追加します。これにより、X-Forwarded-Forクライアントの送信元アドレスからヘッダーが生成されます。

ステップ4：健康チェックを追加し、適切なバランスルールを選択する

シングルドキュメントサーバー

HAProxyが1つのドキュメントサーバーの前面に配置されている場合、バックエンドはシンプルに構成できます。

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アドレスを持つ可能性があり、また、1人のユーザーが同じノード上に存在する必要のない複数のドキュメントを開くこともあります。ONLYOFFICEのシャードキーに基づくドキュメント認識型アフィニティは、ルーティングキーがユーザーのネットワークアドレスではなく編集中のドキュメントを表すため、より正確です。

同様の区別は、単純なクッキーベースのスティッキーセッションをONLYOFFICEで説明されているルーティング動作の代替として扱うべきではない理由を説明しています。マルチノードのDocs APIデプロイメントを構築する場合は、アプリケーションで説明されているシャードキーを使用してください。

最終構成チェックリスト

• すべてのドキュメントサーバーは、HAProxyに追加される前のtrue状態に戻ります。/healthcheck
• HAProxyは、ONLYOFFICEのフロントエンドとバックエンドの両方でHTTPモードで動作します。
• HTTPSは、公開ドキュメントサーバーのホスト名に対して有効な証明書で終端されます。
• X-Forwarded-ProtoそしてX-Forwarded-Host正しく転送されます。
• WebSocketトンネルのタイムアウト時間は、実際の編集セッションには十分な長さです。
• バックエンドのヘルスチェックにより、障害が発生したノードがサービスから削除されます。
• マルチノードのDocs APIトラフィックはshardkey、単純なラウンドロビン方式だけでなく、アフィニティベースの方式を使用します。
• WOPI の展開では、適切なルーティングが使用されますWOPISrc。
• 公衆衛生チェックは機能しており、統合を通じて実際の文書を開いたり、編集したり、保存したりすることができます。

ドキュメントサーバーが1台の場合、HAProxyは主にクリーンなリバースプロキシおよびTLSレイヤーとして機能します。複数のドキュメントサーバーノードを使用する場合、決定的な違いはドキュメント認識ルーティングです。まずこの要件に基づいてプロキシを構築し、その後、ヘルスチェック、HTTPS、タイムアウト調整などを追加してください。