coolwsdログを使用してCollabora接続障害を追跡する

Collabora Online Development Edition (CODE) コンテナの場合、coolwsdログレベルをに上げdebug、SocketとWebSocketエリアが無効になっていないことを確認してから、コンテナのログを追跡しながら、ドキュメントのオープンに失敗したものを再現します。Docker Compose では、CODE イメージの環境変数を通して設定を渡しextra_params、サービスを再作成します。traceデバッグ出力に接続が停止する場所が表示されない場合にのみ を使用し、完了したら前のレベルに戻します。

この方法は、コンテナ構成を更新できる Docker または Compose デプロイメントに適しています。ネイティブ パッケージのインストールでは/etc/coolwsd/coolwsd.xml、代わりにサービス マネージャーが使用されます。この設定は診断の詳細を追加するものであり、プロキシ、WOPI ホスト、証明書、またはネットワークの問題を単独で修復するものではありません。

1. 制御された複製を1回行う

ドキュメントを1つ選択し、それを開こうとした時刻、公開されているCollaboraのURL、コンテナまたはComposeサービス名をメモしてください。複数のファイルを繰り返し更新することは避けてください。1回の試行で、ブラウザの症状、プロキシログ、統合サーバーのログ、およびcoolwsdのエントリを照合しやすくなります。

コンテナが実行されていることを確認し、その名前を特定します。

docker ps --format 'table {.Names}	{.Status}	{.Ports}'

collabora以下の内容を、ホストに表示されているコンテナ名に置き換えてください。問題が再現する直前に、以下の出力が表示され始めたら、次のようになります。

docker logs --since 2m --follow --timestamps collabora

--follow新しい出力をストリーム配信し、--since初期履歴を制限し、--timestampsDocker のタイムスタンプを追加します。Docker は、コンテナログのリファレンスでこれらのオプションを説明しています。Compose では、 を使用できます。docker compose logs --since=2m --follow collaboraここでcollaboraはサービスキーです。

2. テストのためにcoolwsdをデバッグモードにする

Collabora の設定スキーマはwarning、、、、、などの名前付きレベルをサポートしています。また、も定義されていますnotice。ドキュメントに記載されているデフォルト値でinformationは、、などからの詳細な出力が無効になっています。これは接続のトラブルシューティングにおいて重要です。レベルを変更するだけでは、最も有用なハンドシェイクの詳細が抑制されたままになる場合があります。これらのオプションは、Collabora coolwsd 設定テンプレートとCollabora Online SDK マニュアル(Docker 設定セクション、2026 年 10 月確認) に記載されています。debugtracedisabled_areasSocketWebSocket

公式collabora/codeイメージの場合は、サービスの既存のextra_params値に以下の2つのオプションを追加してください。SSL終端やサーバー名など、インストールで既に必要とされているオプションはそのまま保持してください。

services:
  collabora:
    environment:
      extra_params: "--o:logging.level=debug --o:logging.disabled_areas=Admin,Pixel"

2 番目のオプションではSocket、WebSocket高詳細ログ記録のために と が使用可能になりAdmin、 とはPixel無効のままになります。このテスト中は、これら 2 つの領域を無効リストに戻さないでください。CODE イメージのドキュメントでextra_paramsは、 を coolwsd にコマンドライン オプションを渡す方法として説明しています。デプロイメントでマウントされた構成ファイルまたはベンダー管理イメージを使用する場合は、代わりにそのデプロイメントの構成方法に従ってください。

Compose編集を適用するには、サービスを再作成してください。

docker compose up -d --force-recreate collabora

実際の Compose サービス名を使用してください。 で起動した短命のコンテナの場合はdocker run、実行構成を更新し、同じボリューム、ネットワーク、ポート、およびその他のオプションを使用して再作成してください。CODE マニュアルには、イメージがextra_params起動時に を受け入れると記載されています。既に作成済みのコンテナの環境を変更しても、実行中の coolwsd プロセスが変更されるとは考えないでください。

3. 接続を順番に読んでください

障害を一度再現し、その期間のみを確認してください。出力から、、、、などの用語を検索し、WebSocketタイムスタンプを比較してください。正確な表現やログ領域はCollaboraのバージョンによって異なるため、これらは必ずしも正確なメッセージではなく、調査すべきカテゴリとして扱ってくださいWOPI。ERRWRN

• テスト時に新しいcoolwsdエントリが見つかりませんでした。リクエストがこのコンテナに到達していない可能性があります。設定されているパブリックURL、DNS、ロードバランサー、リバースプロキシのアクセス/エラーログ、および正しいレプリカを監視しているかどうかを確認してください。
• ブラウザはサービスに到達しますが、WebSocket接続が確立されません。WebSocketのアップグレード、転送されたホストとスキーム、TLS終端、パスルーティング、アイドルタイムアウトなど、プロキシの処理状況を確認してください。ブラウザの開発者コンソールとプロキシのログと比較してください。coolwsdでは、プロキシが転送しないリクエストを説明できません。
• WOPIリクエストが発生して失敗した場合：統合サーバーのWOPI URL、ホストの許可リストまたはエイリアスの設定、Collaboraコンテナからの到達可能性、および統合サーバーの応答を確認してください。WOPIエラーは、ブラウザとCollabora間のWebSocket接続とは別の段階です。
• WOPIは成功するものの、ブラウザが切断されてしまう場合、次にWebSocketルートとブラウザ側の接続エラーに注目します。この手順で調査範囲を絞り込むことはできますが、どのプロキシやネットワーク設定が間違っているのかを特定するものではありません。

サービスがアクティブであるにもかかわらずDockerに何も出力されない場合は、コンテナ内のログ設定を確認してください。Dockerのlogコマンドはコンテナの標準出力とエラー ストリームを読み取ります。ファイルに書き込むように構成されたインストールでは、/var/log/coolwsd.log構成で定義されているパス（例：）が使用される場合があります。パスを想定するのではなく、実際のファイルを確認してください。

docker exec collabora sh -c 'grep -n -A25 "<logging>" /etc/coolwsd/coolwsd.xml'

ファイルログが有効になっている場合は、設定済みのパスを使用します。例:

docker exec collabora sh -c 'tail -n 200 /var/log/coolwsd.log'

4. 結果を確認し、通常のログ記録を復元します。

テスト後、境界付き読み取りを実行して、意図した試行によって新しいエントリが生成されたことを確認します。

docker logs --since 5m --timestamps collabora

失敗したオープンをcoolwsdイベントと同期させるか、リクエストがこのコンテナに到達しなかったことを確認できれば、有用な結果が得られます。その後、どの接続段階でフォローアップが必要かを特定できます。出力をフィルタリングする必要がある場合は、まず短い時間枠を使用してください。

docker logs --since 5m collabora | grep -Ei 'coolwsd|WOPI|WebSocket|ERR|WRN'

以前の設定logging.levelとdisabled_areas値を復元してから、サービスを再度作成してください。デバッグレベルとトレースレベルでは、より多くの出力が生成され、機密性の高い運用詳細が含まれる場合があります。ログを共有する前に、アクセストークン、ドキュメント名、ユーザー識別子、ホスト名、および内部アドレスを削除してください。サービスが公式のCODEイメージでない場合は、そのイメージのメンテナーに構成パスとサポートされているパラメータを確認してください。