configure-dockerfile

/configure:dockerfile

检查并根据项目标准配置 Dockerfile，重点关注最小化镜像、非 root 用户和多阶段构建。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用其他方法……
检查 Dockerfile 是否符合标准	只查看 Dockerfile（使用 Read 工具）
根据模板创建 Dockerfile	Dockerfile 已符合所有标准
验证镜像大小、安全性和多阶段构建	需要配置容器运行时（使用 /configure:container）
设置基于 Alpine/slim 的最小化镜像	项目使用专用基础镜像（有自定义要求）
确保配置了非 root 用户	调试容器问题（检查日志、检查运行时）

上下文

• Dockerfile：!find . -maxdepth 1 \( -name 'Dockerfile' -o -name 'Dockerfile.*' -o -name '*.Dockerfile' \)
• Dockerignore：!find . -maxdepth 1 -name \'.dockerignore\'
• 项目类型：!find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' \) -print -quit
• 基础镜像：!find . -maxdepth 1 \( -name 'Dockerfile' -o -name 'Dockerfile.*' -o -name '*.Dockerfile' \) -exec grep -hm5 '^FROM' {} +

参数

从命令参数中解析：

• --check-only：报告合规状态，不做修改
• --fix：自动应用修复，不提示确认
• --type <type>：覆盖项目类型检测结果（frontend、python、go、rust）

执行

执行此 Dockerfile 合规检查：

步骤 1：检测项目类型和 Dockerfile

1. 在项目根目录中查找 Dockerfile
2. 根据上下文（package.json、pyproject.toml、go.mod、Cargo.toml）检测项目类型
3. 解析 Dockerfile，分析当前配置
4. 若提供了 --type，则应用覆盖值

步骤 2：验证基础镜像的最新版本

标记过时的基础镜像之前，使用 WebSearch 或 WebFetch 验证最新版本：

1. Node.js Alpine：在 Docker Hub 上查看最新的 LTS Alpine 标签
2. Python slim：在 Docker Hub 上查看最新的 slim 标签
3. nginx Alpine：在 Docker Hub 上查看最新的 Alpine 标签
4. Go Alpine：在 Docker Hub 上查看最新的 Alpine 标签
5. Rust Alpine：在 Docker Hub 上查看最新的 Alpine 标签

步骤 3：分析合规性

根据以下标准检查 Dockerfile：

前端（Node.js）标准：

检查项	标准	严重程度
构建基础镜像	node:24-alpine（LTS）	若不同则 WARN
运行时基础镜像	nginx:1.30-alpine	若不同则 WARN
多阶段构建	必须	缺失则 FAIL
HEALTHCHECK	必须	缺失则 FAIL
非 root 用户	必须	缺失则 FAIL
构建缓存	建议使用 --mount=type=cache	INFO
OCI 标签	与 GHCR 集成时必须	缺失则 WARN

Python 服务标准：

检查项	标准	严重程度
基础镜像	python:3.14-slim	若不同则 WARN
多阶段构建	生产环境必须	缺失则 FAIL
HEALTHCHECK	必须	缺失则 FAIL
非 root 用户	必须	缺失则 FAIL
OCI 标签	与 GHCR 集成时必须	缺失则 WARN

OCI 容器标签：

标签	用途	严重程度
org.opencontainers.image.source	链接到代码仓库	缺失则 WARN
org.opencontainers.image.description	软件包描述	缺失则 WARN
org.opencontainers.image.licenses	SPDX 许可证标识符	缺失则 WARN
org.opencontainers.image.version	语义化版本（通过 ARG）	缺失则 INFO
org.opencontainers.image.revision	Git 提交 SHA（通过 ARG）	缺失则 INFO

步骤 4：报告结果

打印合规报告：

Dockerfile Compliance Report
================================
Project Type: <type> (detected)
Dockerfile: ./Dockerfile (found)

Configuration Checks:
  Build base      <image>           [PASS|WARN]
  Runtime base    <image>           [PASS|WARN]
  Multi-stage     <N> stages        [PASS|FAIL]
  HEALTHCHECK     <present|missing> [PASS|FAIL]
  Non-root user   <present|missing> [PASS|FAIL]
  Build caching   <enabled|missing> [PASS|INFO]

OCI Labels Checks:
  image.source       <present|missing> [PASS|WARN]
  image.description  <present|missing> [PASS|WARN]
  image.licenses     <present|missing> [PASS|WARN]

Recommendations:
  <list specific fixes needed>

如果使用了 --check-only，则到此为止。

步骤 5：应用修复（如果请求）

如果设置了 --fix 标志或用户确认：

1. 缺少 Dockerfile：从标准模板创建（见下方的标准模板）
2. 缺少 HEALTHCHECK：添加标准健康检查
3. 缺少多阶段构建：建议调整结构（需要手动修复）
4. 基础镜像过时：更新 FROM 行
5. 缺少 OCI 标签：添加 LABEL 指令

步骤 6：更新标准跟踪

更新 .project-standards.yaml：

components:
  dockerfile: "2025.1"

标准模板

前端（Node/Vite/nginx）

FROM node:24-alpine AS build

ARG SENTRY_AUTH_TOKEN
ARG VITE_SENTRY_DSN

WORKDIR /app

COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm npm ci

COPY . .
RUN --mount=type=cache,target=/root/.npm \
    --mount=type=cache,target=/app/node_modules/.vite \
    npm run build

FROM nginx:1.30-alpine

# OCI labels for GHCR integration
LABEL org.opencontainers.image.source="https://github.com/OWNER/REPO" \
      org.opencontainers.image.description="Production frontend application" \
      org.opencontainers.image.licenses="MIT" \
      org.opencontainers.image.vendor="Your Organization"

# Dynamic labels via build args
ARG VERSION=dev
ARG BUILD_DATE
ARG VCS_REF
LABEL org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.created="${BUILD_DATE}" \
      org.opencontainers.image.revision="${VCS_REF}"

COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx/default.conf.template /etc/nginx/templates/

EXPOSE 80

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost/health || exit 1

Python 服务

FROM python:3.14-slim AS builder

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN pip install uv && uv sync --frozen --no-dev

FROM python:3.14-slim

# OCI labels for GHCR integration
LABEL org.opencontainers.image.source="https://github.com/OWNER/REPO" \
      org.opencontainers.image.description="Production Python API server" \
      org.opencontainers.image.licenses="MIT" \
      org.opencontainers.image.vendor="Your Organization"

ARG VERSION=dev
ARG BUILD_DATE
ARG VCS_REF
LABEL org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.created="${BUILD_DATE}" \
      org.opencontainers.image.revision="${VCS_REF}"

RUN useradd --create-home appuser
USER appuser
WORKDIR /app

COPY --from=builder /app/.venv /app/.venv
COPY --chown=appuser:appuser . .

ENV PATH="/app/.venv/bin:$PATH"
EXPOSE 8000

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

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Agent 优化

上下文	命令
检查 Dockerfile 是否存在	find . -maxdepth 1 \( -name 'Dockerfile' -o -name 'Dockerfile.*' \) 2>/dev/null
验证多阶段构建	grep -c '^FROM' Dockerfile 2>/dev/null
检查是否使用非 root 用户	grep -E '^USER [^root]' Dockerfile 2>/dev/null
检查基础镜像	grep '^FROM' Dockerfile | head -1
快速合规性检查	/configure:dockerfile --check-only
自动修复问题	/configure:dockerfile --fix

标志

标志	说明
--check-only	报告状态，不提供修复方案
--fix	自动应用修复
--type <type>	覆盖项目类型（frontend、python）

备注

• Node 24 是当前的 Active LTS 版本（Node 22 处于维护阶段）
• 优先选择 nginx:1.30-alpine，而不是 debian 变体
• HEALTHCHECK 对 Kubernetes 存活探针至关重要
• 构建缓存可显著提升 CI/CD 速度
• 生产容器必须使用非 root 用户

另请参阅

• /configure:container - 全面的容器基础设施
• /configure:skaffold - Kubernetes 开发配置
• /configure:all - 运行所有合规性检查
• container-development 技能 - 容器最佳实践