docker-project-foundations

Docker 项目基础

概述

此技能将指导你从零开始将项目容器化。它重点介绍如何创建初始 Docker 文件集、选择合理的布局，以及优先使用容器化依赖项，而非在主机级别安装依赖项。

何时使用此技能

在以下情况下启用此技能：

• 用户要求你设置、初始化或将项目容器化
• 项目需要初始的 Dockerfile、compose.yaml 或 .dockerignore，但目前尚未提供
• 用户想为项目添加服务依赖项（数据库、缓存、消息队列）
• 用户询问如何在本地运行或开发项目，且可以使用 Docker

何时不使用此技能

在以下情况下不要使用此技能：

• 用户明确表示不想使用 Docker
• 项目已有成熟的 Docker 配置，只需进行少量修改
• 主要任务是优化现有的 Dockerfile
• 主要任务是编辑或调试现有的 Compose 配置栈

核心指南

始终创建这三个文件

将项目容器化时，始终创建以下三个文件：

1. .dockerignore — 首先创建此文件，以确保初始构建上下文足够小且安全。请参阅 assets/dockerignore-example 作为参考。
2. Dockerfile — 创建一个可用的基础镜像定义，以便项目可以构建和运行。请参阅 assets/Dockerfile.simple。
3. compose.yaml — 创建一个本地开发配置栈，其中包含应用服务及其所需的依赖项。请参阅 assets/compose-dev.yaml。

npm 注册表凭据

• 在 .dockerignore 中使用 **/.npmrc 排除所有层级的 .npmrc；否则，宽泛的源码复制可能会将凭据留存在镜像层中。
• Node.js 基础配置会将 npmrc 挂载为 BuildKit 密钥，供两处 npm ci 步骤使用。构建公共包时无需密钥。对于私有注册表，请显式传入配置：

  DOCKER_BUILDKIT=1 docker build --secret id=npmrc,src="$HOME/.npmrc" .
  

  如果项目将配置文件存放在其他位置，请使用实际配置路径。切勿复制凭据文件，也不要通过 ARG 或 ENV 传递其值。安装过程中运行的依赖脚本可以访问已挂载的密钥；请使用可信赖的依赖项和遵循最小权限原则的注册表令牌。
• 通过 Compose 构建私有注册表镜像时，可将以下可选覆盖配置作为 compose.npm.yaml，放在基础配置的 compose.yaml 旁边：

  services:
    app:
      build:
        secrets:
          - npmrc
  secrets:
    npmrc:
      file: ${NPMRC_PATH:?Set NPMRC_PATH to your npm config file}
  

  使用 NPMRC_PATH="$HOME/.npmrc" docker compose -f compose.yaml -f compose.npm.yaml build 进行构建。这只授予构建时访问权限，不会提供运行时密钥。构建公共包时应省略此覆盖配置，以免要求提供凭据文件。

优先使用容器化依赖项，而非在主机上安装

当项目需要数据库（Postgres、MySQL、MongoDB）、缓存（Redis、Memcached）、队列（RabbitMQ、Kafka）或其他基础设施服务时：

• 始终在 compose.yaml 中将其定义为服务，而不是让用户在主机上安装。
• 开发依赖项绝不要建议使用 brew install postgres、apt install redis 或类似命令在主机上安装。
• 对这些服务使用来自 Docker Hub 的官方 Docker 镜像。
• 使用环境变量配置服务，而不要将配置文件烘焙进镜像中。

Bootstrap 清单

• 将文件命名为 compose.yaml，不要使用旧版 Compose 文件名。
• 除非明确的多服务布局需要使用 docker/ 子目录，否则将这三个文件都放在项目根目录。
• 确保初始设置可通过一条命令在本地构建并启动。
• 默认将已发布的应用端口绑定到回环地址。只有在其他设备必须访问开发服务时，才扩大主机地址范围。
• 将未经过身份验证的数据存储保留在 Compose 网络中，不要发布其端口。如果本地主机工具需要访问数据库，仅发布到回环地址。
• 如果开发专用的凭据回退方案可实现一条命令启动，请明确标注，并记录 .env 覆盖方式。
• 使用 Compose 服务运行本地数据库、缓存和队列，而不是安装在主机上。
• 保持初始脚手架简单；将详细的镜像优化和高级 Compose 调优留给相应技能处理。

开发与生产

• 开发：使用绑定挂载实现热重载，默认将应用端口发布到回环地址，并启用详细日志。将未经过身份验证的数据存储保留在 Compose 网络中；只有在本地主机工具需要访问时，才将数据存储端口发布到回环地址。
• 生产：使用多阶段构建，仅复制已构建的产物，不要挂载源代码，尽量减少镜像层数，并设置适当的资源限制。
• 尽可能使用一个 Dockerfile，通过构建阶段和构建参数同时支持两种场景。

文件位置

• 将 Dockerfile 放在项目根目录（如果项目包含多个服务，则放在 docker/ 子目录中）。
• 将 compose.yaml 放在项目根目录。
• 将 .dockerignore 放在项目根目录，与 Dockerfile 放在一起。

相关技能

• 如需 Dockerfile 优化、缓存策略、非 root 用户执行和镜像加固，请使用 docker-build-strategies。
• 如需服务依赖、健康检查、覆盖配置、卷、网络和 Compose 调试，请使用 docker-compose-patterns。
• 如需处理有破坏性的 Docker CLI 命令（docker system prune、docker rm -f、镜像／网络／构建器清理），以及跨产品的破坏性命令防护措施索引，请使用 docker-destructive-guardrails。

参考资料

• references/project-structure.md — 关于 Docker 项目文件组织、命名约定和多服务布局的详细指南。

资源

• assets/dockerignore-example — 适用于典型项目的完整 .dockerignore。
• assets/compose-dev.yaml — 包含 Docker 化依赖项的开发用 Compose 文件。
• assets/Dockerfile.simple — 遵循最佳实践的基础多阶段 Dockerfile。

脚本

• scripts/verify-setup.sh — 检查当前目录中是否存在必需文件，并验证其中的 compose.yaml。请从项目根目录运行，并将脚本路径解析到此技能目录下：

  bash "<skill-dir>/scripts/verify-setup.sh" [--help]
  

  将 <skill-dir> 替换为包含此 SKILL.md 的文件夹的绝对路径；scripts/ 路径相对于该文件夹，而非项目目录。请勿先切换到技能目录：脚本会检查当前目录。如果无法解析技能目录，请检查 .dockerignore、Dockerfile 和 compose.yaml 是否存在于项目根目录，然后运行 docker compose config --quiet。验证成功或请求帮助时，退出状态为 0；缺少必需文件或 Compose 配置无效时为 1；参数无效时为 2。

检查

• checks/verification.md — 供人工审查使用的详细验证清单。