CI Runner 镜像文档

镜像概述

CI Runner镜像是CI/CD（持续集成/持续部署）流程中的核心执行组件，用于接收并运行CI系统（如GitLab CI、GitHub Actions等）分配的任务。作为任务执行节点，该镜像可自动化处理代码构建、测试验证、应用打包及部署发布等流程，助力开发团队实现高效的DevOps工作流。

核心功能与特性

• 跨平台兼容：支持Linux、Windows、macOS等主流操作系统，适配x86、ARM等硬件架构。
• 多系统集成：可与GitLab CI、GitHub Actions、Jenkins等主流CI/CD平台无缝对接。
• 任务隔离机制：基于容器化执行环境，确保不同任务间的依赖隔离，避免环境冲突。
• 灵活配置能力：支持通过环境变量、配置文件或CI系统界面自定义任务参数（如标签、并发数、超时时间）。
• 资源管控：可限制CPU、内存等资源使用，优化任务执行效率与系统资源分配。
• 日志与监控：提供详细的任务执行日志，支持与监控工具集成，便于问题排查与流程优化。

使用场景与适用范围

典型应用场景

• 持续集成流程：自动对代码提交进行构建与测试，及时发现集成问题。
• 自动化测试：执行单元测试、集成测试、E2E测试等，保障代码质量。
• 自动部署：在测试通过后触发应用自动部署至开发、测试或生产环境。
• 定时任务：周期性执行数据备份、系统检查、报表生成等自动化操作。

适用对象

• 软件开发团队：实现代码提交后的自动化构建与测试。
• DevOps工程师：构建标准化、自动化的交付流水线。
• 企业级项目：通过任务隔离与资源管控提升CI/CD流程稳定性。

使用方法与配置说明

前提条件

• 已安装Docker引擎（推荐20.10+版本）。
• 已部署CI系统（如GitLab、GitHub等），并获取Runner注册所需的URL与令牌。

快速启动示例

通过docker run命令启动Runner容器，需指定CI系统注册信息：

bash
docker run -d \
  --name ci-runner \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \  # 如需使用Docker执行器，挂载Docker套接字
  -e CI_SERVER_URL="[***]" \  # CI系统URL（必填）
  -e REGISTRATION_TOKEN="your-registration-token" \  # 注册令牌（必填）
  -e RUNNER_NAME="backend-runner" \  # Runner名称（CI系统中显示）
  -e RUNNER_TAG_LIST="java,backend,test" \  # 任务标签（用于筛选Runner）
  -e RUNNER_EXECUTOR="docker" \  # 执行器类型（docker/shell/kubernetes等）
  -e RUNNER_CONCURRENT="3" \  # 最大并发任务数
  ci-runner-image:latest

核心配置参数

环境变量配置

配置文件挂载

如需复杂配置，可通过挂载config.toml文件自定义Runner参数：

bash
docker run -d \
  --name ci-runner \
  -v /path/to/local/config.toml:/etc/ci-runner/config.toml \  # 挂载配置文件
  ci-runner-image:latest

配置文件示例（config.toml）：

toml
[[runners]]
  name = "prod-deploy-runner"
  url = "[***]"
  token = "runner-registration-token"
  executor = "kubernetes"
  [runners.kubernetes]
    image = "ubuntu:22.04"
    namespace = "ci-jobs"
    cpu_request = "1"
    memory_request = "1G"
  [runners.cache]
    Type = "s3"
    Path = "ci-cache"
    Shared = true

容器管理操作

• 查看任务日志：

  bash
  docker logs -f ci-runner
  

• 重启/停止Runner：

  bash
  docker restart ci-runner
  docker stop ci-runner
  

• 更新镜像：

  bash
  docker pull ci-runner-image:latest && docker restart ci-runner
  

注意事项

• 执行器兼容性：使用docker执行器时，需确保容器内Docker客户端版本与宿主机Docker服务端版本匹配。
• 数据持久化：生产环境建议挂载配置文件与缓存目录（如/etc/ci-runner、/cache），避免容器重建导致配置丢失。
• 安全配置：限制容器权限，避免挂载敏感目录（如/root），必要时启用用户命名空间隔离。