Collabora CODEコンテナのSSL終端を設定する方法

SSL終端は、Nginxなどのリバースプロキシで証明書管理を行いながら、1つのパブリックHTTPSエンドポイントが必要な場合に、Collabora Online Development Edition (CODE) コンテナに最適です。この設計では、ブラウザはHTTPS経由でNginxに接続し、Nginxがトラフィックを復号化し、Collaboraは内部ポートでプレーンなHTTPを受信します。品質目標は単に「ページが読み込まれる」ことだけではありません。正常にデプロイするには、有効なパブリック証明書、到達可能なWOPI検出エンドポイント、正常に動作するWebSocketアップグレード、および接続が維持される実際のドキュメント編集セッションが必要です。

Collaboraのプロキシに関するドキュメントでは、このSSLオフロードパターンは、プロキシとCollabora間のHTTP専用接続であり、Collabora側でssl.enable=falseは とが使用されると説明されています。Collabora Onlineのリバースプロキシ設定を参照してください。以下の例ではNginxとDocker Composeを使用していますが、必要なホストとWebSocketの動作を維持できる他のリバースプロキシでも同じ結果が得られます。ssl.termination=true

優れたSSL終端設定が達成すべきこと

ステップ1：Collaboraを変更する前にネットワーク境界を確認する

TLS の終端と、ポート 9980 にアクセスできるホストを決定します。Nginx が Docker と同じマシンで実行されている場合、公開ポートをバインドすること127.0.0.1で、インターネットへの直接アクセスを簡単に防止できます。Docker のドキュメントでは、ポートを公開すると127.0.0.1ホストにローカルに保持されることが説明されています。Dockerのポート公開に関するドキュメントを参照してください。

Nginxが別のコンテナで実行されている場合、通常は9980番ポートを公開するよりも、共有プライベートDockerネットワークを使用する方がクリーンです。原理は同じで、クライアントはCollaboraコンテナを直接使用するのではなく、HTTPSリバースプロキシのホスト名を使用する必要があります。

ステップ2：SSL終端モードでコードを実行する

プロキシ側でTLS終端処理を行う場合、Collaboraは、直接のアップストリーム接続がHTTPであっても、元のクライアント向けスキームがHTTPSであることを認識する必要があります。ドキュメントに記載されている設定は以下のとおりです。

--o:ssl.enable=false --o:ssl.termination=true

Composeの最小限の例は次のようになります。

services:
  collabora:
    image: collabora/code:YOUR_TESTED_TAG
    restart: unless-stopped
    ports:
      - "127.0.0.1:9980:9980"
    environment:
      - "extra_params=--o:ssl.enable=false --o:ssl.termination=true"
      - "server_name=office.example.com"

YOUR_TESTED_TAG本番環境に近いデプロイメントでも安全だと自動的に判断するのではなく、検証済みのバージョンに置き換えてくださいlatest。また、統合に適したWOPIホストまたはエイリアスの設定を構成してください。これらの値は、Nextcloud、ownCloud、別のWOPIホスト、またはカスタム統合のいずれに接続するかによって異なります。

コンテナを起動した後、コンテナが実行されていること、およびポートマッピングが意図した境界と一致していることを確認してください。

docker compose up -d
docker compose ps
docker logs --tail=100 collabora

バージョン26.04展開に関する注記

現在の 26.04 イメージのトラブルシューティングを行う際は、2 つの SSL フラグを唯一の変数として扱わないでください。2026 年半ば、Collabora はディストリビューションレス Docker イメージと SSL 無効化構成に関する回帰を追跡しました。公式の GitHub 問題では 26.04 の起動時の回帰が文書化されており、Collabora コミュニティのフォローアップにより、影響を受けた SSL 終端動作が後の 26.04.2.4.1 イメージで再び動作するようになったことが報告されています。イメージのアップグレード直後に以前は正常に動作していた終端構成が壊れる場合は、CollaboraOnline/online の問題 #16019を確認してください。

これも、イメージのバージョンを固定してテストする理由の一つです。設定エラーとコンテナイメージの不具合は、Nginx上では似たような症状を示すことがあります。どちらも502エラー応答やアップストリームへの接続失敗として現れる可能性があります。

ステップ3：Nginxを設定してTLSを終端し、Collaboraパスをプロキシする

NginxにはCollaboraホスト名の有効な証明書が必要であり、CollaboraのHTTPエンドポイントとWebSocketトラフィックを転送する必要があります。Collaboraのプロキシガイドには、ブラウザアセット、検出、機能、メインのWebSocket接続、ダウンロード/アップロードパス、および管理WebSocketの専用の場所が示されています。以下の設定は、その構造に従いながら、共通の転送ヘッダーを追加しています。

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;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    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 "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }

    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /cool/adminws {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 36000s;
    }
}

WebSocket ヘッダーは見た目だけのものではありません。Nginx の公式ドキュメントでは、Upgradeと はConnectionホップバイホップヘッダーであり、リバースプロキシされた WebSocket には明示的に渡す必要があると説明されています。Nginx WebSocket プロキシを参照してください。標準プロキシモジュールのドキュメントにはproxy_set_header、 、proxy_pass、 およびも記載されていますproxy_read_timeout。ngx_http_proxy_moduleを参照してください。

ステップ4：リロード前にNginxを検証する

正常に動作している設定を置き換える前に、Nginxの設定をテストしてください。

sudo nginx -t

構文テストが成功した場合のみ再読み込みする。

sudo systemctl reload nginx

次に、Nginx自体がローカルのCollaboraバックエンドにアクセスできることを確認します。同一ホスト構成の場合、以下のチェックが役立ちます。

curl -I http://127.0.0.1:9980/hosting/discovery

レスポンスヘッダーの内容はCollaboraのリリースによって異なる場合がありますが、重要な点は、TCP接続が成功し、エンドポイントがタイムアウトしたり接続を拒否したりすることなく応答することです。このローカルリクエストが失敗した場合、パブリックTLS設定を変更しても、根本的なコンテナやネットワークの問題は解決しません。

ステップ5：公開HTTPSエンドポイントを確認する

公開ホスト名を解決するクライアントから、Nginx経由で検出エンドポイントをリクエストします。

curl -I https://office.example.com/hosting/discovery

ブラウザからのリクエストはhttps://office.example.com/hosting/discoveryXMLを返す必要があります。これは、ルートURLに依存するよりも優れた機能チェックです。なぜなら、ルートページの動作はWOPIの主要な契約ではなく、バージョンによって異なる可能性があるからです。

また、ブラウザまたはTLS診断ツールを使用して証明書チェーンを確認してください。ホスト名が証明書と一致していること、チェーンが信頼できるものであること、そしてCollaboraがブラウザにプレーンなHTTP URLを通知することによって発生する混合コンテンツ警告がないことを確認してください。

ステップ6：実際のドキュメントとWebSocketをテストする

検出の成功は必要条件ではありますが、十分条件ではありません。実際のWOPIホストからドキュメントを開き、ライブセッションをテストするのに十分な時間開いたままにしてください。ブラウザの開発者ツールで、Collabora WebSocketリクエストが正常にアップグレードされ、再接続を繰り返したり、400/502エラーが返されたりしないことを確認してください。正常なセッションでは、ドキュメントの入力、保存、および再開が可能です。

エディタシェルは起動するものの、その後すぐにドキュメントが失敗する場合は、WebSocket パス、プロキシタイムアウト、WOPI 許可リスト、ホストヘッダーの動作を優先的に確認してください。WebSocket が確立される前に Nginx のログにアップストリーム接続エラーが表示されている場合は、まず CODE のリスナーとイメージのバージョンを確認してください。

一般的な故障モードの診断方法

502不正なゲートウェイ

502 エラーは通常、Nginx が設定されたアップストリームから有効な応答を取得できなかったことを意味します。CODE が実際に 9980 ポートでリッスンしているか、また正しいアップストリーム プロトコルを使用しているかを確認してください。意図された SSL 終端設計では、プロキシから CODE へのホップは HTTP です。イメージの不具合により、フラグの設定に関わらず CODE が内部的に HTTPS を提供し続ける場合は、ログと直接curlテストで不一致が明らかになります。説明のつかない設定の不具合を隠すためだけに、HTTPS アップストリームに恒久的に切り替えないでください。まず、実行している CODE イメージの動作を確認してください。

証拠開示は機能するが、文書が開かない

これはTLS自体ではなく、WebSocket転送またはWOPI認証に問題があることを示している場合が多いです。/cool/.../wsルート、アップグレードヘッダー、およびWOPIソースとして許可したホストを確認してください。CollaboraはHTTPS経由で完全にアクセスできるにもかかわらず、編集セッションを拒否または失敗させる場合があります。

混合コンテンツまたは不正なスキームのURL

ブラウザがHTTPリソースを参照するHTTPSページを検出した場合、ssl.termination=true転送されたスキームヘッダーとサーバー名を確認してください。プライベートホップがHTTPであっても、デプロイメントのパブリック側は常にHTTPSとして識別される必要があります。

編集は機能しているにもかかわらず、コンテナが異常を報告している。

最近の 26.04 リリースでは、ディストリビューションレスイメージへの移行中に変更されたヘルスチェックの動作が導入されました。Collabora では、プローブが TLS 終端の背後にある HTTP バックエンド構成を尊重しないケースが追跡されました。機能テストがパスしても Docker のヘルスが予期せず赤色になる場合は、動作するプロキシを再設計する前に、リリース固有の問題履歴を確認してください。CollaboraOnline /online の問題 #16032を参照してください。

異なるデザインを使用するタイミング

プロキシ側でのSSL終端は、リバースプロキシとCollaboraが信頼できるローカルインターフェースまたは隔離されたプライベートネットワークを介して通信する場合に適しています。NginxとCODE間のトラフィックが信頼できないネットワークを経由する場合、内部ホップでのプレーンなHTTPではセキュリティ要件を満たせない可能性があります。その場合は、バックエンドにもTLSを使用するか、両方のサービスを傍受の脅威が現実的ではない保護されたネットワークに配置してください。

同様に、証明書、ルーティング、WebSocketを正しく処理するプラットフォーム管理型のイングレスを既に運用している場合、Collaboraのためだけに2つ目のNginxレイヤーを追加してもほとんどメリットはありません。最適なアーキテクチャとは、不要なホップを経由せずに、単一の監視可能なTLS境界を提供するものです。

最終検証チェックリスト

• Collaboraのホスト名はリバースプロキシに解決されます。
• ポート443は、そのホスト名に対して信頼できる証明書を提示します。
• CODEは、ポート9980で不必要にインターネットに公開されていません。
• ssl.enable=falseこれらssl.termination=trueはHTTPバックエンド設計に適用されます。
• NginxはCODEのプライベートアドレスにアクセスできます。
• /hosting/discovery公開されているHTTPS URLを通じて応答します。
• WebSocket/cool/.../wsのアップグレードは正常に完了しました。
• 実際の文書は、開いて、編集して、保存して、また開くことができる。
• デプロイ予定のCODEイメージのバージョンを正確に特定し、テスト済みです。

これらのチェックがすべて合格すれば、SSL終端処理は正常に機能しています。外部トラフィックはHTTPSによって保護され、Collaboraは公開接続を安全な接続として認識し、編集パスは正常に動作します。いずれかのチェックが失敗した場合は、スタックの複数の部分を一度に変更するのではなく、そのレイヤーでトラブルシューティングを行ってください。