docker-in-docker-bitbucket-pipelines

镜像概述和主要用途

概述

docker-in-docker-bitbucket-pipelines 是专为 Bitbucket Pipelines 设计的 Docker-in-Docker (DinD) 镜像，旨在提供容器内独立的 Docker 运行环境。该镜像集成 Docker 引擎与 CLI 工具，允许在 Bitbucket CI/CD 流水线中直接执行 Docker 命令，无需依赖宿主机 Docker 环境。

主要用途

解决 Bitbucket Pipelines 原生环境中缺乏 Docker 守护进程的限制，支持在流水线中完成 Docker 镜像构建、容器运行、镜像推送等操作，无缝衔接容器化应用的自动化构建与部署流程。

核心功能和特性

核心功能

• 内置 Docker 引擎：容器内运行独立的 Docker 守护进程，支持完整的 Docker 生命周期管理（构建、运行、推送、拉取等）。
• 标准 Docker CLI 兼容：集成 Docker 客户端，支持 docker build、docker run、docker push 等所有标准命令。
• Bitbucket Pipelines 适配：针对 Bitbucket 流水线环境优化网络配置（如桥接网络、DNS 解析）和资源分配（内存/CPU 限制）。

特性

• 轻量级基础：基于 Alpine 或官方 docker:dind 镜像构建，镜像体积小，启动速度快。
• TLS 加密支持：默认启用 Docker 守护进程 TLS 加密通信，通过环境变量可配置证书路径与加密策略。
• 多架构兼容：支持 amd64、arm64 等主流架构（需基础镜像支持）。
• 特权模式适配：预配置特权模式所需的内核参数与挂载点，确保 Docker 引擎在 Bitbucket Pipelines 中稳定运行。

使用场景和适用范围

典型使用场景

1. 容器镜像构建：在流水线中直接构建应用 Docker 镜像（如微服务、前端静态资源容器）。
2. 容器化测试：运行构建后的镜像进行集成测试（如启动容器并执行 API 测试、单元测试）。
3. 镜像推送至仓库：将构建好的镜像推送到私有仓库（如 Bitbucket Container Registry、Docker Hub、AWS ECR）。
4. 多阶段构建流程：配合 docker buildx 实现跨平台镜像构建或多阶段构建（如编译阶段→运行阶段分离）。

适用范围

• 技术栈：基于 Docker 容器化的应用项目（如 Java、Python、Node.js、Go 等）。
• 团队场景：使用 Bitbucket 作为代码仓库，且依赖 Docker 进行构建/部署的开发团队。
• 流程需求：需要在 CI/CD 流程中集成 Docker 操作的自动化场景（如每日构建、提交触发构建、发布流水线）。

使用方法和配置说明

Bitbucket Pipelines 配置示例

在 bitbucket-pipelines.yml 中通过 services 配置引入该镜像，作为独立服务提供 Docker 守护进程，主构建容器通过网络连接使用其服务。

基础配置（构建并推送镜像至 Bitbucket 容器仓库）

image: docker:latest  # 主构建容器使用 Docker CLI 镜像
pipelines:
  default:
    - step:
        name: "Build and push Docker image"
        services:
          - docker  # 引入 DinD 服务（此处需替换为实际镜像名，如 your-registry/docker-in-docker-bitbucket-pipelines:latest）
        script:
          # 1. 登录 Bitbucket 容器仓库（使用 Bitbucket 内置环境变量）
          - docker login -u $BITBUCKET_REGISTRY_USER -p $BITBUCKET_REGISTRY_PASSWORD $BITBUCKET_REGISTRY
          
          # 2. 构建镜像（标签格式：仓库地址/项目名/镜像名:提交哈希）
          - docker build -t $BITBUCKET_REGISTRY/$BITBUCKET_REPO_SLUG:$BITBUCKET_COMMIT .
          
          # 3. 推送镜像至仓库
          - docker push $BITBUCKET_REGISTRY/$BITBUCKET_REPO_SLUG:$BITBUCKET_COMMIT
        caches:
          - docker  # 缓存 Docker 层，加速后续构建

高级配置（多阶段构建 + 集成测试）

image: docker:latest
pipelines:
  branches:
    main:
      - step:
          name: "Build, test and push production image"
          services:
            - docker
          script:
            # 构建测试镜像
            - docker build --target test -t app-test .
            # 运行容器并执行测试
            - docker run --rm app-test npm run test
            # 构建生产镜像
            - docker build --target production -t $BITBUCKET_REGISTRY/app-prod:$BITBUCKET_COMMIT .
            # 推送生产镜像
            - docker push $BITBUCKET_REGISTRY/app-prod:$BITBUCKET_COMMIT

本地测试运行示例

如需在本地复现 Bitbucket Pipelines 环境，可通过 docker run 命令直接启动镜像：

# 启动 DinD 容器（需特权模式）
docker run -d \
  --privileged \
  --name bitbucket-dind \
  -e DOCKER_TLS_CERTDIR=/certs \  # 启用 TLS 加密
  -v dind-certs:/certs/client \   # 挂载证书卷（持久化 TLS 证书）
  your-registry/docker-in-docker-bitbucket-pipelines:latest

# 启动客户端容器，连接 DinD 服务
docker run -it \
  --link bitbucket-dind:docker \   # 链接 DinD 容器
  -e DOCKER_HOST=tcp://docker:2376 \  # 指定 Docker 守护进程地址
  -e DOCKER_TLS_VERIFY=1 \          # 启用 TLS 验证
  -e DOCKER_CERT_PATH=/certs/client \ # 指定证书路径
  -v dind-certs:/certs/client \     # 挂载共享证书卷
  docker:latest \
  sh  # 进入客户端容器执行 Docker 命令

配置参数与环境变量

核心环境变量

Bitbucket 内置敏感变量（需提前配置）

• BITBUCKET_REGISTRY_USER：Bitbucket 容器仓库登录用户名（通常为 $BITBUCKET_USERNAME）。
• BITBUCKET_REGISTRY_PASSWORD：Bitbucket 容器仓库登录密码（需在 Bitbucket 项目设置→Repository variables 中配置为 Secured 类型）。

注意事项

1. 特权模式依赖：该镜像必须在特权模式（--privileged）下运行，以确保 Docker 引擎能访问宿主机内核功能（如挂载、网络栈）。
2. 安全风险：特权模式可能引入宿主机安全风险，建议仅在 CI/CD 环境中使用，且避免挂载宿主机敏感目录。
3. 资源限制：在 Bitbucket Pipelines 中需配置足够的内存（建议 ≥ 2GB），避免 Docker 守护进程因资源不足崩溃。
4. TLS 配置：生产环境必须启用 TLS 加密（默认开启），禁用 TLS 仅允许用于本地测试。
5. 缓存优化：通过 Bitbucket Pipelines 的 caches: [docker] 配置缓存 Docker 层，可显著减少重复构建时间。