docker

Docker

使用此技能可确保在 Linux、macOS 和 Windows Docker Desktop 主机上，Docker 操作具有确定性、安全且快速。

快速入门

1. 首先运行 scripts/probe-docker.ps1（Windows）或 docker info / docker version（Linux/macOS），了解实际环境。
2. 选择能够解决请求的最简工作流：
   • 本文件中的核心容器／构建／Compose 工作流可覆盖约 80% 的任务。
   • 只有在需要深入了解特定领域时才加载参考文件。
   • 编写样板代码前，优先复用 assets/templates/ 中的入门模板。
3. 默认先进行只读诊断，再提出会修改状态的命令。
4. 执行破坏性命令（rm、prune、down -v、sandbox reset、删除 builder／缓存）前，先确认。
5. 文档与运行时行为不一致时，优先遵循已安装 CLI 的实际行为；注明具体版本及相关情况。

意图路由器（渐进式披露）

仅加载当前请求所需的参考文件。

• resources/install-and-setup.md — 安装 Docker Desktop（macOS/Windows）或 Docker Engine（Linux），以及安装后的配置。
• resources/core.md — 以 Windows Desktop 为先的诊断、上下文管理、Desktop 状态。
• resources/containers.md — run/exec/logs/inspect/debug/stats 和崩溃排查。
• resources/images.md — Dockerfile 编写、多阶段模式、Buildx/Bake。
• resources/compose.md — Compose 编写和服务编排。
• resources/networking.md — bridge/overlay/macvlan、DNS、端口发布。
• resources/volumes.md — 命名卷、绑定挂载、备份／恢复模式。
• resources/registry.md — 登录／标记／推送／拉取和镜像仓库卫生。
• resources/swarm.md — swarm 初始化、服务、堆栈、安全操作。
• resources/troubleshooting.md — 系统化调试和错误分类。
• resources/security.md — Scout、SBOM、DHI、传递密钥、供应链检查。
• resources/ai-and-agents.md — Docker AI、agent/cagent、MCP 工具包、模型运行器、沙盒。
• resources/cloud-and-remote.md — Offload、Build Cloud、远程构建器和上下文。

快速命令参考

这些命令涵盖日常 Docker 使用的约 80%。无需加载参考文件即可直接使用。

# Container lifecycle
docker run -d --name myapp -p 8080:80 nginx          # Run detached with port mapping
docker run -it --rm ubuntu bash                       # Interactive, auto-remove on exit
docker ps                                             # List running containers
docker ps -a                                          # All containers (incl. stopped)
docker stop myapp && docker rm myapp                  # Stop and remove
docker logs myapp -f                                  # Follow logs
docker logs myapp --tail=100                          # Last 100 lines
docker exec -it myapp bash                            # Shell into running container
docker inspect myapp                                  # Full metadata (JSON)
docker stats                                          # Live resource usage

# Images
docker build -t myapp:latest .                        # Build from Dockerfile in cwd
docker pull nginx:alpine                              # Pull image
docker images                                         # List local images
docker rmi myapp:latest                               # Remove image
docker tag myapp:latest myregistry/myapp:v1.2         # Tag for push

# Compose (v2 — no hyphen)
docker compose config                                 # Validate and view merged config
docker compose up -d                                  # Start all services detached
docker compose down                                   # Stop and remove containers+networks
docker compose logs -f api                            # Follow logs for one service
docker compose exec api sh                            # Shell into service container
docker compose ps                                     # Service status
docker compose build --no-cache                       # Rebuild all images

# Buildx / multi-platform
docker buildx ls
docker buildx build --platform linux/amd64,linux/arm64 -t myorg/myapp:v1 --push .

# System
docker system df                                      # Disk usage breakdown
docker system prune                                   # Remove unused objects (see safety)

安全矩阵

命令或模式	必要的防护措施
docker system prune / prune -a	先运行 docker system df；总结将要删除的内容，然后确认。
docker volume rm	警告卷数据将被永久删除，并要求明确确认。
docker network rm	先检查是否有容器连接到该网络，并在删除前列出受影响的服务。
docker rm -f	确认具体容器名称；避免未列出目标就批量强制删除。
docker rmi -f	先检查依赖的容器／镜像，并确认影响。
docker swarm leave --force	说明对 manager 的影响，并要求明确确认。
docker compose down -v	指出数据库／状态丢失风险，并要求明确确认。
docker sandbox reset	视为破坏性重置；要求明确确认。
向镜像仓库执行 docker push	推送前确认完整的目标标签。
--privileged 标志	使用前说明该标志授予的权限及其风险。

编写 Dockerfile

编写 Dockerfile 时，始终默认遵循以下最佳实践：

• 层顺序 — 将变化最少的内容放在顶部（基础镜像、系统依赖），将变化最多的内容放在底部（应用代码）。最大限度地复用缓存。
• 多阶段构建 — 在构建阶段编译或安装；仅将构建产物复制到精简的运行时镜像中。
• 非 root 用户 — 在 CMD 之前创建并切换到非 root 用户。
• 精简的基础镜像 — 优先选择 alpine、distroless 或 slim。仅在需要系统软件包时使用完整镜像。
• 合并 RUN 命令 — 使用 && 串联相关命令；在同一层中清理软件包缓存。
• 始终同时创建 .dockerignore。

完整的 Dockerfile 模板（Node.js、Python、Go）和 .dockerignore 模式请参见 resources/images.md。

编写 Docker Compose 文件

Compose 文件的关键模式：

• 如果依赖项有健康检查，则在 depends_on 中使用 condition: service_healthy。
• 对于需要保留的数据，始终定义命名卷，而不要使用未命名的绑定挂载。
• 服务不需要外部访问时，将其限定在仅供内部使用的网络中。
• 生产环境使用 restart: unless-stopped；开发工具容器则省略。
• 在顶部显式设置 name:，以避免目录名称冲突。

包含健康检查的完整 Compose 文件模板请参见 resources/compose.md。

诊断工作流

容器崩溃或运行异常时：

docker ps -a                              # Find container and exit code
docker logs <name> --tail=100             # Last 100 lines (stderr included with 2>&1)
docker inspect <name>                     # Full JSON — check State, Config, Mounts
docker stats --no-stream                  # Snapshot of memory/CPU (check for OOM)
docker exec -it <name> sh                 # Shell in (if still running)
docker debug <name>                       # Debug sidecar, works on stopped containers
docker compose ps && docker compose logs --tail=50   # Compose: all services at once

退出代码：0 = 正常退出，1 = 应用错误，137 = 因 OOM 被终止，139 = 段错误，143 = SIGTERM，125/126/127 = Docker/exec 错误。

核心工作流（Windows 桌面端）

1. 建立基线 — 运行 scripts/probe-docker.ps1 -Json 获取结构化诊断信息（CLI 版本、上下文、插件可用性、守护进程可达性）。
2. 先诊断，再更改状态 — 运行 scripts/doctor-docker.ps1 执行可操作的检查。使用 -Quick 快速分诊；仅在适用时使用 -IncludeScout / -IncludeOffload。
3. 执行限定范围的操作 — 容器生命周期、构建流水线、Compose 编排、上下文/桌面端检查。
4. 按根本原因报告发现 — 沙盒/主机权限边界、守护进程/服务状态、配置不匹配。

资源索引

• scripts/probe-docker.ps1 — probe-docker.ps1 [-Json] [-IncludeExperimental] — 只读的主机/运行时探测。
• scripts/doctor-docker.ps1 — doctor-docker.ps1 [-Quick] [-IncludeOffload] [-IncludeScout] — 诊断与建议。
• assets/templates/ — 可复用的入门模板包，包含精简服务、Compose 堆栈和多架构 Buildx。
• resources/*.md — 深入的领域说明（参见上文的 Intent Router）。