blacksquaremedia/ci

CI镜像文档

镜像概述和主要用途

CI镜像是专为持续集成(CI)流程设计的Docker镜像，预集成了常用开发工具、构建框架和测试环境。其核心用途是简化CI/CD流水线中的环境配置工作，使开发者无需在CI节点手动安装依赖，直接通过镜像快速执行自动化构建、代码质量检查、单元测试及部署前验证等任务，提升CI流程的稳定性和效率。

核心功能和特性

• 工具链集成：包含Git、Make、GCC、Python、Node.js等多语言开发工具，支持Java、Go、Python等主流项目构建。
• 轻量级设计：基于Alpine或Debian slim基础镜像，平衡功能与体积，缩短CI环境拉取时间。
• 多平台支持：提供amd64、arm64等架构版本，适配不同CI运行环境。
• 灵活定制：支持通过环境变量或挂载配置文件调整工具版本、构建参数等。
• CI系统兼容：适配GitLab CI、GitHub Actions、Jenkins等主流CI平台。

使用场景和适用范围

• 自动化构建：编译源代码、打包应用（如Java Maven/Gradle构建、Python wheel打包）。
• 代码质量检查：集成ESLint、Pylint等工具执行静态代码分析。
• 测试执行：运行JUnit、PyTest等测试框架，生成测试报告和覆盖率数据。
• 多CI平台适配：在GitLab CI、GitHub Actions等系统中作为执行环境镜像。
• 快速环境标准化：统一团队CI环境，避免"本地可运行，CI失败"的环境不一致问题。

使用方法和配置说明

基本使用（Docker Run）

通过docker run启动容器并执行CI任务：

bash
docker run --rm -v $(pwd):/workspace ci-images:latest \
  sh -c "cd /workspace && make build && make test"

• --rm：任务完成后自动清理容器。
• -v $(pwd):/workspace：挂载本地项目目录到容器内/workspace，实现代码访问。
• ci-images:latest：CI镜像名称（根据实际镜像标签调整）。
• sh -c "..."：替换为项目实际构建/测试命令（如npm run build、go test）。

环境变量配置

通过-e参数传递环境变量自定义行为：

bash
docker run --rm -v $(pwd):/workspace \
  -e BUILD_TYPE=release \
  -e TEST_COVERAGE=true \
  ci-images:latest \
  sh -c "make build TYPE=\$BUILD_TYPE && make test COVERAGE=\$TEST_COVERAGE"

常用环境变量：

• BUILD_TYPE：构建类型（debug/release）
• TEST_COVERAGE：是否生成覆盖率报告（true/false）
• LOG_LEVEL：日志输出级别（info/debug/warn）

在CI配置文件中使用

GitLab CI示例（.gitlab-ci.yml）

yaml
stages:
  - build
  - test

build_job:
  stage: build
  image: ci-images:v1.2.0  # 使用固定标签避免版本变更风险
  script:
    - cd /builds/$CI_PROJECT_PATH
    - make build
  artifacts:
    paths:
      - dist/  # 保存构建产物供后续阶段使用

test_job:
  stage: test
  image: ci-images:v1.2.0
  script:
    - make test
  dependencies:
    - build_job  # 依赖build_job的产物

GitHub Actions示例（.github/workflows/ci.yml）

yaml
name: CI Pipeline
on: [push, pull_request]

jobs:
  build-test:
    runs-on: ubuntu-latest
    container: ci-images:v1.2.0
    steps:
      - uses: actions/checkout@v4  # 拉取代码
      - name: Build
        run: make build
      - name: Test
        run: make test --coverage

自定义工具版本

如需特定工具版本（如Node.js 18），可基于基础镜像扩展：

dockerfile
# 自定义Dockerfile
FROM ci-images:v1.2.0
RUN npm install -g n && n 18  # 安装Node.js 18

构建并使用：

bash
docker build -t my-ci-images:node18 .
docker run --rm -v $(pwd):/workspace my-ci-images:node18 npm run build

注意事项

• 镜像标签管理：生产环境建议使用固定标签（如v1.2.0）而非latest，避免版本变更导致CI失败。
• 资源限制：在CI系统中配置容器CPU/内存限制（如GitLab CI的resources字段），防止任务占用过多资源。
• 依赖缓存：对node_modules、vendor等依赖目录使用CI缓存（如GitLab CI的cache配置），加速任务执行。