CollaboraをNginxの背後に配置してもWebSocketが壊れないようにする方法

Collabora を Nginx の専用の HTTPS ホスト名に配置し、エディタと検出パスを に転送しcoolwsd、ライブソケットルートで WebSocket アップグレードヘッダーを明示的に渡します。単一のホストの場合、Nginx はパブリック TLS を終端し、プライベートインターフェースで Collabora に HTTP を送信できます。Nginx と Collabora が異なるコンテナで実行されている場合は、 の代わりに共有ネットワーク上の Collabora サービス名を使用します127.0.0.1。

この例では、ユーザーがアクセスを許可しhttps://office.example.com、Nginx が証明書を処理することを前提としています。Collabora のデフォルトのリスニングポートは 9980 です。デプロイメントでアクセス可能なポートを使用してください。 のような URL プレフィックスにはhttps://example.com/collabora/、パスとサービス ルートの設定を調整する必要があるため、このルート ホスト構成はそのままでは適用されません。

1. アップストリームとWebSocket接続マップを定義する

Nginxのコンテキストで、Collaboraのアップストリーム名と、クライアントがWebSocketを要求した場合にのみhttp接続ヘッダーを設定するマップを追加します。このブロックは、他のブロックの外側に配置してください。Nginxが別の方法でCollaboraにアクセスする場合は、アドレスを置き換えてください。upgradeserver

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

upstream coolwsd {
    server 127.0.0.1:9980;
}

Nginx自体がコンテナである場合、は127.0.0.1Collaboraコンテナではなく、そのNginxコンテナを参照します。共有Dockerネットワークでは、代わりに、そのネットワークで解決されるサービス名を使用して、upstreamを指定できますserver collabora:9980;。

2. HTTPS仮想ホストとCollaboraルートを追加する

のHTTPSserverブロック内でoffice.example.com、ブラウザのアセット、検出エンドポイント、WebSocket 接続、および残りの Collabora パスを転送します。場所は Collabora のプロキシに関するガイダンスに従います。Nginxが WebSocket ヘッダーを正しく適用できるように、特定のソケットの場所は、より広範なcool/ルートよりも上位に配置してください。lool

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

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/private-key.pem;

    location ^~ /browser {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ^~ /cool/adminws {
        proxy_pass http://coolwsd;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://coolwsd;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

証明書のパスをホストのファイルに置き換えてください。インストールで管理コンソールを使用しない場合は、/cool/adminwsドキュメント編集に場所が必要ない場合があります。メイン/cool/.../wsルートは必須です。proxy_read_timeoutここでの1時間は例として示したもので、普遍的な要件ではありません。Nginxのデフォルトのプロキシ読み取りタイムアウトは、連続読み取りの間隔が60秒です。セッションに必要なアイドル期間よりも長い値を選択するか、サポートされている場合は適切なWebSocket pingトラフィックを利用してください。

3. CollaboraのTLSモードをプロキシホップに合わせる

プライベートなNginxからCollaboraへのホップでHTTPが使用されている場合でも、ユーザーはHTTPS経由でCollaboraにアクセスする必要があります。TLS終端構成では、coolwsdプロキシをTLS終端として扱うように設定してください。内部リスナーではSSLを無効にし、SSL終端を有効にします。これらの設定は、パッケージまたはコンテナイメージでサポートされている方法で適用し、Collaboraのドキュメントに従って再起動/リロードしてください。

HTTP アップストリームは信頼できるプライベート ネットワークでのみ使用し、ポート 9980 へのパブリック アクセスをブロックしてください。ポリシーで Nginx と Collabora 間で暗号化が必要な場合は、HTTPS アップストリームを使用し、証明書の検証を正しく構成してください。証明書の不一致を隠すために検証を無効にしないでください。Collabora のプロキシ設定ドキュメントでは、プロキシでの SSL とプロキシと 間の SSL を区別していますcoolwsd。

また、ストレージ統合における Collabora URL を、公開されている HTTPS ホスト名に設定してください。Nextcloud の場合、管理マニュアルでは、ブラウザと両方のサーバーが、一致する外部プロトコルを使用して HTTP(S) 経由で相互に通信できることが求められています。WOPI の許可リストは、想定されるストレージホストと Collabora アドレスに限定してください。プロキシルーティングエラーを解決するために、許可リストを広範囲に拡大しないでください。

4. 両側から構成をテストする

Nginxを再読み込みする前に、構文を確認してください。

sudo nginx -t
sudo systemctl reload nginx

Nginxがコンテナ内で実行されている場合は、そのコンテナの検証およびリロード手順を使用してください。Nextcloudホストから、実際のホスト名を使用して公開されているCollaboraエンドポイントをテストしてください。

curl -fsS https://office.example.com/hosting/discovery -o /dev/null
curl -fsS https://office.example.com/hosting/capabilities -o /dev/null

それらの HTTPS URL もユーザーのブラウザーから開いてください。到達可能性は確認されますが、検出応答が成功しただけでは、ドキュメント編集が機能していることは証明されません。ドキュメントを開き、ブラウザーのネットワーク パネルを使用して、アセットがロードされ、接続が/cool/.../ws開いたままになっていることを確認します。HTTP/1.1 WebSocket が成功すると、通常は が表示されます101 Switching Protocols。正確な表示はブラウザーとトランスポートによって異なる場合があります。この標準設定が Firefox では機能するのに Chromium では失敗する場合は、リクエスト メソッドとプロトコルを調べます。25.04 用に開かれた Collabora の問題報告では、HTTP/2 上の Chromium WebSocket が を使用しCONNECT、405 を受信したことが報告されています。2026 年 10 月 9 日現在、この問題は未解決のままです。これはバージョン固有の報告であり、普遍的な動作ではありません。HTTP/2 の設定を変更する前に、Collabora、Nginx、およびブラウザーのバージョンを比較してください。Collaboraの問題 12155を参照してください。

検出が失敗した場合は、Nginx のエラー ログを調べて、アップストリームのホスト名、ポート、プロトコルを確認してください。検出は成功したが編集が接続できない場合は、WebSocket のルート、ヘッダー、タイムアウト、および Collabora のログを確認してください。WOPI 認証エラーは、ストレージ ホストの許可リストに問題があることを示しています。Nextcloud Office のトラブルシューティング ガイドでは、ブラウザ、Nextcloud、および Collabora からの接続性を確認し、両方のサーバーのログを確認することを推奨しています。

Nginx WebSocketプロキシガイドでは、なぜUpgradeとをConnection明示的に渡す必要があるのか​​、またアイドルタイムアウトの動作が重要な理由について説明しています。ディレクティブの動作については、 Nginxプロキシモジュールのリファレンスを参照してください。チェックが完了したら、新しいルートをユーザーに利用させる前に、テストドキュメントを開いて編集し、保存して再度開いてください。