maniator/docker-with-buildx

docker-with-buildx 镜像文档

一、镜像概述与主要用途

docker-with-buildx 是一个在 Docker 容器中预装了 Docker Buildx 的镜像。它实现了"Docker-in-Docker"（DinD）模式，将 Buildx 工具直接集成到容器环境中，主要用途是便捷地在隔离环境中运行各类 docker buildx 命令，无需在宿主机系统直接安装 Docker 或 Buildx 依赖。

二、核心功能与特性

核心功能

• 预装 Docker Buildx 工具，开箱即可使用所有 docker buildx 命令
• 支持与宿主机 Docker 守护进程通信，实现基于宿主机资源的镜像构建
• 支持 Buildx 构建器配置（如自定义构建节点、驱动设置）的持久化存储

关键特性

• 兼容性：支持所有标准 docker buildx 命令（如 build、create、use、inspect 等）
• 配置持久化：可通过卷挂载实现 Buildx 配置（构建器实例、节点信息）在多次容器运行间共享
• 轻量集成：容器化设计，可快速集成到开发环境或 CI/CD 流水线
• 环境隔离：避免 Buildx 配置与宿主机环境冲突，确保构建环境一致性

三、使用场景与适用范围

典型使用场景

• 开发环境：在未直接安装 Docker 或 Buildx 的系统（如受限开发机、轻量级 Linux 发行版）中执行镜像构建
• CI/CD 流水线：作为标准化构建步骤集成到自动化流程，消除宿主机环境差异导致的构建问题
• 临时构建任务：快速启动容器执行单次或批量 Buildx 操作，任务完成后自动清理容器
• 多构建器管理：在隔离环境中创建、切换、测试不同配置的 Buildx 构建器实例

适用范围

• 需要使用 Buildx 高级特性（如多平台构建、缓存优化、输出定制）的场景
• 对环境隔离性有要求的构建任务
• 希望简化 Buildx 部署流程的用户或团队

四、使用方法与配置说明

4.1 基本构建操作

通过以下命令可直接在当前目录执行镜像构建，使用默认 Buildx 配置：

bash
docker run --rm \
    -e DOCKER_TLS_CERTDIR=/certs \  # 指定 TLS 证书目录（默认配置）
    -v /var/run/docker.sock:/var/run/docker.sock \  # 挂载宿主机 Docker 套接字，实现与宿主机 Docker 通信
    -v $(pwd):$(pwd) -w $(pwd) \  # 挂载当前工作目录到容器内相同路径，并设置为工作目录
    maniator/docker-with-buildx \
    build .  # 执行 Buildx 构建命令（当前目录下的 Dockerfile）

参数说明：

• --rm：容器退出后自动删除
• -e DOCKER_TLS_CERTDIR=/certs：设置 TLS 证书目录环境变量，适配 Docker 安全配置
• -v /var/run/docker.sock:/var/run/docker.sock：关键挂载项，使容器内的 Docker 客户端能控制宿主机 Docker 守护进程
• -v $(pwd):$(pwd) -w $(pwd)：确保容器内构建上下文与宿主机当前目录一致，避免路径问题

4.2 持久化 Buildx 配置（共享构建器）

若需在多次容器运行间共享 Buildx 配置（如自定义构建器实例），可通过挂载卷持久化配置目录。以下示例创建并使用自定义构建器：

步骤 1：定义配置目录

bash
# 定义 Buildx 配置存储路径（默认使用宿主机 Docker 配置目录下的 buildx 子目录）
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
BUILDX_DIR="$DOCKER_CONFIG/buildx"
mkdir -p $BUILDX_DIR  # 确保目录存在

步骤 2：创建自定义构建器

bash
docker run --rm \
    -e DOCKER_TLS_CERTDIR=/certs \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v $BUILDX_DIR:/env_configs/.docker/buildx \  # 挂载持久化配置目录到容器内 Buildx 配置路径
    -v $(pwd):$(pwd) -w $(pwd) \
    maniator/docker-with-buildx \
    create --driver docker-container --name my_builder --use  # 创建名为 my_builder 的构建器并设为默认

步骤 3：使用自定义构建器执行构建

bash
docker run --rm \
    -e DOCKER_TLS_CERTDIR=/certs \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v $BUILDX_DIR:/env_configs/.docker/buildx \  # 复用之前的配置目录
    -v $(pwd):$(pwd) -w $(pwd) \
    maniator/docker-with-buildx \
    --builder=my_builder build .  # 指定使用 my_builder 构建器执行构建

说明：通过挂载 $BUILDX_DIR:/env_configs/.docker/buildx，容器内的 Buildx 配置会持久化到宿主机的 $BUILDX_DIR 目录，后续运行容器时可直接复用已创建的构建器（如 my_builder）。

五、环境变量说明

六、相关链接

• GitHub Actions 构建状态：https://github.com/maniator/dind-buildx/actions/workflows/docker-build.yml/badge.svg](https://github.com/maniator/dind-buildx/actions/workflows/docker-build.yml)
• Docker Hub 镜像：