rxdage/claude-skills

Windows上のDocker：デプロイ、実行、トラブルシューティング

このスキルは、中国本土ネットワーク環境下のWindows 11デスクトップ上で、Docker Composeアプリケーションを無人・再起動耐性のある本番運用にまで持っていく過程で得られた、貴重な運用ノウハウです。以下のエラーは一見不可解で、修正方法は直感に反します — だからこそ文書化されています。推測で試すよりも、これらの手順を優先してください。それぞれに実際のデバッグ時間が費やされています。

ここに書かれている内容はアプリ固有のものではありません — 実際の例としてはPython/FastAPI + pgvectorスタックを使用しましたが、落とし穴（Docker Desktopソケット、ネットワークブロック、自動起動、PowerShellエンコーディング）は、Windows上のあらゆるDockerプロジェクトに当てはまります。

まずは行動する前に状況を把握する

どの参照ファイルが必要かを判断するための簡単なチェックリスト：

• Dockerは起動していますか？ docker version（クライアント+サーバー）、docker compose ps。サーバーエラーは通常、Docker Desktopが起動時にクラッシュしたことを意味します → crash-recovery.mdを参照。
• WSL2バックエンドは正常ですか？ wsl -l -v — ディストリビューション（例：docker-desktop）がRunningである必要があります。
• 中国本土ネットワークですか？ プル/ダウンロードがタイムアウトまたはTLS障害を起こす場合、ネットワークがブロックしていると想定し、リトライに時間を費やす前にchina-network.mdを参照してください。
• 誰も監視していない状態で再起動に耐える必要がありますか？ それは単一の設定ではなく、一連の連鎖が必要です → unattended-operation.mdを参照。

症状 → 参照ファイル

症状	参照先
Docker Desktopが起動しない、クラッシュループする、またはInference manager/Secrets Engine/listening on unix://…/the file cannot be accessed by the system/syntax is incorrectのログを出力する	references/crash-recovery.md
docker pullがEOF/TLS handshake timeout；ビルド中にpip/aptが失敗する；wsl --installがハングする；winget 0x8a15000f；HuggingFace/モデルダウンロードがブロックされたホストに302リダイレクトされる	references/china-network.md
再起動後に人間の操作なしで実行する必要がある（自動ログイン、自動起動、ロック画面、再起動ポリシー）、または「ログイン中は動作したが、起動時には動作しなかった」	references/unattended-operation.md
.ps1ファイルが非ASCII文字を文字化けさせ、Missing closing '}'で停止し、自身のプロセスを強制終了する、またはすべてのネイティブコマンドが恐ろしい赤いテキストを出力する	references/windows-scripting.md
新しいWindowsマシンへのデプロイ、DBボリュームの復元、または「コードを編集したがコンテナに反映されない」	references/deploy-workflow.md

一般化できる原則（参照ファイルを開かなくてもこれらに目を通してください）

1. Docker DesktopのWindows上での最悪の障害は、設定エラーではなく、孤立したAF_UNIXソケットです。 ハードクラッシュ/強制終了/停電により、%LOCALAPPDATA%\Docker\run\と%LOCALAPPDATA%\docker-secrets-engine\の下に削除できないリパースポイントのソケットファイルが残ります。Dockerは次回起動時にこれらを削除して再作成しようとし、クラッシュループします。削除はできません（Remove-Item/.NET Deleteはどちらも失敗します）が、親ディレクトリの名前を変更することはできます（アクセスエラーを回避するメタデータ操作）。名前を変更して退避させると、Dockerはクリーンに再構築します。EnableInference/EnableDockerAIの切り替えでは修正できません。crash-recovery.mdを参照してください。

2. 中国本土ネットワークでは、直接接続よりもまずミラーを利用してください。 Docker Hub、winget、オンラインwsl --install、deb.debian.org、HuggingFaceの大きな重みはブロックされているか不安定です。レジストリミラー、Tsinghua pip/apt、オフラインWSL MSI、モデル重み用のModelScopeが信頼できる経路です。desktop.docker.comとGitHubリリースは直接接続できます。china-network.mdを参照してください。

3. Windowsの自動ログイン下では、HKCU\…\Runの自動起動エントリは 静かに起動しません。**代わりに、ログオン時にトリガーされるタスクスケジューラタスクを使用してください。これは無人セットアップにおける最大の落とし穴です。unattended-operation.mdを参照してください。

4. .ps1ファイルはASCIIのみで記述してください。 PowerShell 5.1はBOMなしのUTF-8ファイルをGBKとして読み取ります。非ASCII文字（例：中国語のコメント）はブレースマッチングを破壊し → Missing closing '}' → スクリプトはログを残さず即座に停止します。スクリプトは純粋なASCIIに保ち、ログは英語で記録してください。windows-scripting.mdを参照してください。

5. マウントされたコード = 再起動、リビルドではありません。 docker-compose.ymlがソースをバインドマウントしている場合（./:/app）、コードの編集はdocker compose restart <svc>で反映されます — イメージのリビルドは不要です。依存関係/Dockerfileが変更された場合のみリビルドしてください。ロジックの変更は、実際のスケジュールを実行する前に、使い捨てのdocker compose exec <svc> python …ドライランで検証することで、ライブ出力チャネルにスパムを送信してテストすることを避けてください。deploy-workflow.mdを参照してください。

6. 単一書き込み制約を尊重してください。 アプリがスケジュールに従って外部チャネルにプッシュする場合、スケジューラを実行できるのは1台のマシンのみです — 2台あると重複送信が発生します。新しいマシンを起動する前に、古いマシンを停止してください（docker compose down）。

7. Claudeは静かに管理者権限を取得できません。 昇格が必要なシステム変更は、UACプロンプト（Start-Process -Verb RunAsでトリガー）で人間が確認する必要があります。そのような手順は**「需手动操作 / manual step」** として明確にマークしてください — ここでのオペレーターは中国語を話し、インフラに詳しくなく、手動操作の瞬間を明示したステップバイステップのガイダンスを重視します。自動許可モードもExecutionPolicy Bypass + elevationをブロックするため、プロンプトを迂回しないでください。

このスキルを拡張する方法

新しい非自明なWindows/Dockerの障害が解決されたら、それを対応する参照ファイルに追加してください（症状 → 根本原因 → 実際に有効だった正確な修正方法、および有効だったかった方法）。「有効だったかった方法」は多くの場合最も価値のある部分です — 次の人が行き止まりを再試行するのを防ぎます。