symbolplatform/build-ci

CI镜像技术文档

镜像概述

CI镜像是专为持续集成（Continuous Integration）场景设计的Docker镜像，旨在提供一致、可重复的构建和测试环境。通过预集成常用开发工具、运行时依赖及环境配置，解决"环境不一致导致构建失败"的问题，支持自动化构建、测试、打包等CI流程，降低团队CI/CD流水线的配置复杂度。

主要用途

• 统一开发团队的构建/测试环境，消除"本地可运行，CI失败"的环境差异问题
• 简化CI平台（如Jenkins、GitLab CI、GitHub Actions）的配置流程
• 支持多语言项目的自动化构建（如Java、Python、Node.js等）
• 提供轻量级、可扩展的CI环境，适配不同项目的定制化需求

核心功能与特性

标准化环境

• 基于稳定的基础镜像（如Alpine、Ubuntu）构建，版本固定且可追溯
• 预配置系统级依赖（如libc、编译工具链），避免重复安装

工具集成

• 内置版本控制工具：Git（含LFS支持）、SVN
• 构建工具：Maven、Gradle、npm、yarn、pip、go mod
• 容器化工具：Docker CLI、kubectl（可选）
• 测试工具：JUnit、pytest、Jest、Selenium（基础版）
• 代码质量工具：SonarQube Scanner、ESLint、Pylint（可选）

多场景适配

• 支持多架构（amd64/arm64）
• 提供多语言版本标签（如ci-image:java17、ci-image:python3.11）
• 兼容主流CI平台的Agent/Runner环境

可扩展性

• 支持通过环境变量自定义工具配置
• 允许挂载外部配置文件或脚本扩展功能
• 轻量级设计，基础版本镜像体积控制在500MB以内

使用场景

• 多语言项目CI流程：统一Java、Node.js混合项目的构建环境
• 开源项目自动化测试：快速接入GitHub Actions实现PR自动测试
• 企业内部CI标准化：在Jenkins集群中统一使用该镜像，降低维护成本
• 跨团队协作：不同团队共享相同的构建标准，减少沟通成本

使用方法

基本使用（本地测试）

bash
# 启动交互式CI环境（基础版）
docker run -it --rm -v $(pwd):/workspace ci-image:latest bash

# 在容器内执行构建命令（示例：Maven项目）
cd /workspace && mvn clean package

CI平台集成示例

GitLab CI配置（.gitlab-ci.yml）

yaml
stages:
  - build
  - test

build_job:
  stage: build
  image: ci-image:java17-node18
  script:
    - mvn clean compile
    - npm install
  artifacts:
    paths:
      - target/
      - node_modules/

test_job:
  stage: test
  image: ci-image:java17-node18
  script:
    - mvn test
    - npm run test
  dependencies:
    - build_job

GitHub Actions配置（.github/workflows/ci.yml）

yaml
name: CI
on: [push]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    container:
      image: ci-image:python3.10
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements.txt
      - run: pytest tests/

环境变量配置

示例：自定义缓存目录

bash
docker run -it --rm \
  -v $(pwd):/workspace \
  -v ~/.m2:/cache \
  -e CACHE_DIR=/cache \
  ci-image:latest \
  mvn clean package -Dmaven.repo.local=$CACHE_DIR

卷挂载说明

自定义扩展

如需添加镜像未包含的工具，可通过Dockerfile基于该镜像二次构建：

dockerfile
FROM ci-image:latest

# 安装额外工具（示例：Docker Compose）
RUN apk add --no-cache docker-compose

# 添加自定义脚本
COPY ci-scripts/ /usr/local/bin/
RUN chmod +x /usr/local/bin/*

版本说明

注意事项

• 生产环境建议使用固定版本标签（如java17），避免latest标签自动更新导致兼容性问题
• 敏感配置（如密钥、凭证）建议通过CI平台的"环境变量"功能注入，而非内置到镜像中
• 依赖缓存目录（如/cache）持久化挂载可大幅提升重复构建效率，推荐在CI配置中启用