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

Ubuntuターミナルに、2つのONLYOFFICEドキュメントサーバーのバックエンドノードに対するヘルスチェックが表示され、HTTP 200とtrueが返されている。 — ロードバランシングを設定する前に、HAProxyホストから各バックエンドを直接確認してください。ロードバランサーは、ドキュメントサーバーノードの不具合を補うことはできません。

バックエンドのいずれかで障害が発生した場合は、まずそのノードのトラブルシューティングを行ってください。一般的な原因としては、ファイアウォールルール、誤った内部ポート、ドキュメントサーバーサービスが実行されていない、またはサポートサービスが利用できないなどが挙げられます。

ステップ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

ターミナルに表示されるHAProxyの設定画面。HTTPモード、クライアントとサーバーの接続タイムアウト、WebSocketのトンネルタイムアウト（1時間）が示されています。 — WebSocketトンネルのタイムアウトは、通常の要求タイムアウトよりも長く設定する必要があります。そうすることで、アイドル状態の共同編集セッションが途中で切断されるのを防ぐことができます。

トンネルタイムアウトを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

HAProxy フロントエンド構成では、ポート 443 での HTTPS、X-Forwarded-Proto、X-Forwarded-Host、X-Forwarded-For、および ONLYOFFICE バックエンドが示されています。 — HAProxyでTLSを終端し、元のスキームとホストを転送して、ONLYOFFICEが外部的に正しいURLを生成できるようにします。

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バックエンド構成（ONLYOFFICEノード2個、ヘルスチェック、タイムアウト、および複数ノードでの共同編集にはドキュメント認識アフィニティが必要であるという注記） — ヘルスチェックにより、障害が発生したノードはローテーションから除外されます。また、複数ノードでの共同編集には、ドキュメント認識型のアフィニティが必要です。`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はHTTPSではなくHTTPを使用します	転送されたヘッダー	確認し`X-Forwarded-Proto: https`て`X-Forwarded-Host`。
複数ノード編集の動作が一貫していない	ドキュメントの親和性	`shardkey`存在すること、そしてHAProxyがそれを一貫してハッシュ化することを確認してください。
健康チェックは機能するが、保存が失敗する	統合コールバック/ネットワークパス	ドキュメントサーバーがストレージアプリケーションのコールバックおよびドキュメントのURLにアクセスできることを確認します。
一部のノードは繰り返し回転から外れます	バックエンドの依存関係またはヘルスチェック	`/healthcheck`影響を受けているノードに直接クエリを実行し、そのドキュメントサーバーのログを確認してください。

セッションを長く保持する必要がありますか？

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、タイムアウト調整などを追加してください。

コメントを残す

Excelにチェックボックスを挿入する方法：2つの簡単な方法

Excelのセル内ツールを使ってチェックボックスを挿入する方法、数式を使ってチェックされた項目の数を数える方法、古いデスクトップ版でリンクされたフォームコントロールを追加する方法を学びましょう。

Excelで文字を自動入力する方法：AからZ、そしてその先へ

Excelでフィルハンドル関数、SEQUENCE関数、または再利用可能なカスタムリストを使用して、AからZまでのアルファベット、小文字、またはZを超えるラベルを生成します。

Excelで取り消し線を引く方法：ショートカットと手順

Windows、Mac、Web版Excelで取り消し線を引く方法、セルの一部に書式を設定する方法、値を削除せずに行を削除する方法を学びましょう。

Microsoft Accessとは？そのデータベースツールはどのように機能するのか？

Microsoft Accessは、関連レコードの保存、クエリの作成、データ入力フォームの作成、レポートの生成を行うためのWindowsデータベースアプリケーションです。その仕組みと最適な活用シーンについて解説します。

Word 2010でグリッド線の高さと幅を変更する

Word 2010でグリッド線の高さと幅を調整する方法、表示される線の頻度を変更する方法、および下地となる水平方向と垂直方向の描画グリッドの間隔を設定する方法を学びましょう。

Office Outlook 2010 のインポートとエクスポート: PST ファイルを使用してデータを移動する

Outlook 2010にPSTファイルをインポートする方法、またはメール、連絡先、カレンダー、タスクをエクスポートする方法を学びましょう。正しいメニューに従い、フォルダの欠落や重複を避けてください。

Nucleus Kernelを使用してOutlook PSTファイルのパスワードを復元する

Kernelが提供する最新の手順では、忘れてしまったOutlook PSTファイルのパスワードを復元する方法を解説します。正しいファイルの特定方法、バックアップの作成方法、ツールの制限事項の確認方法などが含まれています。

PowerPointスライドにライブWebページを挿入する方法

LiveWebアドインを使用すると、WebサイトをPowerPointスライドに配置し、サイズや更新動作を設定し、プレゼンテーション前に互換性を確認できます。

Access 2010データベースをフォームで開く方法

Access 2010データベースアプリケーションを、データ入力フォームに直接開くように設定し、オブジェクトリストを非表示にし、メニューを制限し、共有前に設定を確認します。

Word 2010で既定のフォントと標準スタイルを変更する方法

Word 2010で既定のフォント、サイズ、テキスト効果を設定し、その設定をNormal.dotmに保存し、今後の文書のためにNormalスタイルを変更します。