rxdage/claude-skills

Docker en Windows: desplegar, ejecutar y reparar

Esta habilidad es conocimiento operativo obtenido con esfuerzo al llevar una aplicación Docker Compose hasta producción desatendida y resistente a reinicios en un escritorio Windows 11 detrás de una red de China continental. Las fallas a continuación parecen crípticas y las soluciones son contraintuitivas, por eso están escritas. Prefiere estas sobre adivinar; cada una costó tiempo real de depuración.

Nada aquí es específico de una aplicación: el ejemplo en ejecución era una pila Python/FastAPI + pgvector, pero las trampas (sockets de Docker Desktop, bloqueos de red, arranque automático, codificación de PowerShell) afectan a cualquier proyecto Dockerizado en Windows.

Primero, orientarse antes de actuar

Verificaciones rápidas que deciden qué archivo de referencia necesitas:

• ¿Está Docker funcionando? docker version (cliente+servidor), docker compose ps. Un error del servidor generalmente significa que Docker Desktop falló al iniciar → crash-recovery.md.
• ¿El backend WSL2 está saludable? wsl -l -v: la distribución (ej. docker-desktop) debería estar Running.
• ¿Red de China continental? Si las descargas expiran o fallan TLS, asume que la red está bloqueando y ve a china-network.md antes de perder tiempo con reintentos.
• ¿Debe sobrevivir a reinicios sin nadie mirando? Eso es una cadena completa, no una sola configuración → unattended-operation.md.

Síntoma → referencia

Lo que ves	Lee
Docker Desktop no arranca, entra en bucle de bloqueos, o 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 fallando en una compilación; wsl --install se cuelga; winget 0x8a15000f; HuggingFace/descarga de modelo 302 a un host bloqueado	references/china-network.md
Debe ejecutarse después del reinicio sin humano (auto-login, arranque automático, pantalla de bloqueo, política de reinicio), o "funcionó cuando estaba autenticado pero no al iniciar"	references/unattended-operation.md
Un .ps1 distorsiona caracteres no ASCII, falla con Missing closing '}', mata su propio proceso, o cada comando nativo imprime texto rojo aterrador	references/windows-scripting.md
Desplegar en una nueva máquina Windows, restaurar un volumen de base de datos, o "Edité el código pero el contenedor no cambió"	references/deploy-workflow.md

Principios que generalizan (ojéalos incluso si no abres una referencia)

1. La peor falla de Docker Desktop en Windows es un socket AF_UNIX huérfano, no un error de configuración. Una detención forzada (bloqueo/cierre forzado/pérdida de energía) deja archivos de socket de punto de reparseo no eliminables bajo %LOCALAPPDATA%\Docker\run\ y %LOCALAPPDATA%\docker-secrets-engine\. Docker intenta eliminarlos y recrearlos en el siguiente inicio y entra en bucle de bloqueos. No puedes eliminarlos (Remove-Item/.NET Delete fallan), pero puedes renombrar el directorio padre (una operación de metadatos que evita el error de acceso). Renómbralo, Docker reconstruye limpio. Alternar EnableInference/EnableDockerAI no lo soluciona. Ver crash-recovery.md.

2. En una red de China continental, recurre primero a espejos, después a directo. Docker Hub, winget, wsl --install en línea, deb.debian.org y pesos grandes de HuggingFace están bloqueados o son inestables. Los espejos de registro, Tsinghua pip/apt, un MSI de WSL sin conexión y ModelScope para pesos de modelos son las rutas confiables. desktop.docker.com y los lanzamientos de GitHub sí conectan directo. Ver china-network.md.

3. Bajo auto-login de Windows, las entradas de arranque automático HKCU\...\Run NO se ejecutan silenciosamente. Usa una tarea del Programador de tareas activada Al iniciar sesión. Este es el mayor problema oculto en configuraciones desatendidas. Ver unattended-operation.md.

4. Escribe archivos .ps1 solo con ASCII. PowerShell 5.1 lee un archivo UTF-8 sin BOM como GBK; cualquier carácter no ASCII (ej. comentarios en chino) corrompe el coincidencia de llaves → Missing closing '}' → el script muere instantáneamente sin dejar registro. Mantén los scripts ASCII puro; registra en inglés. Ver windows-scripting.md.

5. Código montado = reinicio, no reconstrucción. Si docker-compose.yml monta el código fuente (./:/app), un cambio de código surte efecto con docker compose restart <svc> — sin reconstruir la imagen. Solo reconstruye cuando cambien dependencias/Dockerfile. Verifica los cambios de lógica con una prueba rápida docker compose exec <svc> python … antes de dejar que el cronograma real se ejecute, para nunca probar saturando un canal de salida en vivo. Ver deploy-workflow.md.

6. Respeta las restricciones de escritor único. Si la aplicación envía a un canal externo en un cronograma, solo una máquina puede ejecutar el programador a la vez; dos copias = envíos duplicados. Detén la anterior (docker compose down) antes de iniciar la nueva.

7. Claude no puede obtener permisos de administrador silenciosamente. Cualquier cambio del sistema que requiera elevación debe ser confirmado por el humano en un aviso de UAC (Start-Process -Verb RunAs lo activa). Marca esos pasos claramente como "需手动操作 / paso manual" — el operador aquí es hablante de chino y con poca infraestructura, y valora la guía paso a paso con los momentos prácticos señalados. Los modos de permiso automático también bloquean ExecutionPolicy Bypass + elevation, así que no rodees el aviso.

Cómo extender esta habilidad

Cuando se resuelva una nueva falla no obvia de Windows/Docker, agrégala al archivo de referencia correspondiente (síntoma → causa raíz → la solución exacta que funcionó, y lo que no funcionó). La línea de "lo que no funcionó" suele ser la parte más valiosa: evita que la próxima persona vuelva a intentar caminos sin salida.