Collabora Onlineの読み込み時に画面が真っ黒になる、またはドキュメントが空白になる問題を修正する

まず、WebSocket接続と2つのサーバー間の到達可能性を確認してください。Collabora Onlineエディタが黒い画面、白いページ、または空のドキュメントキャンバスで開く場合、ドキュメントUIの読み込みが完了する前にエラーが発生していることがよくあります。問題がすべてのファイルに影響する場合は、まずブラウザからCollaboraへの経路、リバースプロキシ、およびNextcloudからCollaboraへの接続を確認してください。1つのファイルのみがエラーを起こす場合は、サーバー設定を変更する前に、別のドキュメントをテストし、そのファイルの権限と形式を確認してください。

次の手順で行ってください。ブラウザを確認し、Collaboraの検出エンドポイントをテストし、統合ログとサーバーログを読み、証拠が示すプロキシまたはWOPIの設定のみを修正します。ブラウザのキャッシュをリセットすると、古いアセットの解決に役立ちますが、破損したWebSocketや到達不能なWOPIホストは修復されません。以下のインターフェース画像は概略図です。実際のラベルとリクエストパスは、ブラウザ、クラウドプラットフォーム、プロキシ、およびCollaboraのリリースによって異なります。

症状による迅速な診断

1. 問題がブラウザ側の問題なのか、サーバー側の問題なのかを調べます。

まず、正常に読み取れることがわかっている別のドキュメントを開き、同じファイルを別のブラウザーまたはプライベートウィンドウで試してみてください。他のドキュメントは開くのに、1つのドキュメントだけが開けない場合は、ユーザーがファイルプラットフォームでそのファイルをダウンロードまたはプレビューできるかどうかを確認してください。ファイルの破損、サポートされていない形式、共有の期限切れ、または権限の不足はエディターの問題のように見えることがありますが、リバースプロキシを変更してもファイル固有の問題は解決しません。

ブラウザ側で確認するには、空白のドキュメントを再読み込みする前に開発者ツールを開きます。Chromium ベースのブラウザでは、F12またはを押してCtrl+Shift+I、[ネットワーク]を選択し、[ログを保持]を有効にして、再読み込みします。ws、、coolまたはでフィルタリングbrowserします。また、コンソール タブで、ブロックされたスクリプト、証明書の警告、またはコンテンツ セキュリティ ポリシー エラーを確認してください。

リクエストが失敗した場合は、/cool/…/wsWebSocket ハンドシェイクまたはプロキシの問題を示しています。 は502通常、プロキシがアップストリームから使用可能な応答を取得できなかったことを意味します404。 はパスがルーティングされていないことを示している可能性があり、 は403ホストまたはアクセス ルールが拒否されたことを示している可能性があります。これらのステータス コードによって検索範囲は絞り込まれますが、正確な原因を特定するには、一致するプロキシと Collabora のログが必要です。失敗したリクエストが の JavaScript または CSS ファイルである場合は/browser、プロキシがそれらの静的アセットを Collabora サービスに転送していることを確認してください。

プライベートウィンドウでネットワークリクエストが成功した場合は、スクリプトやクロスサイトリクエストをブロックするブラウザ拡張機能を一時的に無効にしてから、クラウドとCollaboraのホスト名のみのサイトデータをクリアしてください。サーバー構成を変更する前に、再度テストしてください。ネットワークタブで同じリクエストが依然として失敗する場合は、キャッシュのクリアを主な解決策としないでください。

2. CollaboraのURLと検出エンドポイントを確認する

Nextcloudとの連携を行うには、Office管理設定でCollabora OnlineサーバーのURLを確認してください。正しいホスト名とポート番号を指定して、ブラウザからアクセスできる公開URLを使用してください。Nextcloudの現在のガイドラインでは、CollaboraとNextcloudのサービスは同じプロトコルを使用する必要があり、HTTPSが推奨されています。一方のサービスがHTTPSで設定されているのに対し、もうhttp://一方のサービスがHTTPSでアクセスされるなど、プロトコルが一致しない場合、https://混合コンテンツ要求がブロックされたり、コールバックが失敗したりする可能性があります。

影響を受けるクライアントのブラウザから、 と を開きhttps://office.example.com/hosting/discovery、https://office.example.com/hosting/capabilities例のホスト名を自分のホスト名に置き換えてください。検出エンドポイントは、サポートされているドキュメントアクションを記述した XML を返します。機能には、Collabora サーバーからの応答が返されます。ブラウザのエラー、ログインページ、プロキシブランドの 404 エラー、またはゲートウェイエラーが発生した場合は、パブリック ルートが想定される Collabora エンドポイントに到達していないことを意味します。

次に、Nextcloudホストからテストを行ってください。ブラウザでのテストだけでは、サーバー同士が通信できることを証明できないためです。

curl -sS -o /dev/null -w "%{http_code}\n" https://office.example.com/hosting/discovery
curl -sS -o /dev/null -w "%{http_code}\n" https://office.example.com/hosting/capabilities

設定済みの Collabora ホスト名に置き換えてくださいoffice.example.com。HTTP 応答が成功すれば到達可能性の確認に役立ちますが、タイムアウト、DNS 障害、TLS エラー、または 5xx 応答は、対応するネットワーク、証明書、DNS、またはプロキシ層で解決する必要があります。Collabora サーバーが Nextcloud にコールバックする必要があるインストールでは、Collabora ホストから Nextcloud ステータス URL もテストしてください。

curl -fsS https://cloud.example.com/status.php

実際のNextcloudホスト名を使用してください。CODEに組み込まれたインストールでは、個別の公開Collaboraホスト名の代わりに内部プロキシURLを使用できる場合があります。そのため、スタンドアロンサーバーの例をそのまま適用するのではなく、そのデプロイメントの手順に従ってください。

3. WebSocketルートとリバースプロキシを確認する

Collabora は、複数のルートを通じてブラウザ アセットとドキュメント セッションを提供します。リバース プロキシは、インストールされているリリースで想定されるパス（エディタ アセット、検出および機能エンドポイント、ドキュメント WebSocket ルートなど）を転送する必要があります。現在の Collabora ドキュメントでは を使用しています/cool/…/wsが、古いデプロイメントではレガシー パスの設定が残っている場合があります。Nextcloud の移行ドキュメントでは、 から、 からへ/loolの過去のパス変更について特に言及しています。loleafletbrowserloolcool

プロキシ設定では、WebSocket の場所がより広範なキャッチオール ルールよりも先に一致していること、プロキシがプロキシ ソフトウェアに必要なアップグレード ヘッダーを転送していること、アップストリームが実際の Collabora サービスとポートを指していることを確認してください。また、プロキシが想定されるホストとスキーム情報を保持し、長時間の接続が開いたままになることを確認してください。TLS がプロキシで終了する場合は、Collabora の SSL 終端設定がその設計と一致していることを確認してください。

上記の短いコード抜粋は、Nginxスタイルのプロキシが必要とするWebSocketヘッダーの例を示していますが、完全なプロキシ設定ではありません。このコードをそのまま貼り付けたり、異なるバージョンのディレクティブを組み合わせたりしないでください。ご使用のプロキシとCollaboraのバージョンに対応する公式のCollaboraリバースプロキシガイドと、完全な設定を比較してください。プロキシファイルを編集した後は、リロードする前に、そのサーバーのconfiguration-testコマンドを使用して構文を検証してください。

4. WOPIホストの検証とサーバーログを確認する

Collaboraは、Webアプリケーションオープンプラットフォームインターフェース（WOPI）を使用して、Nextcloudなどの接続されたストレージサービスからドキュメントを要求します。CollaboraサーバーはWOPIホストを受け入れる必要があり、ストレージサーバーはCollaboraサービスにアクセスできる必要があります。Nextcloudでは、Office設定とWOPIリクエストの許可リストを確認してください。想定されるCollaboraサーバーのアドレスのみを追加し、ホスト検証を無効にしたり、任意のホストを許可して空白画面を消したりしないでください。

問題が再現した時点でログを確認してください。Docker デプロイメントの場合、Nextcloud のトラブルシューティング ガイドではコンテナ ログの確認方法が記載されています。実際のコンテナ名または ID を使用してください。

docker logs --tail 100 collabora

パッケージベースのインストールでは、サービス名とログ出力先はオペレーティングシステムとパッケージのバージョンによって異なります。一般的なsystemdのチェック手順は次のとおりです。

sudo journalctl -u coolwsd -n 100 --no-pager

タイムスタンプが一致し、不正な WOPI ホスト、失敗したCheckFileInfoリクエスト、TLS 検証、利用できないストレージ、または失敗した WebSocket に関するエラーがないか確認してください。許容可能な WOPI ホストが一致しないというメッセージは、通常、統合用に構成されたストレージ ホスト名が Collabora で許可されているホストと一致しないことを意味します。無関係なドメインを追加するのではなく、ホスト名または許可リストのエントリを修正してください。

また、同じリクエスト時刻のファイルプラットフォームログも確認してください。CollaboraがNextcloudに接続できない場合は、CollaboraホストからのDNS解決、ファイアウォールルール、パブリックルートまたは内部ルート、およびサービスがコンテナネットワーク内で異なる解決方法となるホスト名を介して自身にアクセスしようとしているかどうかを確認してください。Nextcloudのトラブルシューティングマニュアルでは、双方向の接続性を確認し、サーバーログを使用して障害が発生した側を特定することを推奨しています。

5. 文書を再テストし、対象を絞った変更のみを行う。

ルート、URL、証明書、または許可リストのエントリを修正した後は、デプロイメントで必要な場合にのみプロキシと影響を受けるサービスを再読み込みしてください。開発者ツールを再度開き、ファイルを再読み込みして、以前に失敗したリクエストが正常に完了することを確認してください。ドキュメントはページまたはシートを表示し、小さな編集を受け付け、その編集を正常に保存できるはずです。空白のページが消えても保存できない場合は、WOPIまたはストレージ接続が未解決であることを示しています。

• 検出は機能するが、WebSocketが失敗する：プロキシのWebSocketルート、アップグレード処理、アップストリームアドレス、および接続タイムアウトに注目してください。
• ブラウザはCollaboraにアクセスできますが、Nextcloudにはアクセスできません。NextcloudホストからDNS、ファイアウォール、TLSの信頼性、ルーティングをテストしてください。
• Collaboraから許可されていないWOPIホストが報告されました。統合設定にあるストレージホスト名とWOPIホスト許可リストの正確な値を比較してください。
• アップグレード後に問題が発生するのは古いインストール環境のみです。プロキシパスをインストール済みのリリースドキュメントと比較し、必要に応じてレガシーパス/loolまたは/loleafletルートを更新してください。
• 接続チェックに合格した後、1つのファイルのみが失敗します。グローバル設定を変更する前に、ファイルへのアクセスを確認し、コピーまたはサポートされている別の形式でテストしてください。

成功した修復とはどのようなものか

信頼できる結果とは、エディタのツールバーが表示されるだけでなく、ドキュメントの内容が正しくレンダリングされ、エディタやWebSocketリクエストの失敗が継続せず、無害なテスト編集が保存され、更新後もそのまま残る状態を指します。問題が解決しない場合は、ブラウザのネットワーク/コンソールログの抜粋（一部編集済み）と、対応するNextcloud、プロキシ、Collaboraのログ行を保存してください。ログにはホスト名、ユーザー名、ファイル識別子、トークンなどが含まれる可能性があるため、共有する前に機密情報を削除してください。

現在のデプロイメント固有の手順については、Nextcloud Office のトラブルシューティング ガイド、Nextcloud Office の構成リファレンス、およびCollabora の移行に関する注意事項を参照してください。ownCloud、別の WOPI ホスト、組み込みの CODE サービス、またはコンテナ プラットフォームに対する具体的なチェック手順は、Nextcloud の例とは異なる場合があります。