circleci/runner-agent

CircleCI Runner (Machine Mode) 镜像文档

镜像概述和主要用途

概述

CircleCI Runner (Machine Mode) 镜像是用于在自托管环境中以机器模式运行 CircleCI 作业的 Docker 镜像。该模式允许作业直接运行在宿主系统的底层环境中（而非容器隔离环境），支持直接访问系统资源、硬件设备及原生系统依赖，适用于需要突破容器隔离限制的 CI/CD 场景。

主要用途

• 执行需要直接访问底层系统资源（如 CPU、内存、GPU）的 CircleCI 作业
• 运行依赖特定系统库、驱动或硬件的任务（如编译内核模块、硬件加速计算）
• 处理资源密集型任务（如大型项目编译、自动化测试集群）
• 在自定义系统环境中执行 CI/CD 流程，满足企业级合规或定制化需求

核心功能和特性

• 原生系统访问：作业直接运行在宿主系统环境，无容器隔离层，支持访问完整系统调用和设备文件
• 多平台兼容：支持 Linux x86_64/ARM64 架构，兼容主流操作系统（如 Ubuntu、CentOS）
• 资源高效利用：通过直接调度系统资源，减少容器化带来的性能开销
• 无缝集成 CircleCI：与 CircleCI 平台原生集成，支持作业队列管理、日志实时同步及状态监控
• 灵活配置：支持通过环境变量、配置文件自定义 Runner 行为，适配不同场景需求

使用场景和适用范围

典型使用场景

• 资源密集型任务：如大数据处理、机器学习模型训练、游戏引擎编译等需高 CPU/内存的作业
• 硬件依赖任务：需访问 GPU、FPGA 或特定外设（如 USB 设备）的测试或构建流程
• 系统级操作：需修改内核参数、加载驱动模块或执行系统级脚本的任务
• 定制化环境需求：企业内部私有系统库、自研工具链或特定版本依赖的场景

适用范围

• 企业级研发团队：需在私有基础设施上运行 CI/CD 作业，满足数据合规或安全要求
• 高性能计算场景：科研机构、AI 实验室等需利用专用硬件加速的场景
• 复杂系统构建：嵌入式开发、操作系统内核开发等需深度系统访问的领域

使用方法和配置说明

安装前提

• 已安装 Docker Engine（20.10+）及 Docker Compose（可选，用于编排）
• 拥有 CircleCI 账户及组织权限，并已在 CircleCI 控制台创建 Runner 资源类（Resource Class）
• 获取有效的 Runner 注册令牌（Runner Token）：在 CircleCI 组织设置 > Runners > 注册 Runner 中生成

获取镜像

该镜像通常通过 CircleCI 官方渠道分发，或通过私有仓库获取。拉取命令示例：

bash
docker pull circleci/runner:machine-mode-latest

基本运行命令

通过 docker run 启动 Runner 容器，核心参数需包含 Runner 令牌、名称及资源类信息：

bash
docker run -d \
  --name circleci-runner-machine \
  --privileged \  # 机器模式需特权模式以访问宿主系统资源
  -e CIRCLECI_RUNNER_TOKEN="your_runner_token" \  # 替换为实际 Runner 令牌
  -e RUNNER_NAME="my-machine-runner-01" \  # 自定义 Runner 名称（需唯一）
  -e RESOURCE_CLASS="your-org/machine-medium" \  # 替换为 CircleCI 资源类名称
  -e RUNNER_MODE="machine" \  # 指定为机器模式
  -v /var/run/docker.sock:/var/run/docker.sock \  # 可选：如需在作业中使用 Docker
  circleci/runner:machine-mode-latest

说明：--privileged 标志为机器模式必需，用于解除容器对系统资源的访问限制。

环境变量说明

docker-compose 配置示例

通过 Docker Compose 管理 Runner 容器，便于持久化配置和服务编排：

yaml
# docker-compose.yml
version: '3.8'
services:
  circleci-runner:
    image: circleci/runner:machine-mode-latest
    container_name: circleci-machine-runner
    restart: always  # 容器退出时自动重启
    privileged: true
    environment:
      - CIRCLECI_RUNNER_TOKEN=your_runner_token  # 替换为实际令牌
      - RUNNER_NAME=machine-runner-prod-01
      - RESOURCE_CLASS=my-org/prod-machine
      - RUNNER_MODE=machine
      - RUNNER_LABELS=gpu,nvidia,ubuntu2204
      - LOG_LEVEL=info
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # 允许作业内使用 Docker
      - ./runner-config:/etc/circleci-runner  # 挂载自定义配置文件（可选）
    deploy:
      resources:
        limits:
          cpus: '8'  # 限制 CPU 核心数
          memory: 16G  # 限制内存使用

启动命令：

bash
docker-compose up -d

高级配置选项

1. 资源限制

通过 Docker 原生参数限制 Runner 容器的资源使用，避免影响宿主系统：

bash
docker run -d \
  --name circleci-runner-machine \
  --privileged \
  --cpus 4 \  # 限制使用 4 核 CPU
  --memory 8G \  # 限制使用 8GB 内存
  -e CIRCLECI_RUNNER_TOKEN="your_token" \
  ...  # 其他参数
  circleci/runner:machine-mode-latest

2. 持久化 Runner 配置

将 Runner 配置文件（如 runner-config.yaml）挂载到容器内，实现自定义配置持久化：

bash
docker run -d \
  ...
  -v /host/path/to/runner-config.yaml:/etc/circleci-runner/runner-config.yaml \
  ...

3. 网络配置

指定自定义网络或端口映射（如需外部监控 Runner 状态）：

bash
docker run -d \
  ...
  --network custom-network \  # 加入自定义 Docker 网络
  -p 9000:9000 \  # 映射监控端口（如 Runner 内置监控接口）
  ...

验证 Runner 状态

Runner 启动后，可通过以下方式验证是否正常连接 CircleCI 平台：

1. 查看容器日志：docker logs circleci-runner-machine，出现 Runner registered successfully 表示注册成功
2. 在 CircleCI 控制台 > 组织设置 > Runners 中，确认 Runner 状态为 Active
3. 提交包含 resource_class: your-org/machine-medium 的 CircleCI 作业，验证作业是否被该 Runner 接收并执行