Docker 硬化镜像多阶段实践与 GitHub Actions 流水线集成

通过本博客，你将掌握：

一套简洁、可投入生产的多阶段 Dockerfile，正确使用 Docker Hardened Images

一套 GitHub Actions 工作流，具备以下能力：

• 向 dhi.io 进行认证
• 构建镜像
• 运行官方 DHI 策略检查
• 若镜像不符合加固标准则让流水线失败

这将此前所有博客中的内容转化为可重复、自动化的实践。

仅有本地可用的 Dockerfile 是不够的。在真实团队中，镜像必须以完全相同的方式构建，安全检查也必须自动化。

如果策略检查只在开发者的笔记本上运行，那它在压力下就会被跳过。如果 CI 无法从 dhi.io 拉取镜像，构建就会随机失败。如果 Dockerfile 仍然使用臃肿的基础镜像或以 root 身份运行，那加固后的基础镜像就会失去大部分价值。

本博客正是为了解决这些缺口。

开始之前你需要了解的内容

• 基本的 GitHub Actions 知识（或任何能运行 Docker 的 CI）
• 一个 GitHub 仓库（公开或私有），你可以在其中添加 secrets

步骤 1 — 生产级多阶段 Dockerfile（最佳实践）

以下是我为大多数语言框架推荐的模式（Python 示例）：

# syntax=docker/dockerfile:1

# ---------- Build stage ----------
FROM dhi.io/python:3.13-dev AS builder

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PATH="/app/venv/bin:$PATH"

WORKDIR /app

# Create isolated environment
RUN python -m venv /app/venv

COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --no-cache-dir -r requirements.txt

# ---------- Runtime stage ----------
FROM dhi.io/python:3.13

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PATH="/app/venv/bin:$PATH"

WORKDIR /app

# Copy only what is required
COPY --from=builder /app/venv /app/venv
COPY app.py .

# Runtime image already defaults to non-root
EXPOSE 8000
CMD ["python", "app.py"]

这个 Dockerfile 遵循的关键规则

说明

所有需要包管理器或编译器的东西都留在第一阶段。只有最终的产物被复制到加固后的运行时镜像中。

步骤 2 — 提交 CI 前的本地验证

docker build -t my-dhi-app:local .
docker run --rm -p 8000:8000 my-dhi-app:local

# Policy check
docker scout policy my-dhi-app:local --policy-bundle dhi/policies:latest

在推送之前修复任何失败。

步骤 3 — GitHub Actions 工作流（完整示例）

创建 .github/workflows/dhi-build.yml：

name: Build and check with Docker Hardened Images

on:
  push:
    branches: [ "main" ]
  pull_request:

env:
  IMAGE_NAME: my-dhi-app:${{ github.sha }}

jobs:
  build-and-policy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to Docker Hub (for Scout + policy bundle)
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PAT }}

      - name: Log in to dhi.io
        uses: docker/login-action@v3
        with:
          registry: dhi.io
          username: ${{ secrets.DOCKER_USER }}
          password: ${{ secrets.DOCKER_PAT }}

      - name: Build image
        uses: docker/build-push-action@v6
        with:
          context: .
          load: true
          tags: ${{ env.IMAGE_NAME }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Evaluate against DHI policies
        uses: docker/scout-action@v1
        with:
          command: policy
          image: ${{ env.IMAGE_NAME }}
          policy-bundle: dhi/policies:latest
          exit-code: true          # fail the job if any policy is violated

必需的 GitHub Secrets

在仓库设置 → Secrets and variables → Actions 中，添加：

• DOCKER_USER — 你的 Docker Hub 用户名
• DOCKER_PAT — 具有读取权限的个人访问令牌（如果后续要推送镜像则需要写入权限）

这个流水线的作用

• 同时登录 Docker Hub 和 dhi.io
• 构建多阶段镜像（带缓存）
• 运行官方 DHI 策略包
• 如果镜像不符合加固标准，则让 PR 或推送失败

步骤 4 — 可选的改进项

• 仅在 main 分支上且策略检查通过后才推送镜像
• 固定 policy-bundle 的 digest 而不是用 :latest 以确保可重复性
• 将 docker scout cves 作为额外的信息步骤添加
• 尽可能使用 OIDC 登录（Docker 组织可用）而不是长期有效的 PAT

---

将最终阶段临时改回普通的 python:3.13 镜像。观察策略步骤失败（root 用户、多余的包、缺失的证明等）。再恢复到 DHI 运行时阶段，看流水线重新变绿。

在真实团队中，我会：

• 将这个工作流设为每个服务仓库的默认配置
• 将失败的 DHI 策略检查视为与失败的单元测试同等对待
• 将多阶段 Dockerfile 模式保存在共享模板或 cookiecutter 中
• 审查任何在最终阶段需要 -dev 镜像的例外情况（几乎永远不合理的）
• 将此与 Sandboxes 系列结合，让 Agent 本身在加固的基础上构建

安全注意事项

• CI 运行器必须能够向 dhi.io 进行认证；否则构建会变得不稳定
• 长期有效的 PAT 应该定期轮换且范围尽可能小
• 策略评估发生在最终镜像上，而不是仅在基础上——这才是有意义的
• 缓存没问题；它不会削弱策略检查

常见错误

• 登录了 Docker Hub 但忘了 dhi.io
• 在构建阶段使用运行时镜像（缺少工具）
• 设置 exit-code: false 导致策略检查永远不会让构建失败
• 将 secrets 烘焙进镜像层
• 在生产 Dockerfile 中对基础镜像使用 :latest 标签

总结

你的机器上不会创建任何永久资源。在 GitHub 中，你可以在完成后删除工作流文件或测试分支。

• 带 -dev 构建阶段 + 纯运行时阶段的多阶段是标准模式
• CI 必须同时向 Docker Hub 和 dhi.io 进行认证
• 官方 DHI 策略包可以在每次构建时自动执行
• 失败的策略检查应该阻止合并

你现在拥有了一条从代码到加固生产镜像的完整自动化路径。

在最后的博客（第 5 篇）中，我们将介绍现有应用的迁移、生产采纳清单、加固系统包概览、已知限制，以及如何将 Docker Hardened Images 与 Sandboxes 系列结合，形成完整的安全开发生 Workflow。

参考链接

https://docs.docker.com/dhi/how-to/use/ — 多阶段模式和 CI 说明

https://docs.docker.com/dhi/how-to/policies/ — 策略包和 GitHub Actions 示例

https://docs.docker.com/build/cache/backends/gha/ — GitHub Actions 缓存

Official Scout GitHub Action 文档

所有命令和工作流模式均已根据当前官方文档（2026 年 8 月）进行过验证。