dockerfile-generator

Dockerfile 生成器

概述

此技能提供一套完整的工作流，用于生成可用于生产环境的 Dockerfile，内置安全性、优化和最佳实践。可生成多阶段构建、安全强化配置和优化的层结构，并自动验证和迭代修复错误。

主要功能：

• 多阶段构建，优化镜像大小（减少 50%–85%）
• 强化安全性（非 root 用户、精简基础镜像、不包含机密信息）
• 优化层缓存，加快构建速度
• 特定语言的模板（Node.js、Python、Go、Java）
• 自动生成 .dockerignore
• 集成 dockerfile-validator 进行验证
• 迭代验证并修复错误（如发现错误，至少迭代 1 次）
• 优先使用本地参考资料；针对框架特定模式，必要时再查询文档

何时使用此技能

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

• 从头创建 Dockerfile
• 将应用容器化（Node.js、Python、Go、Java 或其他语言）
• 实施多阶段构建以优化大小
• 将现有 Dockerfile 转换为符合最佳实践的版本
• 生成可用于生产环境的容器配置
• 优化 Docker 构建的安全性和性能
• 用户要求“创建”“生成”“构建”或“编写”Dockerfile
• 为微服务实施容器化
• 设置 CI/CD 流水线的容器构建

触发短语

请求中出现以下表述时，立即使用此技能：

• “为我的应用生成一个生产环境 Dockerfile”
• “为 <language/framework> 创建一个多阶段 Dockerfile”
• “采用安全最佳实践将此服务容器化”
• “优化此 Dockerfile，以减小体积并加快构建速度”
• “编写用于部署的 Dockerfile 和 .dockerignore”

不要将此技能用于

• 验证现有 Dockerfile（改用 dockerfile-validator）
• 构建或运行容器（使用 docker build/run 命令）
• 调试正在运行的容器（使用 docker logs、docker exec）
• 管理 Docker 镜像或注册表

确定性执行模型

按顺序执行以下阶段，除非在最终输出中说明跳过原因，否则不得跳过任何阶段。

1. 收集需求（语言、运行时版本、入口点、公开端口、包管理器、健康检查端点）。
2. 加载参考资料（优先使用本地参考文件；仅在本地参考资料不足时查阅外部文档）。
3. 生成 Dockerfile 和 .dockerignore。
4. 使用 dockerfile-validator 或备用本地工具进行验证。
5. 迭代修复，直至满足停止条件。
6. 发布最终产物以及验证/审计报告。

阶段 5 的停止条件：

• 验证错误为零，且没有未经批准的警告时停止。
• 最多迭代 3 次，之后针对尚未解决的问题生成有意偏离报告。

参考路径索引

根据需要直接通过路径查阅以下文件：

• references/security_best_practices.md：非 root 用户、机密信息处理、基础镜像强化、漏洞扫描。
• references/optimization_patterns.md：多阶段策略、缓存优化、减少层数、BuildKit 缓存挂载。
• references/language_specific_guides.md：语言/框架运行时和包管理器模式。
• references/multistage_builds.md：高级阶段拆分和产物复制模式。

Dockerfile 生成工作流

生成 Dockerfile 时遵循此工作流，并根据用户需求进行调整：

阶段 1：收集需求

目标： 了解需要容器化的内容，并收集所有必要信息。

需要收集的信息：

1. 应用详情：

   • 编程语言和版本（Node.js 18/20、Python 3.11/3.12、Go 1.21+、Java 17/21 等）
   • 应用类型（Web 服务、API、CLI 工具、批处理作业等）
   • 框架（Express、FastAPI、Spring Boot 等）
   • 入口点（主文件、运行命令）

2. 依赖项：

   • 包管理器（npm/yarn/pnpm、pip/poetry、go mod、maven/gradle）
   • 系统依赖项（构建工具、库等）
   • 构建时依赖项与运行时依赖项

3. 应用配置：

   • 要公开的端口
   • 所需的环境变量
   • 配置文件
   • 健康检查端点（用于 Web 服务）
   • 卷挂载（如有）

4. 构建要求：

   • 构建命令
   • 测试命令（可选）
   • 编译需求（适用于编译型语言）
   • 静态资源生成

5. 生产环境要求：

   • 预期的镜像大小限制
   • 安全要求
   • 扩展需求
   • 资源限制（CPU、内存）

如果信息缺失或不清楚，请使用 AskUserQuestion。

示例问题：

- What programming language and version is your application using?
- What is the main entry point to run your application?
- Does your application expose any ports? If so, which ones?
- Do you need any system dependencies beyond the base language runtime?
- Does your application need a health check endpoint?

阶段 2：框架/库文档查询（如有需要）

目标： 调研特定框架的容器化模式和最佳实践。

执行此阶段的情况：

• 用户提及特定框架（Next.js、Django、FastAPI、Spring Boot 等）
• 应用有复杂的构建要求
• 需要特定框架的优化指导

调研流程（严格遵循回退链）：

1. 首先阅读本地参考资料（必需）：

   • references/security_best_practices.md
   • references/optimization_patterns.md
   • references/language_specific_guides.md

2. 本地参考资料不足时，使用 Context7 文档查询（优先选用的外部来源）：

   Use mcp__context7__resolve-library-id with the framework name
   Then use mcp__context7__query-docs with query:
   "docker deployment production build"
   

3. 仅当 Context7 不可用或缺少所需细节时，才使用 Web 搜索：

   "<framework>" "<version>" dockerfile production deployment best practices
   

4. 如果无法进行外部查询（离线/工具限制）：

   • 继续使用本地参考资料和此文件中的语言模板。
   • 在输出中明确说明假设。
   • 在最终报告中标明查询受限。

5. 仅提取可执行的信息：

   • 推荐的基础镜像及版本策略
   • 构建优化技巧
   • 所需的运行时环境变量
   • 生产环境与开发环境的差异
   • 框架特定的安全要求

阶段 3：生成 Dockerfile

目标： 遵循最佳实践，创建适用于生产环境的多阶段 Dockerfile。

核心原则：

1. 多阶段构建（编译型语言必须使用，所有语言建议使用）：

   • 将构建阶段与运行时阶段分开
   • 不将构建工具放入最终镜像
   • 仅复制必要的构建产物
   • 可使镜像缩小 50-85%

2. 强化安全性（必须）：

   • 使用明确的版本标签（绝不使用 :latest）
   • 以非 root 用户运行（创建专用用户）
   • 使用精简的基础镜像（alpine、distroless）
   • 不硬编码机密信息
   • 扫描基础镜像中的漏洞

3. 优化镜像层（必须）：

   • 按指令变更频率从低到高排序
   • 在应用代码之前复制依赖文件
   • 使用 && 合并相关的 RUN 命令
   • 在同一镜像层清理包管理器缓存
   • 有效利用构建缓存

4. 满足生产环境要求（必须）：

   • 为服务添加 HEALTHCHECK
   • 对 ENTRYPOINT/CMD 使用 exec 格式
   • 将 WORKDIR 设置为绝对路径
   • 使用 EXPOSE 说明公开的端口

特定语言的模板：

Node.js 多阶段 Dockerfile

构建阶段依赖规则： 如果应用有构建步骤（TypeScript、 Vite、Webpack 等），请在构建阶段安装所有依赖（省略 --only=production），并在构建后清理开发依赖。在构建步骤前使用 --only=production 会导致 npm run build 失败，因为未安装开发工具。

# syntax=docker/dockerfile:1

# Build stage — installs all deps so build tools (tsc, vite, etc.) are available,
# then prunes dev deps so the production stage only ships what is needed at runtime.
FROM node:20-alpine AS builder
WORKDIR /app

# Copy dependency files for caching
COPY package*.json ./
# Install ALL dependencies (including devDependencies required by the build step)
RUN npm ci && \
    npm cache clean --force

# Copy application code
COPY . .

# Build application and prune dev dependencies
RUN npm run build && \
    npm prune --production

# Production stage
FROM node:20-alpine AS production
WORKDIR /app

# Set production environment
ENV NODE_ENV=production

# Create non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# Copy pruned node_modules and built application from builder
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app .

# Switch to non-root user
USER nodejs

# Expose port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"

# Start application
CMD ["node", "index.js"]

简单应用（无构建步骤）： 如果不需要编译或打包，请在构建阶段仅安装 生产依赖，并从主机上下文复制源代码：

RUN npm ci --only=production && npm cache clean --force
...
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --chown=nodejs:nodejs . .

Python 多阶段 Dockerfile

# syntax=docker/dockerfile:1

# Build stage
FROM python:3.12-slim AS builder
WORKDIR /app

# Install build dependencies
# hadolint ignore=DL3008
RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Copy dependency files
COPY requirements.txt .

# Install Python dependencies
RUN pip install --no-cache-dir --user -r requirements.txt

# Production stage
FROM python:3.12-slim AS production
WORKDIR /app

# Create non-root user
RUN useradd -m -u 1001 appuser

# Copy dependencies from builder
COPY --from=builder /root/.local /home/appuser/.local

# Copy application code
COPY --chown=appuser:appuser . .

# Update PATH and set Python production env vars
# PYTHONUNBUFFERED=1 ensures stdout/stderr are flushed immediately (essential for container logs)
# PYTHONDONTWRITEBYTECODE=1 prevents writing .pyc files to disk
ENV PATH=/home/appuser/.local/bin:$PATH \
    PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1

# Switch to non-root user
USER appuser

# Expose port
EXPOSE 8000

# Health check (adjust endpoint as needed)
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health').read()" || exit 1

# Start application
CMD ["python", "app.py"]

Go 多阶段 Dockerfile

# syntax=docker/dockerfile:1

# Build stage
FROM golang:1.21-alpine AS builder
WORKDIR /app

# Copy go mod files
COPY go.mod go.sum ./
RUN go mod download

# Copy source code
COPY . .

# Build the application
RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" -o main .

# Production stage (using distroless for minimal image)
# gcr.io/distroless/static-debian12 IS a specific tag; hadolint DL3006 is a
# false positive for non-Docker-Hub registries.
# hadolint ignore=DL3006
FROM gcr.io/distroless/static-debian12 AS production
WORKDIR /

# Copy binary from builder
COPY --from=builder /app/main /main

# Expose port
EXPOSE 8080

# HEALTHCHECK is not supported in distroless images (no shell available)

# Switch to non-root user (distroless runs as nonroot by default)
USER nonroot:nonroot

# Start application
ENTRYPOINT ["/main"]

Java 多阶段 Dockerfile

# syntax=docker/dockerfile:1

# Build stage
FROM eclipse-temurin:21-jdk-jammy AS builder
WORKDIR /app

# Copy Maven wrapper and pom.xml
COPY mvnw pom.xml ./
COPY .mvn .mvn

# Download dependencies (cached layer)
RUN ./mvnw dependency:go-offline

# Copy source code
COPY src ./src

# Build application
RUN ./mvnw clean package -DskipTests && \
    mv target/*.jar target/app.jar

# Production stage (using JRE instead of JDK)
FROM eclipse-temurin:21-jre-jammy AS production
WORKDIR /app

# Install healthcheck dependency and create non-root user
# hadolint ignore=DL3008
RUN apt-get update && apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/* && \
    useradd -m -u 1001 appuser

# Copy JAR from builder
COPY --from=builder --chown=appuser:appuser /app/target/app.jar ./app.jar

# Switch to non-root user
USER appuser

# Expose port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
    CMD curl -f http://localhost:8080/actuator/health || exit 1

# Start application
ENTRYPOINT ["java", "-jar", "app.jar"]

选择逻辑：

• Node.js：用于 JavaScript/TypeScript 应用
• Python：用于 Python 应用（Web、API、脚本）
• Go：用于 Go 应用（非常适合构建精简镜像）
• Java：用于 Spring Boot、Quarkus 或其他 Java 框架
• 通用：为其他语言创建自定义 Dockerfile

始终包含：

1. 语法指令：# syntax=docker/dockerfile:1
2. 多阶段构建（构建阶段 + 生产阶段）
3. 创建并使用非 root 用户
4. 为服务添加 HEALTHCHECK（如适用）
5. 正确设置 WORKDIR
6. 为文档说明的端口添加 EXPOSE
7. 清理包管理器缓存
8. CMD/ENTRYPOINT 使用 exec 格式

第 4 阶段：生成 .dockerignore

目标： 创建完善的 .dockerignore，以缩小构建上下文并防止机密泄露。

生成 Dockerfile 时始终创建 .dockerignore。

标准 .dockerignore 模板：

# Git
.git
.gitignore
.gitattributes

# CI/CD
.github
.gitlab-ci.yml
.travis.yml
.circleci

# Documentation
README.md
CHANGELOG.md
CONTRIBUTING.md
LICENSE
*.md
docs/

# Docker
Dockerfile*
docker-compose*.yml
.dockerignore

# Environment
.env
.env.*
*.local

# Logs
logs/
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Dependencies (language-specific - add as needed)
node_modules/
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
venv/
.venv/
target/
*.class

# IDE
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store

# Testing
coverage/
.coverage
*.cover
.pytest_cache/
.tox/
test-results/

# Build artifacts
dist/
build/
*.egg-info/

根据语言自定义：

• Node.js：添加 node_modules/、npm-debug.log、yarn-error.log
• Python：添加 __pycache__/、*.pyc、.venv/、.pytest_cache/
• Go：添加 vendor/、*.exe、*.test
• Java：添加 target/、*.class、*.jar（最终构件除外）

第 5 阶段：使用 dockerfile-validator 验证

目标： 确保生成的 Dockerfile 遵循最佳实践，且不存在尚未解决的严重问题。

必须：生成后始终运行验证。

首选路径：

1. 调用 dockerfile-validator。
2. 按严重级别（error、warning、info）记录检查结果。
3. 优先处理安全性和可复现性问题。

备用路径（无法调用技能时）：

1. 直接尝试运行本地验证脚本：

   bash ../dockerfile-validator/scripts/dockerfile-validate.sh Dockerfile
   

2. 如果该路径不可用，直接运行可用的工具：

   hadolint Dockerfile
   checkov -f Dockerfile --framework dockerfile
   

3. 如果有一个或多个工具不可用，请继续生成，并在最终报告中逐一说明跳过的检查。

预期的验证阶段：

[1/4] Syntax Validation (hadolint)
[2/4] Security Scan (Checkov)
[3/4] Best Practices Validation
[4/4] Optimization Analysis

第 6 阶段：验证-迭代循环（明确要求）

目标： 执行确定性的修复循环，并记录可审计的迭代记录。

循环规则（必需）：

1. 至少运行一轮验证。
2. 如果存在任何 error，请应用修复并重新运行验证。
3. 持续迭代，直到：
   • 不再有 error，或
   • 迭代次数达到 3 次。
4. 对于 warning，请修复，或将其标记为有理由的有意偏差。
5. 绝不悄悄忽略检查结果。

迭代日志格式（必需）：

迭代	使用的命令/路径	错误	警告	已应用的修复	结果
1	dockerfile-validator 或备用命令	N	N	简短摘要	通过/失败
2	...	N	N	简短摘要	通过/失败
3	...	N	N	简短摘要	通过/失败

常见修复：

• 为基础镜像添加版本标签
• 在 CMD/ENTRYPOINT 前添加 USER 指令
• 为服务添加 HEALTHCHECK
• 在安全的情况下合并 RUN 命令
• 在同一层中清理包缓存
• 如果不需要归档文件/URL 处理行为，则将 ADD 替换为 COPY

第 7 阶段：最终审查和审计报告

**目标：**交付可运行的制品和可审计的报告。

交付内容（必需）：

1. 生成的文件：
   • Dockerfile（已验证并优化）
   • .dockerignore（内容全面）
2. 验证摘要：
   • 使用的工具路径（主要路径还是备用路径）
   • 按严重级别分类的问题
   • 循环结束后的最终状态
3. 第 6 阶段的迭代日志表。
4. 有意偏差报告（仅在适用时）。
5. 使用说明。
6. 优化指标和后续步骤。

有意偏差报告（存在未修复的问题时必需）：

ID	规则/检查	严重级别	决策	理由	风险	缓解措施	到期/复审日期
DEV-001	例如，DL3059	警告	接受	构建步骤可读性要求	轻微的层开销	重构后重新审查	YYYY-MM-DD

使用说明模板：

# Build image
docker build -t myapp:1.0 .

# Run container
docker run -p 3000:3000 myapp:1.0

# Probe health endpoint (if exposed)
curl http://localhost:3000/health

优化指标（必需）：

## Optimization Metrics

| Metric | Estimate |
|--------|----------|
| Image Size | ~150MB (vs ~500MB without multi-stage, 70% reduction) |
| Build Cache | Layer caching enabled for dependencies |
| Security | Non-root user, minimal base image, no secrets |

按语言划分的大小估算：

• Node.js：使用 Alpine 时约为 50-150MB（使用完整的 node 镜像时约为 1GB）
• Python：使用 slim 时约为 150-250MB（使用完整的 python 镜像时约为 900MB）
• Go：使用 distroless/scratch 时约为 5-20MB（使用完整的 golang 镜像时约为 800MB）
• Java：使用 JRE 时约为 200-350MB（使用 JDK 时约为 500MB 以上）

后续步骤（必需）：

## Next Steps

- [ ] Test the build locally: `docker build -t myapp:1.0 .`
- [ ] Run and verify the container works as expected
- [ ] Update CI/CD pipeline to use the new Dockerfile
- [ ] Consider BuildKit cache mounts for faster builds (see references/optimization_patterns.md)
- [ ] Set up automated vulnerability scanning with `docker scout` or `trivy`
- [ ] Push to registry and deploy

生成脚本（可选参考）

scripts/ 目录包含独立的 bash 脚本，可在此技能之外手动生成 Dockerfile：

• generate_nodejs.sh - 用于生成 Node.js Dockerfile 的 CLI 工具
• generate_python.sh - 用于生成 Python Dockerfile 的 CLI 工具
• generate_golang.sh - 用于生成 Go Dockerfile 的 CLI 工具
• generate_java.sh - 用于生成 Java Dockerfile 的 CLI 工具
• generate_dockerignore.sh - 用于生成 .dockerignore 的 CLI 工具

**用途：**这些脚本是参考实现和手动工具，供希望通过命令行生成 Dockerfile、而不使用技能调用的用户使用。它们展示了此技能中采用的相同最佳实践。

**使用此技能时：**Codex 会直接使用 SKILL.md 中记录的模板和模式生成 Dockerfile，而不是调用这些脚本。本文档中的模板是权威来源。

脚本用法示例：

# Manual Dockerfile generation
cd devops-skills-plugin/skills/dockerfile-generator/scripts
./generate_nodejs.sh --version 20 --port 3000 --output Dockerfile

Node/Python 入口点标志（脚本模式）：

标志	用途	备注
--entry	旧版入口点简写	仅进行简单的空白字符分割。拒绝带引号的值。
--entry-cmd	首选命令/可执行文件	与重复使用的 --entry-arg 配合，以精确控制 argv。
--entry-arg	首选参数值	每个参数重复使用一次；每个参数中的空格都会保留。

# Recommended for arguments containing spaces
./generate_nodejs.sh \
  --entry-cmd node \
  --entry-arg server.js \
  --entry-arg --message \
  --entry-arg "hello world"

最佳实践参考

安全最佳实践

1. 使用明确的标签：

   # Bad
   FROM node:alpine
   
   # Good
   FROM node:20-alpine
   
   # Better (with digest for reproducibility)
   FROM node:20-alpine@sha256:abc123...
   

2. 以非 root 用户身份运行：

   # Create user
   RUN addgroup -g 1001 -S appgroup && \
       adduser -S appuser -u 1001 -G appgroup
   
   # Switch to user before CMD
   USER appuser
   

3. 使用精简的基础镜像：

   • Alpine Linux（体积小、安全）
   • Distroless（无 shell，攻击面小）
   • 明确的运行时镜像（node:alpine 而非 node:latest）

4. 绝不将机密硬编码：

   # Bad
   ENV API_KEY=secret123
   
   # Good - use build secrets
   # docker build --secret id=api_key,src=.env
   RUN --mount=type=secret,id=api_key \
       API_KEY=$(cat /run/secrets/api_key) ./configure
   

优化最佳实践

1. 层缓存：

   # Copy dependency files first
   COPY package.json package-lock.json ./
   RUN npm ci
   
   # Copy application code last
   COPY . .
   

2. 合并 RUN 命令：

   # Bad (creates 3 layers)
   RUN apt-get update
   RUN apt-get install -y curl
   RUN rm -rf /var/lib/apt/lists/*
   
   # Good (creates 1 layer)
   RUN apt-get update && \
       apt-get install -y --no-install-recommends curl && \
       rm -rf /var/lib/apt/lists/*
   

3. 多阶段构建：

   # Build stage - can be large
   FROM node:20 AS builder
   WORKDIR /app
   COPY . .
   RUN npm install && npm run build
   
   # Production stage - minimal
   FROM node:20-alpine
   COPY --from=builder /app/dist ./dist
   CMD ["node", "dist/index.js"]
   

生产就绪

1. 健康检查：

   HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
       CMD curl -f http://localhost:3000/health || exit 1
   

2. 正确处理信号：

   # Use exec form for proper signal handling
   CMD ["node", "server.js"]  # Good
   CMD node server.js         # Bad (no signal forwarding)
   

3. 元数据：

   LABEL maintainer="[email protected]" \
         version="1.0.0" \
         description="My application"
   

常见模式

模式 1：使用 Next.js 的 Node.js

# syntax=docker/dockerfile:1
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nextjs -u 1001
COPY --from=builder --chown=nextjs:nodejs /app/.next ./.next
COPY --from=builder --chown=nextjs:nodejs /app/public ./public
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
USER nextjs
EXPOSE 3000
CMD ["npm", "start"]

模式 2：使用 FastAPI 的 Python

# syntax=docker/dockerfile:1
FROM python:3.12-slim AS builder
WORKDIR /app
# hadolint ignore=DL3008
RUN apt-get update && apt-get install -y --no-install-recommends gcc && \
    rm -rf /var/lib/apt/lists/*
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt

FROM python:3.12-slim
WORKDIR /app
RUN useradd -m -u 1001 appuser
COPY --from=builder /root/.local /home/appuser/.local
COPY --chown=appuser:appuser . .
ENV PATH=/home/appuser/.local/bin:$PATH \
    PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1
USER appuser
EXPOSE 8000
HEALTHCHECK CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

模式 3：Go CLI 工具

# syntax=docker/dockerfile:1
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.* ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /bin/app

FROM scratch
COPY --from=builder /bin/app /app
ENTRYPOINT ["/app"]

Docker 现代功能（2025）

使用 BuildX 构建多平台镜像

**使用场景：**构建可在 AMD64 和 ARM64 架构上运行的镜像（例如，x86 服务器和 Apple Silicon Mac）。

启用 BuildX：

# BuildX is included in Docker Desktop by default
# For Linux, ensure BuildX is installed
docker buildx version

创建多平台镜像：

# Build for multiple platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myapp:latest \
  --push \
  .

# Build and load for current platform (testing)
docker buildx build \
  --platform linux/amd64 \
  -t myapp:latest \
  --load \
  .

Dockerfile 注意事项：

# Most Dockerfiles work across platforms automatically
# Use platform-specific base images when needed
FROM --platform=$BUILDPLATFORM node:20-alpine AS builder

# Access build arguments for platform info
ARG TARGETPLATFORM
ARG BUILDPLATFORM
RUN echo "Building on $BUILDPLATFORM for $TARGETPLATFORM"

适用场景：

• 部署到混合基础设施（x86 + ARM）
• 在开发中支持 Apple Silicon Mac
• 针对 AWS Graviton（基于 ARM）实例进行优化
• 构建跨平台 CLI 工具

软件物料清单（SBOM）

**使用场景：**为供应链安全和合规生成 SBOM（2025 年这项要求日益普遍）。

在构建过程中生成 SBOM：

# Generate SBOM with BuildKit (Docker 24.0+)
docker buildx build \
  --sbom=true \
  -t myapp:latest \
  .

# SBOM is attached as attestation to the image
# View SBOM
docker buildx imagetools inspect myapp:latest --format "{{ json .SBOM }}"

从现有镜像生成 SBOM：

# Using Syft
syft myapp:latest -o json > sbom.json

# Using Docker Scout
docker scout sbom myapp:latest

SBOM 的优势：

• 跟踪整个供应链中的漏洞
• 验证许可证合规性
• 提高依赖项透明度
• 为安全审查提供审计跟踪
• 政府/企业合同要求提供

与 CI/CD 集成：

# GitHub Actions example
- name: Build with SBOM
  run: |
    docker buildx build \
      --sbom=true \
      --provenance=true \
      -t myapp:latest \
      --push \
      .

BuildKit 缓存挂载（高级）

**使用场景：**通过在多次构建之间保留包管理器缓存，大幅加快构建速度。

详见 references/optimization_patterns.md。

快速参考：

# syntax=docker/dockerfile:1

# NPM cache mount (30-50% faster builds)
RUN --mount=type=cache,target=/root/.npm \
    npm ci

# Go module cache
RUN --mount=type=cache,target=/go/pkg/mod \
    go mod download

# Pip cache
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

错误处理

常见生成问题

1. 缺少依赖文件：

   • 确保 package.json、requirements.txt、go.mod、pom.xml 存在
   • 请用户提供文件或生成模板

2. 未知框架：

   • 先使用本地参考资料，再使用 Context7，最后进行网页搜索
   • 回退到通用模板
   • 询问用户具体的运行时/构建要求

3. 验证失败：

   • 自动应用修复
   • 持续迭代，直到没有问题
   • 记录所有抑制项

与其他技能集成

此技能适合与以下技能结合使用：

• dockerfile-validator — 验证生成的 Dockerfile（必需）
• k8s-yaml-generator — 为容器生成 Kubernetes 部署配置
• helm-generator — 使用容器镜像创建 Helm chart

注意事项

• 对于编译型语言，始终使用多阶段构建
• 出于安全考虑，始终创建非 root 用户
• 为防止机密泄露，始终生成 .dockerignore
• 始终使用 dockerfile-validator 进行验证（或明确执行备用检查）
• 如果验证发现错误，至少迭代一次
• 尽可能使用 alpine 或 distroless 基础镜像
• 固定所有版本标签（切勿使用 :latest）
• 在同一层中清理包管理器缓存
• 按照 Dockerfile 指令的变更频率从低到高排列
• 使用 BuildKit 功能进行高级优化
• 提交前在本地测试构建
• 保持 Dockerfile 简洁且易于维护
• 使用注释说明任何不明显的模式

完成标准

仅当以下各项全部满足时，才将任务标记为完成：

• 已生成 Dockerfile 和 .dockerignore。
• 已通过 dockerfile-validator 执行验证，或记录了备用命令。
• 存在验证—迭代循环的证据（包含命令路径、数量和修复内容的迭代日志）。
• 不再有未解决的验证 error 发现项。
• 每个剩余的 warning 都已修复，或有对应的有意偏离报告条目。
• 输出包含优化指标和可执行的后续步骤。

来源

此技能基于对权威来源的全面研究：

Docker 官方文档：

• Docker 最佳实践
• 多阶段构建
• Dockerfile 参考

安全指南：

• Dockerfile 最佳实践 2025
• Docker 安全最佳实践

优化资源：

• Docker 多阶段构建指南
• 构建优化的 Docker 镜像