GitHub Actions 自动化流程

#📋 快速概览

本项目配置了两个核心工作流：

优化成果：通过 Phase 1 和 Phase 2 优化，CI/CD 流水线速度提升 65-75%，缓存命中率达到 85-95%

#🚀 CI/CD 流水线 (ci.yml) - 优化版

#主要功能

• 并行测试矩阵: Python 3.12/3.13, Ruff, MyPy, 单元/集成测试（并行执行）
• 智能安全扫描: Safety (依赖漏洞) + Bandit (代码安全) - 并行运行
• 优化 Docker 构建: 多平台构建，高级缓存策略，BuildKit 优化
• 性能测试: PR 性能基准测试（可选）
• 自动发布: Python 包构建 + GitHub Release

#触发条件

• PR 到 main, master, release/**
• Push 到 main, master, release/**

#新增优化特性

#1. 智能并行执行

# 测试、安全扫描、文档构建并行运行
jobs:
  test: # 单元/集成测试
  security: # 安全扫描
  docs: # 文档构建
  performance: # 性能测试
  # 全部并行执行，不互相等待

#2. 高级缓存策略

• 多层缓存: Pip、Node modules、Docker layers
• 智能缓存键: 基于内容哈希的缓存键生成
• 缓存预热: 主分支自动缓存预热
• 缓存命中率: 85-95%（原来 60-70%）

#3. 优化的依赖管理

• 并行安装: 依赖包并行下载和安装
• 选择性安装: 每个任务只安装必需的依赖
• 预下载包: 常用包预先缓存

#🔧 自动代码质量修复 (ruff.yml) - 增强版

#工作流程

1. 智能检测 Ruff 代码问题（并行检测）
2. 自动应用可修复的问题
3. 创建/更新 PR 提交修复
4. 支持多种通知配置（Slack/Email）

#智能特性

• 避免无限循环：跳过 auto-fix 分支
• 智能 PR 管理：更新现有 PR 而非创建重复
• 并发控制：支持多分支并发处理
• 通知集成：Slack 和邮件通知支持

#新增功能

#通知配置

# Slack 通知
SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

# 邮件通知
EMAIL_NOTIFICATIONS: user@example.com
NOTIFICATION_ENABLED: true

#🧩 复合动作 (Composite Actions)

项目使用复合动作来重用常见的 CI/CD 步骤，提高维护性和一致性。

#1. setup-python 复合动作

位置：.github/actions/setup-python/action.yml

功能特性：

• 智能缓存键生成
• 多级缓存支持
• 可选的 pre-commit 设置
• 自动依赖检测和安装

使用示例：

- name: Setup Python with caching
  uses: ./.github/actions/setup-python
  with:
    python-version: "3.12"
    cache-key-suffix: "linting"
    install-deps: "true"
    pre-commit: "false"

输出：

• cache-key: 生成的缓存键
• python-hash: Python 依赖哈希
• cache-hit: 缓存命中状态

#2. setup-node 复合动作

位置：.github/actions/setup-node/action.yml

功能特性：

• 自动检测包管理器（npm/yarn）
• 优化的缓存策略
• 公共注册表配置
• 包安装验证

使用示例：

- name: Setup Node.js
  uses: ./.github/actions/setup-node
  with:
    node-version: "18"
    working-directory: "./ui"
    package-manager: "yarn"

#🎯 智能路径检测与过滤

#1. 变更检测优化

# 根据文件变更智能运行任务
- name: Detect changes
  uses: dorny/paths-filter@v2
  with:
    filters: |
      python:
        - '**/*.py'
        - 'pyproject.toml'
        - 'requirements*.txt'
      docs:
        - 'docs/**'
        - '*.md'
      docker:
        - 'Dockerfile*'
        - '.dockerignore'

#2. 条件执行

# 只在有 Python 变更时运行测试
test:
  if: steps.changes.outputs.python == 'true'

# 只在有 Docker 变更时构建
docker:
  if: steps.changes.outputs.docker == 'true'

#💾 改进的缓存策略

#1. 分层缓存架构

# Python 依赖缓存
- name: Cache pip dependencies
  uses: actions/cache@v4
  with:
    path: |
      ~/.cache/pip
      ~/.local/share/virtualenvs
    key: ${{ runner.os }}-python-${{ matrix.python-version }}-${{ hashFiles('**/pyproject.toml') }}
    restore-keys: |
      ${{ runner.os }}-python-${{ matrix.python-version }}-

# Docker 层缓存
- name: Build with cache
  uses: docker/build-push-action@v5
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=max

#2. 缓存优化脚本

位置：.github/scripts/optimization-helpers.sh

功能：

• 智能缓存键生成
• 缓存预热
• 缓存清理和管理
• 性能监控

#3. 缓存性能指标

#⚡ 性能改进

#1. 并行化策略

• 任务级并行：多个 Job 同时运行
• 测试并行：pytest-xdist 多进程测试
• Linting 并行：多个 Linter 同时运行

#2. 依赖安装优化

• 并行下载：pip 并行下载包
• 预编译包：使用预编译 wheels
• 缓存复用：跨 Job 共享缓存

#3. Docker 优化

• BuildKit：高级构建缓存
• 多阶段构建：减少镜像大小
• 并行构建：多平台同时构建

#4. 性能基准测试

运行性能基准测试：

# 手动触发基准测试
gh workflow run performance-benchmark.yml

# 查看性能报告
gh run list --workflow=performance-benchmark.yml

#⚙️ 配置要求

#必需的 Secrets

#可选配置（通知）

#新增环境变量

# 性能优化
PYTHON_VERSION: "3.12"
NODE_VERSION: "18"

# 通知配置
NOTIFICATION_ENABLED: false # 设为 true 启用通知
EMAIL_NOTIFICATIONS: "" # 逗号分隔的邮件列表
PR_LABELS: "auto-fix,ruff" # 自动 PR 标签

# 缓存配置
CACHE_VERSION: "v3" # 缓存版本号
CACHE_RETENTION_DAYS: "30" # 缓存保留天数

SMTP_SERVER: smtp.example.com
SMTP_PORT: 587

#📊 性能基准

#CI/CD 性能对比

#性能等级：A+ (优秀)

• ✅ 并行作业执行
• ✅ 高级缓存策略
• ✅ 智能路径检测
• ✅ 优化的依赖管理
• ✅ Docker BuildKit 优化

#🐛 故障排除

#常见问题速查

#调试技巧

1. 启用调试模式：

   hljs yaml复制

   env:
     ACTIONS_STEP_DEBUG: true
     ACTIONS_RUNNER_DEBUG: true
   

2. 查看缓存状态：

   hljs bash复制

   # 查看缓存使用情况
   gh api repos/:owner/:repo/actions/cache/usage
   

3. 性能分析：

   hljs yaml复制

   # 添加计时步骤
   - name: Record timing
     run: |
       echo "Start: $(date +%s)" >> $GITHUB_ENV
       # ... your steps ...
       echo "Duration: $(($(date +%s) - START_TIME)) seconds"
   

4. 分析失败的工作流：

   hljs bash复制

   # 下载失败的工作流日志
   gh run download <run-id> --name logs
   

#性能问题诊断

1. 检查并行度：

   • 确认可并行任务确实在并行执行
   • 检查 needs 依赖配置

2. 优化缓存使用：

   • 查看缓存命中率报告
   • 调整缓存键策略

3. 监控资源使用：

   hljs yaml复制

   - name: System resources
     run: |
       echo "CPU usage: $(top -bn1 | grep "Cpu(s)" | awk '{print $2}')"
       echo "Memory usage: $(free -m | awk 'NR==2{printf "%.2f%%", $3*100/$2}')"
       echo "Disk usage: $(df -h . | awk 'NR==2 {print $5}')"
   

#🔗 相关资源

#工作流配置

• [GitHub Actions 运行历史](${{ github.server_url }}/${{ github.repository }}/actions)
• 配置参考
• 复合动作

#性能监控

• 性能基准测试
• 优化脚本

#测试相关

• 测试运行指南
• [覆盖率报告](https://codecov.io/gh/${{ github.repository }})

#最佳实践

• GitHub Actions 文档
• 缓存最佳实践
• Docker BuildKit 指南

#📈 持续优化计划

#已完成 (Phase 1 & 2)

• ✅ 基础并行化实现
• ✅ 复合动作创建
• ✅ 智能缓存策略
• ✅ 通知系统集成
• ✅ 性能基准建立

#计划中 (未来改进)

• 🔄 增量构建（只测试变更部分）
• 🎯 测试优先级排序
• 🏃 自托管 Runner 支持
• 🤖 AI 驱动的测试选择
• 📊 实时性能监控仪表板