docker.mdc

---
description: 编写高效、安全的 Dockerfile 的最佳实践
globs: "**/Dockerfile"
---

# Dockerfile 最佳实践

## 基础镜像
- 使用官方、经过验证的基础镜像
- 选择最小化的基础镜像（如 `alpine`, `slim`, `distroless`）以减小体积和攻击面
- 固定基础镜像的版本（e.g., `node:18-alpine` 而不是 `node:latest`）

## 构建缓存
- 优化指令顺序以利用 Docker 的层缓存
- 将不经常变化的指令（如安装系统依赖）放在前面
- 将经常变化的指令（如复制源代码）放在后面
- 例如，先复制 `package.json` 并安装依赖，再复制整个应用代码

## 多阶段构建 (Multi-stage Builds)
- 使用多阶段构建来分离构建环境和生产环境
- 最终镜像只包含运行应用所需的最小文件，不包含编译器、开发工具或中间产物
- 这能显著减小镜像体积并提高安全性

## 安全性
- 不要以 `root` 用户运行容器。使用 `USER` 指令切换到非 root 用户
- 使用 `.dockerignore` 文件排除不必要的文件和目录（如 `.git`, `node_modules`, `secrets`）
- 不要将敏感信息（密码、API 密钥）硬编码到 Dockerfile 中，使用构建时参数（`ARG`）、环境变量（`ENV`）或 Docker secrets
- 定期扫描镜像以查找漏洞（使用 `docker scan` 或第三方工具如 Trivy, Snyk）

## 镜像体积
- 将多个 `RUN` 指令合并为一个，以减少镜像层数（e.g., `RUN apt-get update && apt-get install -y ...`）
- 在安装包后清理缓存（e.g., `rm -rf /var/lib/apt/lists/*`）
- 了解 `COPY` 和 `ADD` 的区别，优先使用 `COPY`

## 指令使用
- 使用 `CMD` 提供容器的默认执行命令
- 使用 `ENTRYPOINT` 配置容器为可执行文件
- 结合使用 `ENTRYPOINT` 和 `CMD` 来创建灵活的启动命令
- 使用 `HEALTHCHECK` 指令来检查容器是否仍在正常工作