marsyang1/bitbucket-ci-runner Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

Bitbucket CI Runner 镜像文档

镜像概述

Bitbucket CI Runner是一个自托管的Docker镜像，作为Bitbucket Pipelines的私有运行环境解决方案。它允许用户在自有基础设施（物理服务器、私有云或数据中心）上执行Bitbucket CI/CD流水线，替代Bitbucket官方托管运行器，解决托管服务在资源限制、数据隐私和环境定制方面的不足，提供对CI/CD执行环境的完全控制。

核心功能与特性

1. 自托管基础设施控制

• 脱离Bitbucket托管环境，在私有服务器上运行CI/CD任务，避免公共云资源限制
• 支持企业内网部署，满足数据不出境、本地数据处理等合规要求

2. 高度自定义环境

• 可配置任意操作系统基础镜像（如Ubuntu、CentOS、Alpine）及预装依赖
• 支持自定义工具链（编译器、运行时、测试框架）和系统库，适配特定项目需求

3. 资源优化与弹性扩展

• 支持配置CPU/内存资源限制，避免单一任务占用过量资源
• 可部署多个运行器实例，通过Bitbucket工作区自动负载均衡作业分配

4. 持久化与配置管理

• 支持挂载数据卷持久化运行器配置、作业日志和构建缓存
• 环境变量驱动配置，支持动态调整运行参数（如并发任务数、日志级别）

5. 多架构与网络兼容性

• 兼容Linux x86_64/ARM64架构，适配物理服务器与嵌入式设备
• 支持HTTP/HTTPS代理配置，适应企业内网网络隔离环境

使用场景与适用范围

适用场景

• 企业级开发团队：需满足GDPR、ISO 27001等合规要求，需控制数据存储位置
• 特殊环境依赖项目：依赖私有库、硬件加密模块或特定操作系统版本的项目
• 资源密集型任务：运行大型编译、自动化测试或大数据处理的CI/CD流水线
• 多团队共享基础设施：企业内部多项目复用运行器资源，降低硬件成本

不适用场景

• 无私有基础设施或运维能力的小型团队
• 完全依赖Bitbucket托管服务生态的简单流水线需求
• 对实时弹性伸缩有极高要求且可接受公共云成本的场景

使用方法与配置说明

前提条件

• 拥有Bitbucket账号及工作区管理员权限（需创建自托管运行器令牌）
• 目标服务器已安装Docker 20.10+或Docker Compose 2.0+
• 服务器需具备：
  • 访问Bitbucket API的网络权限（https://api.bitbucket.org）
  • 至少2核CPU、4GB内存（基础配置，根据并发任务数调整）
  • 持久化存储（建议10GB+，用于缓存和日志）

快速启动（Docker Run）

1. 获取Bitbucket运行器令牌

在Bitbucket工作区控制台依次进入：设置 > Pipelines > 运行器 > 添加运行器，选择"自托管运行器"，生成并复制令牌（有效期通常为30分钟）。

2. 启动运行器容器

bash
docker run -d \
  --name bitbucket-ci-runner \
  --restart unless-stopped \
  -e BITBUCKET_RUNNER_TOKEN="your-runner-token" \
  -e RUNNER_NAME="prod-ci-runner-01" \
  -e MAX_JOBS=2 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v runner-data:/opt/bitbucket-runner \
  marsyang1/bitbucket-ci-runner:latest

Docker Compose部署（推荐）

创建docker-compose.yml文件：

yaml
version: '3.8'

services:
  bitbucket-runner:
    image: marsyang1/bitbucket-ci-runner:latest
    container_name: bitbucket-ci-runner
    restart: unless-stopped
    environment:
      # 必需参数
      - BITBUCKET_RUNNER_TOKEN=your-runner-token  # 替换为Bitbucket生成的令牌
      # 可选参数
      - RUNNER_NAME=backend-team-runner           # 运行器显示名称（默认自动生成）
      - MAX_JOBS=3                                # 最大并发作业数（默认1）
      - LOG_LEVEL=info                            # 日志级别：debug/info/warn/error（默认info）
      - WORKING_DIR=/opt/workspace                # 作业工作目录（默认/opt/bitbucket-runner/workspace）
      - HTTP_PROXY=http://proxy:3128              # 代理配置（如需要）
      - HTTPS_PROXY=https://proxy:3128
      - NO_PROXY=localhost,127.0.0.1,bitbucket.org
    volumes:
      # 必需：允许运行器管理主机Docker容器（执行作业）
      - /var/run/docker.sock:/var/run/docker.sock
      # 推荐：持久化运行器配置与日志
      - runner-data:/opt/bitbucket-runner
      # 可选：挂载自定义工具目录（如私有依赖库）
      # - /opt/local-tools:/usr/local/custom-tools
    resources:
      limits:
        cpus: '4'                                 # CPU核心限制
        memory: 8G                                # 内存限制

volumes:
  runner-data:  # 自动创建Docker卷，持久化运行器数据

启动服务：

bash
docker-compose up -d

核心配置参数说明

运行状态验证

1. 容器状态检查：

   bash
   docker logs bitbucket-ci-runner
   

   成功启动会显示：Runner registered successfully with ID: <runner-id> 和 Waiting for jobs...

2. Bitbucket控制台验证： 在Bitbucket工作区 Pipelines > 运行器 页面，可看到新注册的运行器状态为"在线"。

数据管理与维护

日志与监控

• 容器日志：docker logs -f bitbucket-ci-runner（实时查看作业执行日志）
• 持久化日志路径：runner-data/logs/（通过卷挂载可在主机查看）
• 作业历史：Bitbucket工作区 Pipelines > 运行器 > 查看详情 可查看执行记录

升级与更新

1. 拉取最新镜像：docker pull marsyang1/bitbucket-ci-runner:latest
2. 重启容器：docker-compose down && docker-compose up -d（数据卷会保留注册信息）

资源调整

根据实际作业负载调整MAX_JOBS和CPU/内存限制，建议通过监控工具（如Prometheus+Grafana）观察资源使用率后逐步优化。

安全最佳实践

1. 最小权限原则：

   • 运行器主机仅开放必要端口，限制SSH访问
   • 避免使用--privileged模式运行容器

2. 镜像安全：

   • 定期拉取最新镜像以获取安全补丁
   • 通过私有镜像仓库分发（如Harbor），避免直接拉取公网镜像

3. 令牌管理：

   • 运行器令牌仅在初始化时使用，容器启动后自动持久化注册信息
   • 若令牌泄露，需在Bitbucket控制台吊销并重新生成

4. 数据隔离：

   • 不同团队/项目使用独立运行器实例，通过RUNNER_NAME标识
   • 敏感项目建议配置独立数据卷与网络隔离策略