Ci Cd规范

CI_CD规范

流水线设计、自动化检查

流水线设计

流水线阶段

[Requirement] CI/CD 流水线必须包含以下阶段，按顺序执行，任一阶段失败则中止后续阶段。

代码提交 → 1.构建 → 2.静态检查 → 3.单元测试 → 4.集成测试 → 5.安全扫描 → 6.制品入库 → 7.部署

阶段	说明	失败处理
构建	编译、打包、生成可部署制品	中止，通知提交者
静态检查	Lint、类型检查、代码风格	中止，通知提交者
单元测试	运行单测，校验覆盖率	中止，通知提交者
集成测试	启动依赖服务，运行集成测试	中止，通知提交者
安全扫描	依赖漏洞、镜像漏洞、SAST	中止，通知提交者 + 安全团队
制品入库	推送镜像/包到制品仓库	中止
部署	部署到目标环境	中止，回滚

流水线模板

[Standard] 所有项目使用统一的 CI/CD 流水线模板，禁止每个项目自行定义完整流水线，仅允许覆写特定步骤的参数。

GitHub Actions 示例：

# .github/workflows/ci.yml
name: CI
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
 
      - name: Install
        run: npm ci
 
      - name: Lint
        run: npm run lint
 
      - name: Type Check
        run: npm run type-check
 
      - name: Unit Test
        run: npm run test:unit -- --coverage
 
      - name: Build
        run: npm run build
 
      - name: Security Scan
        run: npm audit --audit-level=high
 
  deploy-staging:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to staging
        run: ./scripts/deploy.sh staging

流水线性能

[Standard] CI 流水线单次执行时间不超过 15 分钟，超时需优化（拆分任务、缓存依赖、并行化）。

[Suggestion] 对依赖安装、构建产物使用缓存，减少重复构建时间。

# 依赖缓存示例
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

反模式

❌ 流水线只有构建和部署，缺少测试和安全检查阶段。
❌ 流水线执行时间超过 30 分钟，导致开发效率低下。
❌ 每个项目自行定义流水线，格式和质量参差不齐。

自动化检查

必选检查项

[Requirement] 合并到主干分支前，以下检查必须全部通过，任一失败禁止合并。

检查项	工具示例	说明
代码风格检查	ESLint / Prettier / Black / gofmt	统一代码风格
类型检查	TypeScript / mypy / Go vet	编译期类型安全
单元测试	Jest / pytest / JUnit	核心逻辑测试
测试覆盖率	nyc / coverage.py / JaCoCo	覆盖率达标（见单元测试规范）
安全扫描	npm audit / Snyk / Trivy	依赖漏洞检测
构建验证	各语言构建命令	确保可成功构建

质量门禁

[Requirement] CI 必须设置质量门禁（Quality Gate），以下指标不达标则流水线失败：

指标	阈值
单元测试覆盖率	≥ 70%（核心模块 ≥ 80%）
新增代码覆盖率	≥ 80%
严重/高危漏洞数	0
阻断级 Code Smell 数	0

SonarQube 门禁配置示例

# sonar-project.properties
sonar.qualitygate.wait=true
 
# 门禁规则（在 SonarQube 控制台配置）
# 1. Coverage on New Code < 80% → Error
# 2. Vulnerabilities > 0 → Error
# 3. Security Hotspots Reviewed < 100% → Error

提交前本地检查

[Standard] 使用 Git Hooks（Husky / pre-commit）在提交前自动执行轻量检查，减少 CI 失败次数。

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "pre-push": "npm run test:unit"
    }
  },
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.py": ["black --check", "flake8"]
  }
}

反模式

❌ CI 检查失败后，通过 --force 或关闭门禁强行合并。
❌ 测试覆盖率统计排除了核心业务代码。
❌ 安全扫描只在发布时才运行，开发阶段完全不检查。

制品管理

制品版本

[Requirement] 所有可部署制品（Docker 镜像、Jar 包、前端构建产物）必须有唯一不可变版本号，遵循版本号规范的语义化版本（SemVer）。

镜像标签：registry.example.com/user-service:1.2.3
制品路径：artifactory.example.com/user-service/1.2.3/app.jar

[Caution] 禁止使用 latest 标签部署到生产环境，必须使用确定的版本号。

制品仓库

[Standard] 所有制品必须推送到统一的制品仓库（Nexus / Artifactory / Harbor），禁止制品散落在开发机或 CI 临时目录。

制品类型	仓库	说明
Docker 镜像	Harbor / ECR	按项目分仓库
Maven 包	Nexus	`groupId` 统一前缀 `com.example`
npm 包	Verdaccio / npm registry	私有包前缀 `@example/`
前端构建产物	对象存储 / CDN	按版本号分目录

制品生命周期

[Standard] 制品保留策略：

环境	保留时长	说明
dev 构建	7 天	自动清理
test 构建	30 天	自动清理
staging 构建	90 天	自动清理
prod 构建	永久	不可删除

制品签名

[Suggestion] 生产环境制品必须经过签名校验，防止篡改。

# Docker 镜像签名（cosign）
cosign sign registry.example.com/user-service:1.2.3
cosign verify registry.example.com/user-service:1.2.3

触发规则

分支触发

[Standard] 不同分支的 CI/CD 行为必须区分：

分支	CI 触发	CD 目标
`feature/*`	全量 CI 检查	不部署
`develop`	全量 CI 检查	自动部署到 test
`main`	全量 CI 检查 + 制品入库	自动部署到 staging
`release/*`	全量 CI 检查	手动审批后部署到 prod
`hotfix/*`	全量 CI 检查	手动审批后部署到 prod

PR 触发

[Requirement] 所有 Pull Request 必须触发 CI 检查，检查通过且至少 1 人审批后方可合并。

# GitHub 分支保护规则
required_status_checks:
  strict: true
  contexts:
    - lint
    - type-check
    - unit-test
    - security-scan
required_pull_request_reviews:
  required_approving_review_count: 1
  dismiss_stale_reviews: true

定时触发

[Standard] 每天凌晨定时运行全量测试和安全扫描，及时发现依赖漏洞和间歇性测试失败。

on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨 2 点

手动触发

[Standard] 支持手动触发流水线（workflow_dispatch），便于回滚和紧急部署。

on:
  workflow_dispatch:
    inputs:
      version:
        description: '部署版本号'
        required: true
      environment:
        description: '目标环境'
        required: true
        default: 'staging'

权限

流水线权限

[Requirement] CI/CD 流水线使用的凭证（Token、密钥）必须最小权限，禁止使用管理员权限或个人 Token。

[Requirement] 所有密钥必须通过 Secret Manager 管理，禁止明文写入流水线配置文件。

# GitHub Actions 使用 Secrets
- name: Deploy
  env:
    DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
  run: ./scripts/deploy.sh

部署审批

[Requirement] prod 环境部署必须经过审批，禁止自动部署。审批人至少 1 人，且不能是提交者本人。

环境	审批要求
dev	无需审批
test	无需审批
staging	无需审批（自动）
prod	必须审批（≥1 人）

操作审计

[Requirement] 所有流水线操作（构建、部署、回滚）必须记录操作日志，包括操作人、时间、版本、环境。

[Standard] 审计日志保留至少 180 天，支持按操作人、时间、环境检索。

反模式

❌ 流水线配置中硬编码数据库密码。
❌ 使用个人 GitHub Token 作为 CI 凭证，人员离职后失效。
❌ prod 部署无审批，合并即自动上线。
❌ 无操作审计日志，出问题无法追溯。