Docker sur Windows : déployer, exécuter et réparer

Que fait Docker sur Windows : déployer, exécuter et réparer ?

Cette compétence est un savoir-faire opérationnel durement acquis en menant une application Docker Compose jusqu'à une production sans surveillance, résistante aux redémarrages sur un bureau Windows 11 derrière un réseau de Chine continentale. Les échecs ci-dessous semblent cryptiques et les correctifs sont contre-intuitifs — c'est exactement pourquoi ils sont écrits. Préférez-les aux suppositions ; chacun a coûté un véritable temps de débogage.

Rien ici n'est spécifique à une application — l'exemple d'exécution était une pile Python/FastAPI + pgvector, mais les pièges (sockets Docker Desktop, blocages réseau, démarrage automatique, encodage PowerShell) touchent tout projet Dockerisé sur Windows.

D'abord, orientez-vous avant d'agir

Vérifications rapides qui déterminent le fichier de référence dont vous avez besoin :

• Docker est-il en marche ? docker version (client+serveur), docker compose ps. Une erreur serveur signifie généralement que Docker Desktop a planté au démarrage → crash-recovery.md.
• Backend WSL2 sain ? wsl -l -v — la distribution (par ex. docker-desktop) doit être Running.
• Réseau de Chine continentale ? Si les téléchargements expirent ou échouent TLS, supposez que le réseau bloque et allez dans china-network.md avant de perdre du temps en nouvelles tentatives.
• Doit-il survivre aux redémarrages sans personne ? C'est toute une chaîne, pas un seul paramètre → unattended-operation.md.

Symptôme → référence

Ce que vous voyez	Lisez
Docker Desktop ne démarre pas, boucle en crash, ou enregistre Inference manager / Secrets Engine / listening on unix://… / le fichier ne peut pas être accédé par le système / la syntaxe est incorrecte	references/crash-recovery.md
docker pull EOF/TLS handshake timeout ; pip/apt échouent dans une construction ; wsl --install se bloque ; winget 0x8a15000f ; HuggingFace/téléchargement de modèle 302 vers un hôte bloqué	references/china-network.md
Doit s'exécuter après redémarrage sans humain (connexion automatique, autostart, écran de verrouillage, politique de redémarrage), ou "ça a fonctionné quand j'étais connecté mais pas au démarrage"	references/unattended-operation.md
Un .ps1 défigure les caractères non-ASCII, meurt avec Accolade fermante manquante '}', tue son propre processus, ou chaque commande native affiche un texte rouge effrayant	references/windows-scripting.md
Déploiement sur une nouvelle machine Windows, restauration d'un volume de base de données, ou "j'ai modifié le code mais le conteneur n'a pas changé"	references/deploy-workflow.md

Principes généraux (parcourez-les même si vous n'ouvrez pas de référence)

1. La pire panne Windows de Docker Desktop est une socket AF_UNIX orpheline, pas une erreur de configuration. Un arrêt brutal (plantage/forcé/perte de courant) laisse des fichiers de sockets de point de réparation indélébiles sous %LOCALAPPDATA%\Docker\run\ et %LOCALAPPDATA%\docker-secrets-engine\. Docker essaie de les supprimer+recréer au prochain démarrage et boucle en crash. Vous ne pouvez pas les supprimer (Remove-Item/.NET Delete échouent tous deux) — mais vous pouvez renommer le répertoire parent (une opération de métadonnées qui contourne l'erreur d'accès). Renommez-le, Docker reconstruit proprement. Basculer EnableInference/EnableDockerAI ne corrige pas le problème. Voir crash-recovery.md.

2. Sur un réseau de Chine continentale, utilisez d'abord les miroirs, puis les sources directes. Docker Hub, winget, wsl --install en ligne, deb.debian.org et les gros poids HuggingFace sont bloqués ou instables. Les miroirs de registre, Tsinghua pip/apt, un MSI WSL hors ligne et ModelScope pour les poids de modèle sont les chemins fiables. desktop.docker.com et les versions GitHub se connectent directement. Voir china-network.md.

3. Sous la connexion automatique Windows, les entrées d'autostart HKCU\...\Run ne se déclenchent SILENCIEUSEMENT PAS. Utilisez plutôt une tâche du Planificateur de tâches déclenchée Au démarrage. C'est le piège le plus important dans les configurations sans surveillance. Voir unattended-operation.md.

4. Écrivez les fichiers .ps1 en ASCII uniquement. PowerShell 5.1 lit un fichier UTF-8 sans BOM comme du GBK ; tout caractère non-ASCII (par ex. commentaires chinois) corrompt la correspondance des accolades → Accolade fermante manquante '}' → le script meurt instantanément sans laisser de journal. Maintenez les scripts en ASCII pur ; enregistrez en anglais. Voir windows-scripting.md.

5. Code monté = redémarrage, pas reconstruction. Si docker-compose.yml monte la source en bind mount (./:/app), une modification de code prend effet sur docker compose restart <svc> — pas de reconstruction d'image. Reconstruisez seulement lorsque les dépendances/Dockerfile changent. Vérifiez les changements logiques avec un test à blanc docker compose exec <svc> python … avant de laisser le vrai planning se déclencher, afin de ne jamais tester en inondant un canal de sortie en direct. Voir deploy-workflow.md.

6. Respectez les contraintes d'écriture unique. Si l'application pousse vers un canal externe selon un planning, une seule machine peut exécuter le planificateur à la fois — deux copies = envois en double. Arrêtez l'ancienne (docker compose down) avant de lancer la nouvelle.

7. Claude ne peut pas obtenir silencieusement les droits administrateur. Tout changement système nécessitant une élévation doit être confirmé par l'humain dans une invite UAC (Start-Process -Verb RunAs la déclenche). Marquez clairement ces étapes comme "需手动操作 / étape manuelle" — l'opérateur ici est sinophone et léger en infrastructure, et apprécie des instructions pas à pas avec les moments pratiques signalés. Les modes d'autorisation automatique bloquent également ExecutionPolicy Bypass + elevation, donc ne contournez pas l'invite.

Comment étendre cette compétence

Lorsqu'un nouvel échec non évident de Windows/Docker est résolu, ajoutez-le au fichier de référence correspondant (symptôme → cause racine → le correctif exact qui a fonctionné, et ce qui n'a pas fonctionné). La ligne "ce qui n'a pas fonctionné" est souvent la partie la plus précieuse — elle empêche la personne suivante de réessayer les impasses.