Docker no Windows: implantar, executar e desvendar

O que Docker no Windows: implantar, executar e desvendar faz?

Esta skill é conhecimento operacional conquistado com muito esforço ao levar uma aplicação Docker Compose até o estado de produção desassistida e resiliente a reinicializações em um desktop Windows 11 atrás de uma rede na China continental. As falhas abaixo parecem enigmáticas e as correções são contra-intuitivas — é exatamente por isso que estão registradas. Prefira estas soluções a tentativas aleatórias; cada uma custou tempo real de depuração.

Nada aqui é específico da aplicação — o exemplo real foi uma pilha Python/FastAPI + pgvector, mas as armadilhas (sockets do Docker Desktop, bloqueios de rede, inicialização automática, codificação do PowerShell) afetam qualquer projeto Dockerizado no Windows.

Primeiro, oriente-se antes de agir

Verificações rápidas que decidem qual arquivo de referência você precisa:

• O Docker está funcionando? docker version (cliente + servidor), docker compose ps. Um erro do servidor geralmente significa que o Docker Desktop travou na inicialização → crash-recovery.md.
• Backend WSL2 saudável? wsl -l -v — a distribuição (ex.: docker-desktop) deve estar como Running.
• Rede na China continental? Se downloads/pulls expiram ou falham em TLS, assuma que a rede está bloqueando e vá para china-network.md antes de perder tempo com repetições.
• Precisa sobreviver a reinicializações sem ninguém monitorando? Isso é uma cadeia, não uma única configuração → unattended-operation.md.

Sintoma → referência

O que você vê	Leia
Docker Desktop não inicia, entra em loop de falha ou registra 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 falhando durante um build; wsl --install pausa; winget 0x8a15000f; HuggingFace/modelo baixado 302 para um host bloqueado	references/china-network.md
Deve ser executado após reinicialização sem nenhum humano (login automático, inicialização automática, tela de bloqueio, política de reinicialização), ou "funcionou quando eu estava logado, mas não na inicialização"	references/unattended-operation.md
Um .ps1 bagunça caracteres não ASCII, morre com Missing closing '}', elimina o próprio processo, ou cada comando nativo imprime texto vermelho assustador	references/windows-scripting.md
Implantar em uma nova máquina Windows, restaurar um volume de banco de dados, ou "eu editei o código, mas o contêiner não mudou"	references/deploy-workflow.md

Princípios generalizáveis (leia mesmo que não abra uma referência)

1. A pior falha do Docker Desktop no Windows é um socket AF_UNIX órfão, não um erro de configuração. Uma parada forçada (travamento/forçar saída/queda de energia) deixa arquivos de socket de ponto de remapeamento indeletáveis em %LOCALAPPDATA%\Docker\run\ e %LOCALAPPDATA%\docker-secrets-engine\. O Docker tenta removê-los e recriá-los na próxima inicialização e entra em loop de falha. Você não pode deletá-los (Remove-Item/.NET Delete ambos falham) — mas você pode renomear o diretório pai (uma operação de metadados que contorna o erro de acesso). Renomeie para outro lugar e o Docker recria tudo limpo. Ativar/desativar EnableInference/EnableDockerAI não resolve. Veja crash-recovery.md.

2. Em uma rede na China continental, recorra primeiro a espelhos, depois a fontes diretas. Docker Hub, winget, wsl --install online, deb.debian.org e pesos grandes do HuggingFace são bloqueados ou instáveis. Espelhos de registro, Tsinghua pip/apt, um MSI WSL offline e ModelScope para pesos de modelos são os caminhos confiáveis. desktop.docker.com e lançamentos do GitHub conectam diretamente. Veja china-network.md.

3. No login automático do Windows, entradas HKCU\...\Run de inicialização automática NÃO disparam silenciosamente. Use uma tarefa do Agendador de Tarefas acionada Ao Fazer Logon. Esta é a maior armadilha em configurações desassistidas. Veja unattended-operation.md.

4. Escreva arquivos .ps1 apenas com ASCII. O PowerShell 5.1 lê um arquivo UTF-8 sem BOM como GBK; qualquer caractere não ASCII (ex.: comentários em chinês) corrompe a correspondência de chaves → Missing closing '}' → o script morre instantaneamente sem deixar log. Mantenha os scripts ASCII puros; registre logs em inglês. Veja windows-scripting.md.

5. Código montado = reiniciar, não reconstruir. Se docker-compose.yml monta a origem por bind (./:/app), uma edição de código entra em vigor com docker compose restart <svc> — sem reconstruir imagem. Reconstrua apenas quando dependências ou o Dockerfile mudarem. Verifique mudanças de lógica com um teste descartável docker compose exec <svc> python … antes de deixar o agendamento real disparar, para nunca testar enviando para um canal ao vivo. Veja deploy-workflow.md.

6. Respeite restrições de escritor único. Se o aplicativo envia para um canal externo agendado, apenas uma máquina pode executar o agendador por vez — duas cópias = envios duplicados. Derribe a antiga (docker compose down) antes de iniciar a nova.

7. Claude não pode obter elevação administrativa silenciosamente. Qualquer mudança no sistema que precise de elevação deve ser confirmada pelo humano em um prompt UAC (Start-Process -Verb RunAs o aciona). Marque tais etapas claramente como "需手动操作 / etapa manual" — o operador aqui fala chinês e tem pouca infraestrutura, valorizando orientação passo a passo com os momentos práticos destacados. Modos de permissão automática também bloqueiam ExecutionPolicy Bypass + elevation, então não tente contornar o prompt.

Como estender esta skill

Quando uma nova falha não óbvia do Windows/Docker for resolvida, adicione-a ao arquivo de referência correspondente (sintoma → causa raiz → a correção exata que funcionou, e o que não funcionou). A linha "o que não funcionou" geralmente é a parte mais valiosa — impede que a próxima pessoa refaça tentativas frustradas.