Docker のトラブルシューティング

概要

Sitecore と Docker を使用する場合のいくつかのトラブルシューティングのテクニックを示します。

このトピックでは、Docker Desktop for Windows や Docker ベースの Sitecore での開発における問題のトラブルシューティングに関するアドバイスを示します。また、「Docker のツールとリソース」のいくつかのリソースやサイトへのリンクでも、トラブルシューティングのディスカッションを見つけることができます。

一般的なトラブルシューティングの手順

  • ログの確認: 最初にログを確認します。問題に応じて、コンテナーのログやエンジンのログを確認します。コンテナーのログへのアクセスについては、「Sitecore Docker クイック ガイド」を参照してください。また、Docker Desktop (ダッシュボード) や上記の他のツールでも、ログを確認できます。

    Sitecore の CM イメージや CD イメージでは、Sitecore の組み込みのログ ファイルの一部はデフォルトではストリーミングされません。それらのログ ファイルは LogMonitor 設定 (c:\LogMonitor\LogMonitorConfig.json) に追加できますが、それにより出力が過剰になる可能性があります。Docker サンプル リポジトリにあるように、Sitecore のログ フォルダーをバインド マウントすると役立ちます。

    cm:
 [...]
 volumes:
   - ${LOCAL_DATA_PATH}\cm:C:\inetpub\wwwroot\App_Data\logs

    Docker エンジン (デーモン) のログは、C:\Users\%USERNAME%\AppData\Local\Docker にあります。

  • Docker Desktop を再起動します。Docker Desktop を再起動すると、問題が解決することがよくあります。Windows システム トレイの Docker アイテム (クジラのアイコン) から再起動できます。

  • マップ済みのボリューム データを消去します。コンテナーで、永続ストレージにマップされたボリュームを使用している場合は、これらのフォルダー内の古いデータが問題の原因である可能性があります。デフォルトの Sitecore 設定では、このような設定は、mssql および solr サービスで使用されています。インスタンスがダウン (docker-compose down) していることを確認してください。マウントされたフォルダー内のファイルを手動で、またはクリーン スクリプトを使用して削除します (clean.ps1 は、Docker Examples リポジトリの例です)。

  • Docker リソースを整理します。最近行っていなかった場合は、使用していない Docker リソースを消去します。ディスク領域を解放するために、最低でもこの作業を毎日行うことをお勧めします。

    docker system prune

    詳細については、Sitecore Docker クイック ガイドを参照してください。

  • コンピューターを再起動します。システムを再起動すると、問題が解決することがあります。

  • Windows 用の最新の Docker Desktop にアップグレードします。Docker では、バグ修正と改良を加えた新しいバージョンの Docker Desktop for Windows が継続的にリリースされています。Windows システム トレイの Docker アイテム (クジラのアイコン) から、更新を確認できます。

  • Docker Desktop を工場出荷時のデフォルトにリセットします。これにより、Docker Desktop のすべてのオプションは、Docker Desktop が最初にインストールされたときと同じ初期状態にリセットされます。これは、Windows システム トレイの Docker アイテム (クジラのアイコン) の [トラブルシューティング] オプションから実行できます。

コンテナー環境のメモリ使用量

Sitecore は、Sitecore コンテナーを使用する場合、開発者のワークステーションに 32 GB のメモリを確保することを推奨しています (最低必要容量 16 GB 以上)。システム メモリが不足しているためにエラーやパフォーマンスの問題が発生している場合は、次の方法で環境のメモリ使用量を減らすことができます。

  • XP1 の代わりに XM1 または XP0 トポロジを実行します。

  • XM0 で変更された XM1 トポロジを実行します (開発専用)。これは、redis および cd サービスを scale: 0 に設定し、Sitecore_AppSettings_role:define 環境変数を使って cm サービスをスタンドアロン モードに設定して行います。

    redis:
  [...]
  scale: 0
cd:
  [...]
  scale: 0
cm:
  [...]
  environment:
      Sitecore_AppSettings_role:define: Standalone

  • 1909 コンテナーでプロセス分離を実行できる Windows 10 バージョンを実行している場合は、SITECORE_VERSION および ISOLATION 環境変数を使って、1909 ベースの Sitecore コンテナーとプロセス分離に切り替えます。

    SITECORE_VERSION=10.0.0-1909
ISOLATION=process

  • コンテナーごとにメモリ制限を設定します。Docker はデフォルトで 1 GB を使用しますが、mssql または solr サービス以外の特定のサービスではこの値以下に減らすことができます。

  • 不要なコンテナーのサービスを無効にします。たとえば、XP1 トポロジで Marketing Automation Engine を使用しない場合は、xdbautomation、 xdbautomationrpt および xdbautomationworker を無効にします。あるいは、Cortex を使用しない場合は、cortexprocessing、cortexreporting および cortexprocessingworker を無効にします。これは、サービスを scale: 0 に設定し、depends_on 条件をすべて削除して行います。

ウイルス対策ソフトウェアがインストールされている場合に、Docker Desktop の起動が失敗する

ウイルス対策ソフトウェアのスキャンから Docker データ ディレクトリを除外してみることができます (%ProgramData%\docker) 。詳細については、https://docs.docker.com/engine/security/antivirus/ を参照してください。

Windows コンテナーがインターネットにアクセスできない

これは、NuGet 復元操作の接続エラーなど、さまざまな現象として現れます。

出典: https://github.com/docker/for-win/issues/2760#issuecomment-430889666:

これは、ホストに複数のネットワーク アダプター (イーサネット、Wi-Fi) がある場合によく発生します。Windows ネットワーク スタックがゲートウェイ ルートを正しく選択できるよう、これらのアダプターの優先順位を適切に設定する必要があります。これは、プライマリ インターネット接続ネットワーク アダプターの InterfaceMetric 値を最小値に設定することで実行できます。

Get-NetIPInterface -AddressFamily IPv4 | Sort-Object -Property InterfaceMetric -Descending

このコマンドを使用して変更します (この例では、プライマリ アダプターの InterfaceAlias が 'Wi-Fi' であると仮定しています)。

Set-NetIPInterface -InterfaceAlias 'Wi-Fi' -InterfaceMetric 3

Hyper-V で外部仮想スイッチが設定されているためにホストのプライマリ ネットワーク アダプターがブリッジされている場合は、外部仮想スイッチの InterfaceMetric 値を最小に設定します。

このコマンドを使用して、ルーティング テーブルを確認できます (最後の行には、プライマリ アダプターのゲートウェイ アドレスとその ifMetric 値が表示されます)。

Get-NetRoute -AddressFamily IPv4

ポートが使用中です /「プロセスはファイルにアクセスできません」

Sitecore 環境を起動しようとすると、次のようなエラーが表示される場合があります。

ERROR: for myproject_traefik_1  Cannot start service traefik: failed to create endpoint myproject_traefik_1 on network myproject_default: failed during hnsCallRawResponse: hnsCall failed in Win32: The process cannot access the file because it is being used by another process. (0x20)

このエラーは、必要なポートを使用する IIS またはその他のプロセスを停止する必要があることを示しています。必要なポートの完全なリストについては、最初の Sitecore インスタンスを実行する を参照してください。

無効な SQL Server 管理者パスワードによるエラー

SQL_SA_PASSWORD 値は、SQL Server が指定する安全なパスワード要件を満たす必要があります。これらの要件を満たさないパスワードには、次のようなエラーが表示されます。

  • 使用している環境 (XConnect、CM など) のコンテナーの状態が異常な場合は、次のような起動エラーが表示されます。

    ERROR: for traefik  Container <id> is unhealthy.
ERROR: Encountered errors while bringing up the project.

  • XConnect コンテナー ログのエラー:

    Microsoft.Azure.SqlDatabase.ElasticScale.ShardManagement.ShardManagementException: Store Error: Login failed for user 'sa'.. The error occurred while attempting to perform the underlying storage operation during 'Microsoft.Azure.SqlDatabase.ElasticScale.ShardManagement.StoreException: Error occurred while performing store operation. See the inner SqlException for details. ---> System.Data.SqlClient.SqlException: Login failed for user 'sa'.

  • SQL Server コンテナー ログのエラー:

    VERBOSE: Changing SA login credentials
Msg 15118, Level 16, State 1, Server 96FAC1ED734A, Line 1
Password validation failed. The password does not meet the operating system policy requirements because it is not complex enough.

    デフォルトの SQL Server ポリシーに適合するよう、SQL_SA_PASSWORD の SQL パスワードを変更します。.env ファイルのパスワードを変更したら、docker-compose down の実行後に、マウント済み SQL データ フォルダーをクリアします。内容を手動で削除するか、クリーン アップ スクリプトを使用できます (Docker Examples リポジトリの clean.ps1 の例を参照)。

コンテナーが [作成済み] ステータスで機能不全になる

通常は、docker-compose up を使用した後にこのエラーが表示されます。特定のサービスの実行が失敗することがあり、docker ps -a を確認すると作成済み状態が報告されています。

この問題を解決するには、Docker Compose ファイル内で問題のあるコンテナーのメモリ制限を増やします。Docker のデフォルトは 1 GB ですが、サービスによってはこれでは小さすぎる場合があります。たとえば、mssql および solr サービス用のコンテナーには 2 GB が必要な場合があります。

mssql:
  [...]
  mem_limit: 2GB
solr:
  [...]
  mem_limit: 2GB

管理者として Sitecore にログインできない

これは、永続的な SQL データ ストレージが有効になっていて (Docker Compose 設定でマウントされたボリュームを介して)、.env ファイル内の Sitecore 管理者パスワード (SITECORE_ADMIN_PASSWORD 変数) を変更した場合に発生する可能性があります。パスワードはデータベース ファイルが最初に作成されたときに設定されるため、パスワードの変更前にインスタンスが実行されたときに (docker-compose up を使用して) 古くなっています 。

デフォルトの Sitecore 設定ではこれが有効になっており、ボリュームは mssql-data フォルダーにマウントされています。

mssql:
  [...]
  volumes:
    - type: bind
      source: .\mssql-data
      target: c:\data

これを解決するには、インスタンスがダウン (docker-compose down) していることを確認し、マウントされたフォルダー内のファイルを削除します。手動で削除するか、クリーン スクリプトを使用できます (Docker Examples リポジトリの clean.ps1 の例を参照)。

不正な機能エラー

コンテナーの起動時またはイメージのビルド時に、次のエラーが表示される場合があります。

hcsshim::PrepareLayer - failed failed in win32 : Incorrect function. (0x1)

これは多くの場合、Box、Dropbox、OneDrive などのツールの互換性がないドライバーが原因です。これについては、GitHub の Docker Desktop for Windows の問題に関するディスカッションで回避策や解決策の提案を参照してください。

「コンテナーのシャットダウンに失敗しました」エラー

コンテナーの起動時またはイメージのビルド時に、次のエラーが表示される場合があります。

failed to shutdown container: container 45917373d49ed4130f7c7ac16f19f59379c1c98d0c429cc806a6f292d6792286 encountered an error during hcsshim::System::Shutdown: failure in a Windows system call: The connection with the virtual machine or container was closed. (0xc037010a): subsequent terminate failed container 45917373d49ed4130f7c7ac16f19f59379c1c98d0c429cc806a6f292d6792286 encountered an error during hcsshim::System::waitBackground: failure in a Windows system call: The connection with the virtual machine or container was closed. (0xc037010a)

ほとんどの場合、Docker Desktop を再起動するとこの問題は解決しますが、マシンの再起動が必要になる場合もあります。

こちらの GitHub での Docker Desktop for Windows の問題に関するディスカッションを参照にしてください。

ファイアウォールとプロセス分離の競合

特定のファイアウォール設定では、プロセス分離を使用するコンテナーが相互に通信できなくなります。ログを調べると、異常なコンテナーや、コンテナー間のネットワーク通信エラーなどの現象が報告されています。

特定のファイアウォールの競合を見つけるのは難しい場合があります。回避策として、影響を受けた各コンテナーをデフォルトの分離に設定できます (docker-compose.override.yml などを使用)。

solr:
  [...]
  isolation: default