Collaboraの空白ドキュメントをトレースして、問題のあるレイヤーを特定する

まず、空白画面が特定のファイルのみに影響しているのか、すべてのファイルに影響しているのかを確認してください。次に、ブラウザのネットワークパネルとコンソールパネル、そしてCollaboraとストレージプラットフォームのログを併せて確認してください。空白画面は症状であって診断ではありません。エディタは読み込まれたものの、ドキュメント接続、WOPI認証、または埋め込みリソースの取得に失敗した可能性があります。

ツールバーの下に読み込みスピナーが表示され、ページは真っ白なままのドキュメントエディタ。 — 症状を示すブラウザ画面の例：エディタフレームは表示されるが、ドキュメントキャンバスは読み込み中は空白のままです。

1. 問題がファイル、ブラウザ、またはサービスのいずれにあるかを判断する

同じアプリケーションで正常に動作するドキュメントを開き、次に問題のあるファイルを別の対応ブラウザまたはプライベートウィンドウで開いてみてください。診断中は元のファイルを編集しないでください。1つのファイルで問題が発生している場合は、ファイル形式、コンテンツ、またはアクセス許可に問題がある可能性があります。複数のファイルで問題が発生している場合は、共有サービスまたはネットワークの変更が原因である可能性があります。

あなたが見るもの	最も役立つ次のチェック	トレードオフ
1つの文書は空白です	同じ形式の別のファイルを試してください。ストレージアプリのファイルとWOPIログを確認してください。	迅速な特定は可能だが、ファイル固有の解析や権限の問題を排除するものではない。
すべてのドキュメントが1つのブラウザで失敗します	プライベートウィンドウ、別のブラウザ、拡張機能、およびブラウザのコンソール。	リスクが低く迅速ではあるが、ブラウザの回避策ではサーバーの問題は解決しない。
すべてのユーザーとブラウザが失敗します	ネットワーク要求、リバースプロキシ、WOPIホストポリシー、およびサーバーログ。	診断上の価値は高まりますが、変更内容はすべてのユーザーに影響を与える可能性があるため、まずは現在の設定値を取得してください。

プライベートウィンドウはテスト用であり、修正用ではありません。プライベートウィンドウで問題が解決する場合は、同期されていない作業がないことを確認してから、拡張機能を1つずつ無効にするか、影響を受けているオリジンのサイトデータをクリアしてください。ブラウザのデータをすべてクリアすると、ユーザーがログアウトされ、無関係なサイトの状態が削除される場合があります。

2. 設定を変更する前に失敗したリクエストを見つける

ChromeまたはChromiumで、開発者ツール（F12またはCtrl+Shift+I）を開き、「ネットワーク」を選択して「ログを保持」を有効にし、ページを再読み込みします。WS（WebSocket）でフィルタリングして、エラーを調べます。Chrome DevToolsのネットワークリファレンスには、リクエストフィルタとステータスの詳細が記載されています。コンソールで、CSP、証明書、混合コンテンツ、またはJavaScriptのエラーを確認してください。

ブラウザの開発者ツールのネットワークパネルに、502ステータスで失敗したドキュメントおよびWebSocketリクエストが表示されます。 — ネットワークパネルの例：失敗したドキュメントおよびWebSocketリクエストは、ルーティングまたはアップストリーム接続の問題を示しています。実際のリクエスト名とステータスコードは、展開環境によって異なります。

一般的な代替手法を適用するのではなく、証拠を解釈する。

エディターのアセットまたは/browser/パスで404エラーが発生した場合：リバースプロキシが現在のCollaboraパスを適切なアップストリームに転送しているかどうかを確認してください。
502エラー、タイムアウト、またはWebSocketが即座に閉じる場合は、アップストリームへの到達可能性、プロキシログ、WebSocketの処理、およびリクエストパスを確認してください。到達可能な/hosting/discoveryエンドポイントは、基本的なHTTPアクセスを証明するだけであり、エディタのライブ接続が正常に機能していることを証明するものではありません。
ログに403または「Unauthorized WOPI host」と表示される場合： WOPI URLで指定されているストレージホストが、Collaboraで許可されているWOPIホストと照合されていることを確認してください。
CSPまたは証明書のエラー：正確な埋め込み元または証明書チェーンを修正してください。画面を読み込むために、ブラウザのセキュリティを無効にしたり、コンテンツセキュリティポリシーを大幅に緩和したりしないでください。

WebSocketリクエストの場合、ハンドシェイクの成功が目標です。表示されるステータスはHTTPバージョンとプロキシパスによって異なるため、単一の期待されるステータス番号を普遍的なものとして扱わないでください。

3. 不具合のあるレイヤーに合わせて修正を行う

両方の方向とURLスキームを確認してください

Nextcloudの現在のオフィス向けトラブルシューティングガイドによると、ユーザーのブラウザはHTTP(S)経由で両方のサーバーに接続でき、NextcloudはCollaboraに接続でき、CollaboraはNextcloudに接続できる必要があります。また、両方のサービスで同じプロトコルを使用するように指示されています。ブラウザから公開されているCollaboraアドレスをテストするには、https://office.example.com/hosting/discoveryとをhttps://office.example.com/hosting/capabilities使用します。Nextcloudホストからは、以下を使用します。

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

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

例のホスト名を実際の Collabora URL に置き換えてください。これらのチェックは HTTP の到達可能性を確認するものであり、編集の成功を保証するものではありません。サーバーは正常に動作するのにブラウザが失敗する場合は、パブリック DNS、TLS、ファイアウォール、またはプロキシの公開状況を確認してください。Nextcloud Office のトラブルシューティングガイドには、これらの接続チェック項目が記載されており、両方のアプリケーションログを確認することを推奨しています。

プロキシルーティングを修復するのは、リクエストがそれを示唆する場合に限る。

静的エディタのリソースが 404 エラーを返す場合、またはライブ接続が 502 エラーを返す場合は、リバースプロキシのルートを Collabora の公式プロキシ設定と比較してください。プロキシが必要な Collabora パスを正しいアップストリームに送信し、ブラウザで使用される WebSocket 接続をサポートしていることを確認してください。デプロイメントで想定される外部ホストと HTTPS 情報を保持してください。前提条件を確認せずに、別のプロキシ、URL プレフィックス、または Collabora リリース用の設定をコピーしないでください。専用の Collabora ホスト名を使用すると、デバッグが容易になることがよくあります。パスベースのルーティングでは、プレフィックスの一貫した処理が必要です。

WOPI許可リストを公開せずに修正する

WOPI は、Collabora がストレージプラットフォームを介してドキュメントを取得および保存するために使用するプロトコルです。WOPI ホストは通常、Collabora ホスト名ではなく、Nextcloud またはその他のストレージホスト名です。ログにと表示される場合は、Collabora の WOPI ホスト構成で正確なストレージホストを追加または修正し、ストレージプラットフォームの WOPI リクエスト許可リストに Collabora サーバーアドレスが含まれていることを確認してください。Nextcloud は、 Office 構成ガイダンスNo acceptable WOPI hosts foundで、WOPI リクエストを想定される Collabora IP アドレスに制限し、想定されるホストを信頼するように Collabora を構成することを推奨しています。

一般的なサービスログパネルに、認証されていないWOPIホストの警告と、許可されたホストとの不一致が表示されます。 — WOPIホストの不一致を示す診断画面の例です。実際のホスト名と許可リストの値は、ご自身のサーバーのログと設定でご確認ください。

ホスト検証を無効にしたり、広範囲のドメインを許可したりするよりも、特定の信頼できるホストを追加する方が安全です。現在の設定を記録し、関連するエントリのみを変更し、デプロイメントで必要な場合にのみサービスを再起動またはリロードしてください。Docker を使用している場合は、Collabora の最新の出力をで確認してくださいdocker logs --since=10m <collabora-container>。プレースホルダーを実際のコンテナ名に置き換えてください。パッケージまたは Kubernetes のインストールの場合は、代わりにサービスまたはポッドのログを使用してください。

4. ヘルスエンドポイントだけでなく、エディターも検証する

同じドキュメントを再読み込みします。アセットが読み込まれ、ライブ接続が維持され、コンテンツが表示され、コンソールエラーが停止することを確認します。問題が共有されている場合は、別のドキュメントと別のユーザーでテストします。無害なテスト編集を保存し、再度開いて読み取りと保存が可能であることを確認します。

テキストを表示する汎用ドキュメントエディタ。ネットワークパネルは正常に動作しており、WebSocketリクエストが成功しています。 — 復旧確認の例：ドキュメントの内容が表示され、ネットワークパネルにWebSocket接続が完了したことが表示されます。ご自身のブラウザでも同じ信号を確認してください。

空白のキャンバスが残ったままリクエストが成功するようになった場合は、サーバーログでドキュメント変換エラーやファイル固有のエラーを確認し、同じ形式の別のファイルと比較してください。Collabora、ブラウザ、またはプロキシのアップデート直後に問題が発生した場合は、複数の変数を一度に変更するのではなく、メンテナンス期間中に制御されたロールバックまたはバージョン固有のプロキシ変更をテストしてください。ブラウザのキャッシュクリアは、古いクライアントアセットが原因であることが示唆される場合にのみ有効であり、ブロックされたルートや拒否されたWOPIリクエストを修復することはできません。