Collabora Onlineの「これは恥ずかしい」接続エラーを修正する

Collabora Onlineのメッセージ「大変申し訳ございませんが、ドキュメントに接続できません」は、診断ではなく症状です。このメッセージは、エディタシェルがロードされた後、ドキュメントセッションが完了できない場合に表示されます。現在の環境では、ランダムにCollaboraの設定を変更するのではなく、WOPIパス内のどの接続が失敗しているかを特定することが、この問題を解決する最も迅速な方法です。

このガイドでは、Nextcloud 35 の最新管理ドキュメントと Collabora Online の 25.04 SDK ガイダンスを参考にしています。多くの ownCloud およびカスタム WOPI 統合にも同様のトラブルシューティングロジックが適用されますが、設定名はプラットフォームやリリースによって異なる場合があります。

Collaboraの接続エラーは通常どのような原因で発生しますか？

ブラウザセッションが正常に動作するためには、いくつかの異なる経路が必要です。ユーザーのブラウザはストレージサーバーとCollaboraの両方にアクセスできる必要があり、ストレージサーバーはCollaboraにアクセスできる必要があり、Collaboraもストレージサーバーにアクセスできる必要があります。また、プロトコルと証明書は互換性があり、リバースプロキシはCollaboraのHTTPおよびWebSocketルートを正しく転送する必要があります。Nextcloudの公式トラブルシューティングページには、これらの双方向の到達可能性要件が明示的に記載されています。

つまり、万能な解決策は存在しないということです。最初に失敗したテストに基づいて修復方法を選択してください。

1. Collaboraの検出エンドポイントと機能エンドポイントを確認する

まず、統合に実際に使用されているCollaboraの公開URLから始めます。ブラウザとストレージサーバーの両方で、以下のエンドポイントを開いてください。

https://office.example.com/hosting/discovery
https://office.example.com/hosting/capabilities

Nextcloudの現在のトラブルシューティングドキュメントでは、両方のテストを実施することを推奨しています。検出エンドポイントはXMLを返し、capabilitiesはCollaboraの機能データを返します。タイムアウト、証明書の警告、404エラー、プロキシブランドのエラーページ、またはリダイレクトループが発生した場合は、WOPIの設定を変更する前に、ネットワークまたはリバースプロキシを修正する必要があります。

まず、Collaboraの公開されている検出URLと機能URLを確認してください。どちらも、統合で使用されているホスト名と同じホスト名でアクセスできる必要があります。

エンドポイントに関する信頼できるガイダンスについては、Nextcloud OfficeのトラブルシューティングおよびCollabora Online 25.04 SDKマニュアルを参照してください。

2. ブラウザだけでなく、ネットワークの4方向すべてをテストしてください。

よくある間違いは、office.example.comデスクトップブラウザで開くからといって、Collaboraがストレージサーバーからファイルを取得できると思い込むことです。これは保証されていません。実際のホストまたはコンテナからテストしてください。

# From the Nextcloud/storage server
curl -fsS https://office.example.com/hosting/discovery >/dev/null && echo OK

# From the Collabora host/container
curl -fsS https://cloud.example.com/status.php

# Then inspect Collabora logs
docker logs --tail 100 collabora

公開ホスト名がDocker、Kubernetes、またはプライベートネットワーク内で異なる解決方法を示す場合は、内部DNSを修正するか、適切なホストマッピングを追加するか、または公開エンドポイント経由でルーティングするかを決定します。内部DNSは通常、大規模な環境ではよりクリーンな状態を維持できます。hostsファイルへのエントリは小規模な静的インストールでは迅速ですが、メンテナンスが難しくなります。

サーバー自体から到達可能性テストを実行し、その後Collaboraログを使用して、ネットワーク障害とWOPI信頼関係の障害を区別します。

3. WebSocketsまたはCollaboraのルートが欠落している場合は、リバースプロキシを修正してください。

Collabora は通常の静的 Web アプリケーションではありません。そのリバース プロキシには、ブラウザのアセット、検出/機能、ドキュメント トラフィック、および WebSocket のルートが必要です。Collabora の SDK マニュアルでは、Nginx の例では/browser、、、、WebSocketパス、および関連するまたはトラフィックを転送します。/hosting/discovery/hosting/capabilities/cool/.../ws/cool/lool

WebSocketルートの場合、プロキシはホストを保持し、HTTPアップグレードを通過させる必要があります。簡略化されたNginxパターンは次のとおりです。

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_read_timeout 36000s;
}

TLS終端処理の方法が異なる場合は、この内容をそのままコピーしないでください。Collaboraでは、エンドツーエンドのTLS終端処理とSSL終端処理について、それぞれ異なるパターンを文書化しています。TLS終端処理がNginxで行われ、バックエンド接続がHTTPの場合、Collaboraの内部SSL設定もその設計に合わせる必要があります。HTTPSをあらゆる場所で使用すれば理解しやすくなりますが、プロキシでTLS終端処理を行うと、コンテナ内の証明書処理は削減されるものの、新たな設定境界が生じます。

適切なリバースプロキシは、CollaboraのHTTPルートを転送し、ドキュメントセッションのWebSocketアップグレードを保持する必要があります。

4. プロトコル、証明書、ホスト名の整合性を確認する

Nextcloudの現在のOffice構成ドキュメントでは、Collabora OnlineサーバーはNextcloudのインストールと同じプロトコルを使用する必要があり、HTTPSが推奨されています。しかし実際には、HTTPとHTTPSが混在するパブリック構成では、コンテンツのブロック、リダイレクト先の誤り、バックエンド証明書の検証エラーなどが発生する可能性があります。

以下の項目を一緒に確認してください。

• ストレージプラットフォームに保存されているCollaboraのURLは、ユーザーがアクセスする公開URLと全く同じものです。
• そのホスト名によって提示された証明書は、そのホスト名に対して有効であり、ストレージサーバーによって信頼されています。
• CollaboraはストレージサーバーのHTTPS証明書を検証できます。
• リバースプロキシは、元のホストとスキームを正しく転送します。
• WOPIが想定していない、設定済みのCollaboraホスト名から別のホスト名へのリダイレクトは存在しません。

自己署名証明書は、すべてのコンポーネントが明示的に信頼するように設定されていれば、ラボ環境では許容される場合もありますが、その利便性は移植性を犠牲にし、後々のアップグレードやコンテナの再構築で失敗する原因となることがよくあります。本番環境では、公的に信頼されている証明書チェーン、または組織が信頼している証明書チェーンを使用する方が安全です。

5. WOPIの許可リストを無効にするのではなく、正しく修正する

検出が成功し、Collaboraのログに「Unauthorized WOPI hostターゲットに一致する許容可能なWOPIホストがありません」などのメッセージが表示される場合、問題は基本的な接続性から信頼構成へと移行しています。Nextcloudの公式トラブルシューティングドキュメントでは、このケースについて管理者がコンテナログを確認するよう具体的に指示しています。

ストレージ側では、Nextcloudは「WOPIリクエストの許可リスト」設定を使用して、WOPIリクエストをCollaboraサーバーのIPアドレスに制限することを推奨しています。Collabora側では、許可されたWOPIストレージホストは、Collaboraが実際に受信するストレージURLと一致している必要があります。複数のストレージドメインの場合、Collaboraの現在のSDKにはWOPIエイリアスグループに関するドキュメントがあります。

CollaboraサーバーのURLとWOPIの許可リストは、実際の導入環境に合わせて設定してください。検証を無効にするのではなく、信頼できるエントリを限定的に使用してください。

現在のサーバー URL と WOPI 許可リストに関するガイダンスについては、Nextcloud Office の設定を参照してください。ownCloud Infinite Scale を使用している場合、そのコラボレーション サービスは、COLLABORATION_APP_ADDRオフィス アプリの URL とCOLLABORATION_WOPI_SRC外部からアクセス可能な WOPI ソースにそれぞれ を使用します。ownCloudコラボレーション サービスのドキュメントを参照してください。

Collaboraの組み込みCODEを、別途Collaboraサーバーを使用する代わりに使うべきなのはどのような場合ですか？

小規模なNextcloud環境の場合、内蔵のCODEサーバーを使用することで、外部で管理するコンポーネントの数を減らすことができます。ただし、その代償として、ブラウザで使用されているホスト名を介してNextcloudインスタンスが自身にアクセスできることが前提となります。Nextcloudのトラブルシューティングに関するドキュメントでは、この点について明確に指摘しており、内蔵のCODEサーバーが接続できない場合は、ホスト名を正しく解決するよう推奨しています。

独立したスケーリングが必要な場合、複数のストレージインスタンスを一元管理するサービスが必要な場合、またはリソース境界がより明確な本番環境アーキテクチャが必要な場合は、通常、独立したCollaboraサーバーの方が適しています。ただし、DNS、プロキシ、証明書、ファイアウォール、WOPI信頼設定などの設定が必要になるため、運用上の負担は大きくなります。

やってはいけないこと

• 最初の対策としてWOPI検証を無効にしないでください。ホスト名の不一致を隠蔽し、セキュリティ境界を弱める可能性があります。
• プロキシが機能していないという理由だけで、ポート9980を直接公開しないでください。直接公開が意図的なセキュリティ設計である場合を除き、プロキシを修正してください。
• Collaboraのホームページから200番のレスポンスが返ってきたからといって、ドキュメント編集が正常に動作していると決めつけないでください。検出、機能、WOPIファイルアクセス、WebSocketはそれぞれ別の経路で動作します。
• 複数のレイヤーを一度に変更しないでください。変更ごとにテストを行い、DNS、TLS、プロキシ、またはWOPIの信頼関係のどれが真の原因であったかを確認してください。

最終確認チェックリスト

変更を加えた後は、以下の順序でシステムを検証してください。

1. ブラウザから開いてください/hosting/discovery。/hosting/capabilities
2. ストレージサーバーから同じエンドポイントを取得します。
3. Collaboraサーバーから、ストレージサーバーのステータスURLを取得します。
4. Collaboraとストレージのログの両方を監視しながら、ドキュメントを開きます。
5. ブラウザが繰り返し切断されることなくCollabora WebSocketを確立することを確認してください。
6. 共同編集が必要な場合は、2人目のユーザーがテスト文書を開いて編集できることを確認してください。

6つのチェックすべてが成功すれば、「これは恥ずかしい」という一般的なメッセージは接続エラーを隠蔽しているものではなくなります。メッセージが消えない場合は、ドキュメントを開こうとした際のCollaboraのログ行とブラウザのネットワークエラーを正確に記録してください。これらの2つの情報は、一般的なUIメッセージ自体よりもはるかに役立ちます。