Collabora OnlineをNginxの背後で設定する方法

リバースプロキシが果たすべき役割

Nginxの背後で正常に動作するCollabora Online環境では、ユーザーにはエディタ用のパブリックHTTPSアドレスが1つ提供され、Collaboraサービスはプライベートネットワーク上に維持されます。エディタはブラウザのアセットを読み込み、Officeの機能を検出し、接続されたストレージプラットフォームを介してドキュメントを開き、編集中はWebSocket接続を維持する必要があります。Nginxの構文チェックが正しいだけでは、これらのパスが正しく機能しているとは言えません。

この例では、スタンドアロンの Collabora サーバーまたは CODE コンテナがポート 9980 でリッスンし、Nginx がサービスを提供しoffice.example.com、TLS が Nginx で終了することを想定しています。ホスト名と証明書のパスを実際のものに置き換えてください。バックエンド アドレスは、127.0.0.1:9980Nginx と Collabora が同じホストを共有し、サービスがループバックにバインドされている場合にのみ適用されます。別のコンテナの場合は、プライベート Docker ネットワーク (例: ) で Collabora サービス名を使用してくださいhttp://collabora:9980。

Nginxを変更する前に

パブリック DNS 名がプロキシに解決されること、TLS 証明書がその名前を正確にカバーしていること、および Nginx が内部アドレスで Collabora にアクセスできることを確認してください。Docker を使用する場合は、両方のサービスをユーザー定義ネットワークに接続し、Collabora ポートを公開しないでください。Nginx がホスト上で実行されている場合は、コンテナポートをループバックにバインドします (例: ) 127.0.0.1:9980:9980。ファイアウォールは、Collabora バックエンドポートではなく、提供する予定のパブリック Web ポートを公開する必要があります。

TLS 構成を 1 つ選択してください。以下の構成では、ブラウザから Nginx までは TLS を使用し、信頼できるプライベート ホップを介して Collabora まではプレーン HTTP を使用します。これは TLS 終端です。ポリシーでプロキシと Collabora 間でも暗号化が必要な場合は、アップストリームに HTTPS を使用し、バックエンド証明書を信頼するように Nginx を設定してください。スキームだけを変更しないでください。サーバー側の TLS 設定は、実際の Collabora リスナーと一致する必要があります。Collabora は、Nginx リバース プロキシ ガイダンスと25.04 SDK マニュアルproxy_passで、両方のプロキシ構成について説明しています。

Collaboraのプロキシ対応TLSオプションを設定する

TLS 終端には、Collabora のcoolwsdサービスを と でssl.enable=false構成しますssl.termination=true。これらの値の設定方法は、Collabora のインストール方法によって異なります。サポートされているcoolwsd.xml構成を編集するか、パッケージまたはコンテナのドキュメントに記載されているオプションを使用してください。CODE Docker イメージの場合、デプロイメントではオプションを として渡すのが一般的ですextra_params。ご使用のバージョンのイメージドキュメントを確認し、Compose で引数を正しく引用符で囲んでください。構成を変更した後は、Collabora サービスを再起動または再作成してください。

これらの設定は、プロキシからバックエンドへのホップでHTTPが使用されている場合でも、外部接続がプロキシによって保護されていることをCollaboraに伝えます。これらの設定では、公開証明書のインストール、DNSの設定、ストレージサーバーによるCollaboraの使用許可は行われません。ストレージプラットフォームに応じて、WOPIホストの許可リストまたは統合設定を個別に構成してください。

Nginxを設定してエディタのルートを転送するようにします。

Nginx は、検出リソースとブラウザリソースを渡し、対話型編集で使用される WebSocket アップグレードを保持する必要があります。以下は、シングルサーバーの例です。 は、仮想ホスト内ではなく、メインの などのmapNginx コンテキストで定義してください。httpnginx.conf

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

サーバーブロックをNginxに含まれるサイト設定に配置してください。これは、TLS証明書が既にインストールされており、プロキシからCollaboraへの接続がHTTPであることを前提としています。

server {
    listen 443 ssl;
    server_name office.example.com;

    ssl_certificate     /etc/letsencrypt/live/office.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;

    location ^~ /browser {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
        proxy_buffering off;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 36000s;
    }
}

で始まるパスは/cool、メインの WebSocket およびエディタのリクエストを伝送します。このパターンには、互換性のためにレガシー パスも含まれています。Nginx の WebSocket プロキシでは、およびがホップ バイ ホップ ヘッダーである/loolため、HTTP/1.1 アップグレード ヘッダーが必要です。長い読み取りタイムアウトは、通常の短いプロキシ タイムアウトによってアクティブな編集接続が閉じられるのを防ぐのに役立ちます。Nginx WebSocket プロキシのドキュメントとプロキシ モジュールのリファレンスを参照してください。UpgradeConnection

アップストリームで HTTPS を使用するには、バックエンド URL を変更しhttps://、Nginx のアップストリーム証明書の検証と信頼済み​​証明書チェーンを適切に構成します。恒久的な回避策として証明書の検証を無効にすることは避けてください。Nginx が別のコンテナにある場合は、ループバック アドレスを Collabora サービス名に置き換えます。127.0.0.1プロキシ コンテナ内では、そのプロキシ コンテナを指すように設定されます。

専用ホスト名の代わりにURIプレフィックス（例：）を使用する場合/collabora/、設定とCollaboraが生成する検出URLには追加のパス処理が必要です。プラットフォームがサブパス展開を明示的にサポートしていない限り、専用ホスト名から始めてください。ルートでリクエストを転送するサーバーブロックは、プレフィックスの下で検出生成URLが機能するように自動的には働きません。

各レイヤーを再読み込みして検証する

Nginxの設定を適用する前に検証し、その後サービスをリロードしてください。

sudo nginx -t
sudo systemctl reload nginx

構文チェックが失敗した場合は、まず報告されたファイルと行を修正してください。リロードが成功した場合は、Nginxが設定を受け入れたことを確認するものであり、バックエンド、証明書、またはWebSocketパスが機能していることを示すものではありません。DNSと証明書の有効性を個別に確認してから、公開ホスト名を使用して2つのCollaboraエンドポイントにリクエストを送信してください。

curl -fsS https://office.example.com/hosting/discovery | head
curl -fsS https://office.example.com/hosting/capabilities

検出エンドポイントは、Nginxの404ページやログインページではなく、XMLを返す必要があります。機能については、Collaboraからの応答を返す必要があります。検出XMLのエディタURLを確認してください。コンテナ名や内部専用アドレスではなく、公開HTTPSホスト名と到達可能なパスを使用する必要があります。以下のサンプル画像は、確認すべき応答の種類を示しています。表示されている値は例示であり、実際のサーバーからの出力ではありません。

最後に、ドキュメントプラットフォームをhttps://office.example.comCollaboraサーバーとして設定し、テストドキュメントを開きます。成功の目安としては、エディタが読み込まれ、入力、保存、およびドキュメントの再開中も応答し続けることが挙げられます。ブラウザの開発者ツールでは、WebSocketリクエストが/cool/正常にアップグレードされるはずです。HTTPステータス101 Switching Protocolsは、期待されるWebSocketハンドシェイクの結果です。描画されたサンプルステータスを、ご自身のサーバーがこのチェックに合格した証拠として扱わないでください。

故障の症状から判断する

• 502 Bad Gateway: Nginxがアップストリームに接続できません。サービス名、ポート、コンテナネットワーク、リスナー、ログを確認してください。コンテナが別々になっている場合は、プロキシコンテナのループバックアドレスを使用しないでください。
• 検出またはブラウザアセットで404エラーが発生した場合：リクエストが正しい仮想ホストに到達し、意図しないURI書き換えなしにパスが転送されていることを確認してください。バックエンドURLだけでなく、公開URLもテストしてください。
• エディタが読み込まれるものの、フリーズしたり切断されたりする：リクエストを調べてください/cool/.../ws。アップグレードヘッダーの欠落、HTTP/1.0 アップストリーム接続、タイムアウト時間の短さ、または接続をバッ​​ファリングするプロキシが原因で編集が中断されることがあります。リクエストがアップグレードされ、ドキュメントがアクティブな間は開いたままになっていることを確認してください。
• 認証されていないWOPIホスト：プロキシは正常に動作しているにもかかわらず、Collaboraがストレージプラットフォームを拒否する場合があります。実際のWOPIホスト名をCollaboraの許可リストとプラットフォームのコネクタ設定と照合してください。バックエンドをパブリックインターネットに公開することでこの問題を解決しないでください。
• 混合コンテンツまたは証明書の警告：公開エディタのURLと検出対象のURLがHTTPSを使用していること、および証明書がホスト名と一致していることを確認してください。NginxでTLSを終端している場合は、Collaboraの終端設定も確認してください。

これらのチェックに合格したら、Collaboraバックエンドを非公開にし、いずれかのコンポーネントをアップグレードする際には、NginxとCollaboraの両方のログを監視してください。この単一アップストリームの例では、高可用性、ロードバランシング、またはドキュメントごとのセッションアフィニティは構成されていません。複数のCollaboraレプリカを使用する場合は、該当するCollaboraコントローラーまたはロードバランサーのデプロイガイダンスに従い、本番トラフィックをルーティングする前にドキュメントアフィニティをテストしてください。

出典およびバージョンノート

設定の詳細は、2026年10月6日にCollaboraのプロキシドキュメントと25.04 SDKマニュアル、およびNginxのWebSocketとproxy-moduleのリファレンスに基づいて確認されました。パッケージとコンテナのオプションはCollaboraのリリースによって異なる場合があります。適用する前に、使用しているバージョンの設定名を確認してください。この記事は特定のストレージプラットフォームを前提としておらず、実際のデプロイメントを実証するものでもありません。