docker

此技能是 Docker 参考资料集的路由外壳。

不可妥协的规则：

1. 首先阅读 references/stack.md，以确定项目的基础镜像、镜像仓库和构建约定。
2. 然后只加载实际任务所需的参考资料。
3. 默认采用多阶段构建 — 分离依赖安装、构建和生产阶段。
4. 生产环境使用非 root 用户 — 容器绝不能以 root 身份运行。添加用户并设置 USER 指令。
5. 镜像中不得包含机密信息 — 不得将密码放入 ARG/ENV，不得 COPY .env，不得在构建层中包含机密信息。
6. 固定基础镜像版本 — 使用 node:22-slim，而不是 node:latest。关键镜像应使用摘要固定版本。
7. 必须提供 .dockerignore — 排除 node_modules、.git、.env、dist 和测试产物。
8. 构建时使用冻结的锁文件 — 使用 --frozen-lockfile / --ci 进行可复现安装。

docker

输入

• $request：Docker 任务 — Dockerfile、Compose、镜像仓库、优化或调试目标

目标

通过经过验证的容器模式处理 Docker 相关工作，确保镜像体积小、安全、可复现，并遵循项目的基础设施约定。

步骤 0：阅读技术栈规范

始终从以下文件开始：

• references/stack.md

该文件明确了：基础镜像、镜像仓库、构建工具（Docker/BuildKit/Podman）、CI 集成和固定约定。

成功标准：编写任何 Dockerfile 或 Compose 配置之前，必须明确项目的容器基础设施选择。

步骤 1：仅加载相关参考资料

使用路由表选择参考文件。不要一次性加载整个参考资料目录树。

任务	阅读
基础镜像、镜像仓库、构建约定、CI	references/stack.md
编写或编辑 Dockerfile	references/dockerfile.md
多阶段构建、层优化、缓存	references/multi-stage.md
docker-compose 服务、网络、卷	references/compose.md
.dockerignore、构建上下文优化	references/build-context.md
健康检查、就绪状态、启动探针	references/health-checks.md
安全：非 root、只读文件系统、功能、扫描	references/security.md
镜像体积优化、distroless、slim、alpine	references/image-optimization.md
镜像仓库：推送、拉取、标记、ECR/GCR/GHCR/DockerHub	references/registry.md
BuildKit 功能、缓存挂载、机密挂载	references/buildkit.md
CI/CD：GitHub Actions、GitLab CI、构建与推送流水线	references/ci-cd.md
调试：日志、exec、inspect、网络问题	references/debugging.md
特定语言：Node.js、Python、Go、Rust、Java	references/language-patterns.md
卷、绑定挂载、tmpfs、命名卷	references/volumes.md
网络：bridge、host、overlay、DNS、端口映射	references/networking.md

涉及多项任务？阅读多个文件。参考资料各自独立完整。

成功标准：仅采用与任务相关的 Docker 约定。

步骤 2：按核心 Docker 防护规则实施

始终遵循以下规则：

• 多阶段构建：依赖 → 构建 → 生产
• .dockerignore 排除构建上下文中的所有非必要内容
• 固定基础镜像标签 — 生产环境绝不使用 :latest
• 最终阶段设置非 root USER
• 每个阶段只 COPY 所需内容 — 不要复制整个代码库
• 为每个长期运行的服务添加健康检查
• ARG、ENV 或 COPY 中不得包含机密信息 — 使用 BuildKit --mount=type=secret
• 合并 RUN 命令以减少层数 — 同时保持可读性
• 按变更频率从低到高排列各层（先依赖，后代码）

成功标准：容器体积小、安全、可复现，并遵循项目约定。

第 3 步：验证构建

使用最相关且范围最窄的验证方式：

• docker build 成功
• 镜像大小符合该语言／框架的合理范围
• 容器启动，健康检查通过
• .dockerignore 排除的文件正确（使用 docker build --dry-run 或检查构建上下文大小）
• docker history 或 docker inspect 中没有可见的密钥

成功标准：镜像构建成功、能够运行，并通过基本健康验证。

防护措施

• 不要将整本 Docker 手册内联到 SKILL.md 中。
• 不要跳过 references/stack.md。
• 生产环境的 Dockerfile 中，基础镜像不要使用 latest 标签。
• 没有正确的 .dockerignore 时，不要使用 COPY . .。
• 不要以 root 身份运行容器。
• 不要将密钥放在构建参数中，也不要放在烘焙进镜像的环境变量中。
• 不要添加 disable-model-invocation；这是一个常规领域技能。

何时加载参考资料

• references/stack.md 始终加载。

• 然后只加载 references/ 下与任务相关的文件

输出约定

报告：

1. 加载了哪些 Docker 参考资料
2. 选择的构建模式（多阶段、单阶段等）
3. 所做的更改
4. 运行的验证（构建是否成功、镜像大小、健康检查）