dimikot/ci-runner

自动扩展自托管Runner镜像

镜像概述和主要用途

本镜像用于构建可自动扩展的GitHub自托管Runner，支持启动多个Runner实例。通过环境变量配置，可灵活对接GitHub仓库，实现CI/CD作业的高效执行。其核心价值在于结合自动扩展能力与CI存储预初始化机制，显著提升作业运行效率，同时支持自定义扩展以满足特定需求。

核心功能和特性

• 自动扩展支持：可基于CPU使用率或CloudWatch指标（如ActiveRunnersPercent）配置自动扩缩容规则
• 灵活配置：通过环境变量定义Runner注册信息、标签、时区等关键参数
• 端口转发：支持将容器内端口转发至指定主机，实现网络资源共享
• CI存储预初始化：启动时从CI_STORAGE_HOST拉取数据，预创建工作目录，加速作业文件恢复
• 自定义扩展：支持基于基础镜像添加额外软件（如Node、Python等）和自定义入口脚本
• 优雅关闭：支持配置停止宽限期，确保作业完成后再注销Runner

使用场景和适用范围

• 需要自托管Runner的GitHub仓库CI/CD流程
• 对CI作业性能有较高要求的场景（通过预初始化存储加速）
• 需要根据负载自动调整Runner数量的团队或项目
• 需要自定义运行环境（如特定工具、依赖）的CI/CD场景

使用方法和配置说明

环境变量配置

密钥配置

• CI_STORAGE_PRIVATE_KEY：访问CI_STORAGE_HOST所需的SSH私钥，可通过环境变量传递或挂载文件至/run/secrets/CI_STORAGE_PRIVATE_KEY

Docker Compose配置示例

yaml
services:
  ci-runner:
    build:
      context: .
      dockerfile: Dockerfile
    stop_grace_period: 10m  # 确保作业完成的宽限期
    environment:
      - GH_TOKEN  # 从环境变量传入
      - GH_REPOSITORY  # 从环境变量传入，格式{owner}/{repo}
      - GH_LABELS  # 从环境变量传入，逗号分隔标签
      - TZ  # 从环境变量传入时区
      # 端口转发配置：容器内localhost端口转发至FORWARD_HOST
      - FORWARD_HOST  # 从环境变量传入转发目标主机
      - FORWARD_PORTS=15432 18125/udp 10022  # 转发端口列表
      - CI_STORAGE_HOST=127.0.0.1:10022  # CI存储服务地址
      - BTIME  # 从环境变量传入主机启动时间戳
    volumes:
      # 挂载SSH私钥用于访问CI存储
      - ~/.ssh/ci-storage:/run/secrets/CI_STORAGE_PRIVATE_KEY
      # 持久化CI存储缓存
      - ~/.ci-storage-cache:/var/cache/ci-storage
    tmpfs:
      # 将工作目录挂载到tmpfs，提升性能和可预测性
      - /mnt:exec,size=80%

自定义Dockerfile示例

基于基础镜像扩展，添加额外软件和自定义入口脚本：

Dockerfile
FROM ghcr.io/dimikot/ci-runner:latest
RUN true \
    && apt-get update \
    && apt-get install -y nodejs redis-tools postgresql-client coreutils \
    && npm -g install yarn \
    && ...  # 添加其他所需软件
# 添加自定义root用户入口脚本（自动执行）
COPY --chmod=755 --chown=root:root root/entrypoint*.sh /root
# 添加自定义guest用户入口脚本（自动执行）
COPY --chmod=755 --chown=guest:guest guest/entrypoint*.sh /home/guest

进入容器方法

bash
# 以guest用户身份进入容器（自动切换至/home/guest目录）
docker compose exec ci-runner bash -l

# 以root用户身份进入容器（不带-l参数）
docker compose exec ci-runner bash

注意事项

• 每个容器仅服务于一个GitHub仓库（由GH_REPOSITORY指定），多仓库需启动多个容器
• 自定义入口脚本需遵循命名规范：/root/entrypoint.*.sh（root用户执行）或/home/guest/entrypoint.*.sh（guest用户执行），会被自动执行
• 停止容器时建议设置足够长的stop_grace_period（如10分钟），确保作业完成并注销Runner

相关链接

• https://github.com/dimikot/ci-storage