# CI/CD 流水线可视化
本文档详细说明了 MZMCP 项目的完整 CI/CD 流水线，包括所有工作流的触发条件、执行步骤和输出结果。
## 代码变更流水线 Mermaid 图
```mermaid
graph TB
%% 样式定义
classDef trigger fill:#e1f5fe,stroke:#0288d1,stroke-width:2px
classDef check fill:#fff3e0,stroke:#f57c00,stroke-width:2px
classDef build fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
classDef security fill:#e8f5e9,stroke:#388e3c,stroke-width:2px
classDef scheduled fill:#fce4ec,stroke:#c2185b,stroke-width:2px
classDef issue fill:#e0f7fa,stroke:#006064,stroke-width:2px
classDef result fill:#f5f5f5,stroke:#616161,stroke-width:1px
%% 触发条件
Push[Push到main分支]:::trigger
PR[Pull Request到main]:::trigger
Manual[手动触发workflow_dispatch]:::trigger
BranchRule[分支保护规则触发]:::trigger
IssueOpened[Issue被打开/编辑/重开]:::issue
PROpened[PR被打开/同步/重开]:::issue
Schedule1[定时任务-每周一00:00]:::scheduled
Schedule2[定时任务-每周四19:17]:::scheduled
Schedule3[定时任务-每周日21:43]:::scheduled
Schedule4[定时任务-每天17:44]:::scheduled
%% PR时触发的安全检查
PR --> |触发| DependencyReview[依赖审查<br>dependency-review.yml]:::check
PR --> |触发| OSSARPR[OSSAR静态分析<br>ossar.yml]:::security
PR --> |触发| CodeQLPR[CodeQL分析<br>codeql.yml]:::security
%% Push到main触发的工作流（路径限制）
PushRelease[Push to main<br>路径: src/**<br>publish.yaml<br>.github/workflows/release.yml]:::trigger
Push --> PushRelease
PushRelease --> |触发| ReleaseBuild[Release构建<br>release.yml]:::build
Push --> |触发| OSSAR[OSSAR静态分析<br>ossar.yml]:::security
Push --> |触发| CodeQL[CodeQL分析<br>codeql.yml]:::security
Push --> |触发| Scorecard[Scorecard安全评分<br>scorecard.yml]:::security
%% 分支保护规则触发
BranchRule --> |触发| ScorecardRule[Scorecard安全评分<br>scorecard.yml]:::security
%% Issue相关触发
IssueOpened --> |触发| IssueLabeler[Issue自动标签<br>issue-labeler.yml]:::issue
IssueOpened --> |触发| IssueSummary[Issue AI总结<br>issue-summary.yml]:::issue
%% PR相关触发
PROpened --> |触发| PRLabeler[PR智能标记<br>labeler.yml]:::issue
%% 定时任务
Schedule1 --> |触发| CodeQLScheduled[CodeQL分析<br>codeql.yml]:::security
Schedule2 --> |触发| ScorecardScheduled[Scorecard安全评分<br>scorecard.yml]:::security
Schedule3 --> |触发| OSSARScheduled[OSSAR静态分析<br>ossar.yml]:::security
Schedule4 --> |触发| Stale[标记陈旧Issue/PR<br>stale.yml]:::scheduled
%% 手动触发
Manual --> |触发| ReleaseBuildManual[Release构建<br>release.yml]:::build
Manual --> |触发| ScorecardManual[Scorecard安全评分<br>scorecard.yml]:::security
%% Release构建详细步骤
ReleaseBuild --> ReleaseSteps1[步骤0: Harden Runner]
ReleaseSteps1 --> ReleaseSteps2[步骤1: Checkout代码]
ReleaseSteps2 --> ReleaseSteps3[步骤2: 设置Python 3.11]
ReleaseSteps3 --> ReleaseSteps4[步骤3: 获取版本号]
ReleaseSteps4 --> ReleaseSteps5[步骤4: 安装依赖]
ReleaseSteps5 --> ReleaseSteps6[步骤5: 模糊测试<br>可失败不阻断]
ReleaseSteps6 --> ReleaseSteps7[步骤6: 创建发布目录]
ReleaseSteps7 --> ReleaseSteps8[步骤7: 复制项目文件]
ReleaseSteps8 --> ReleaseSteps9[步骤8: 打包ZIP]
ReleaseSteps9 --> ReleaseSteps10[步骤9: 计算SHA256哈希]
ReleaseSteps10 --> ReleaseSteps11[步骤10: 生成Release Notes]
ReleaseSteps11 --> ReleaseSteps12[步骤11: 生成SLSA出处文件]
ReleaseSteps12 --> ReleaseSteps13[步骤12: 生成证据包<br>始终运行]
ReleaseSteps13 --> ReleaseSteps14[步骤13: 创建GitHub Release]
%% CodeQL分析详细步骤
CodeQL --> CodeQLMatrix[矩阵: ubuntu-latest<br>windows-latest<br>macos-latest<br>语言: Python]
CodeQLMatrix --> CodeQLSteps1[步骤1: Harden Runner]
CodeQLSteps1 --> CodeQLSteps2[步骤2: Checkout代码]
CodeQLSteps2 --> CodeQLSteps3[步骤3: 初始化CodeQL]
CodeQLSteps3 --> CodeQLSteps4[步骤4: Autobuild]
CodeQLSteps4 --> CodeQLSteps5[步骤5: 执行CodeQL分析]
%% OSSAR分析详细步骤
OSSAR --> OSSARSteps1[步骤1: Checkout代码<br>平台: windows-latest]
OSSARSteps1 --> OSSARSteps2[步骤2: 运行OSSAR静态分析]
OSSARSteps2 --> OSSARSteps3[步骤3: 上传SARIF结果<br>到Security标签页]
%% Scorecard评分详细步骤
Scorecard --> ScorecardSteps1[步骤1: Harden Runner]
ScorecardSteps1 --> ScorecardSteps2[步骤2: Checkout代码<br>persist-credentials: false]
ScorecardSteps2 --> ScorecardSteps3[步骤3: 运行Scorecard分析]
ScorecardSteps3 --> ScorecardSteps4[步骤4: 上传SARIF工件<br>保留5天]
ScorecardSteps4 --> ScorecardSteps5[步骤5: 上传到代码扫描仪表板]
%% 依赖审查详细步骤
DependencyReview --> DependencySteps1[步骤1: Harden Runner]
DependencySteps1 --> DependencySteps2[步骤2: Checkout代码]
DependencySteps2 --> DependencySteps3[步骤3: 依赖审查<br>失败级别: moderate<br>PR评论: always<br>重试快照警告]
%% Issue标签器详细步骤
IssueLabeler --> IssueLabelerSteps1[步骤1: Harden Runner]
IssueLabelerSteps1 --> IssueLabelerSteps2[步骤2: Checkout代码]
IssueLabelerSteps2 --> IssueLabelerSteps3[步骤3: Tag-ur-it<br>自动标签和指派]
%% Issue总结详细步骤
IssueSummary --> IssueSummarySteps1[步骤1: Harden Runner]
IssueSummarySteps1 --> IssueSummarySteps2[步骤2: Checkout代码]
IssueSummarySteps2 --> IssueSummarySteps3[步骤3: 安装Python依赖<br>openai]
IssueSummarySteps3 --> IssueSummarySteps4[步骤4: Gitee AI生成总结<br>评论到Issue]
%% PR标记器详细步骤
PRLabeler --> PRLabelerSteps1[步骤1: Harden Runner]
PRLabelerSteps1 --> PRLabelerSteps2[步骤2: Checkout代码]
PRLabelerSteps2 --> PRLabelerSteps3[步骤3: PR Insights标记器<br>大小/类别/风险分析<br>质量门禁检查]
%% 标记陈旧详细步骤
Stale --> StaleSteps1[步骤1: Harden Runner]
StaleSteps1 --> StaleSteps2[步骤2: 标记陈旧Issue<br>60天无活动]
StaleSteps2 --> StaleSteps3[步骤3: 标记陈旧PR<br>60天无活动]
StaleSteps3 --> StaleSteps4[步骤4: 自动关闭<br>30天后]
%% 输出结果
ReleaseSteps14 --> ReleaseResult[✅ GitHub Release<br>📦 ZIP包 + SLSA出处文件 + 证据包]:::result
CodeQLSteps5 --> CodeQLResult[✅ CodeQL分析报告<br>📊 多平台安全扫描]:::result
OSSARSteps3 --> OSSARResult[✅ OSSAR扫描结果<br>🔍 Windows静态分析]:::result
ScorecardSteps5 --> ScorecardResult[✅ Scorecard评分<br>🎯 安全评分徽章<br>发布到OpenSSF API]:::result
DependencySteps3 --> DependencyResult[✅ 依赖审查结果<br>📦 PR评论<br>阻止已知漏洞]:::result
IssueLabelerSteps3 --> IssueLabelerResult[✅ Issue自动标签<br>🏷️ 规则匹配<br>自动指派]:::result
IssueSummarySteps4 --> IssueSummaryResult[✅ Issue AI总结<br>🤖 Gitee AI<br>结构化评论]:::result
PRLabelerSteps3 --> PRLabelerResult[✅ PR智能标记<br>📊 大小/类别/风险分析<br>质量门禁]:::result
StaleSteps4 --> StaleResult[✅ Issue/PR清理<br>🧹 自动标记和关闭]:::result
```
## 工作流触发条件说明
| 工作流名称 | Push到main | Pull Request | 定时任务 | 手动触发 | 分支保护规则 | Issue | PR |
|---------------------------|-------------------------------------------------------------|--------------|-----------|------|--------|----------------------------|---------------------------------|
| **release.yml** | ✅ 路径限制: src/**, publish.yaml, .github/workflows/release.yml | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |
| **codeql.yml** | ✅ | ✅ | 每周一 00:00 | ❌ | ❌ | ❌ | ❌ |
| **ossar.yml** | ✅ | ✅ | 每周日 21:43 | ❌ | ❌ | ❌ | ❌ |
| **dependency-review.yml** | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| **scorecard.yml** | ✅ | ❌ | 每周四 19:17 | ✅ | ✅ | ❌ | ❌ |
| **stale.yml** | ❌ | ❌ | 每天 17:44 | ❌ | ❌ | ❌ | ❌ |
| **issue-labeler.yml** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ opened, edited, reopened | ❌ |
| **issue-summary.yml** | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ opened | ❌ |
| **labeler.yml** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ opened, synchronize, reopened |
### 触发条件说明
- **路径限制**: 某些工作流仅在特定文件或目录变更时触发，以节省 CI 资源
- **分支保护规则**: scorecard.yml 还会在分支保护规则变更时触发
- **定时任务**: 所有时间均为 UTC 时区
## 工作流分类
### 🏗️ 构建发布类
#### release.yml - Release 构建与发布
- **用途**: 创建发布包、生成 Release Notes、创建 GitHub Release
- **平台**: ubuntu-latest
- **输出**:
- ZIP 发布包（含源代码、配置文件、文档、许可证）
- SLSA 出处文件（符合 SLSA v1.0 标准）
- 证据包（包含源代码、Git 元数据、依赖项、SBOM、签名）
- **特殊功能**:
- 自动从 git 历史生成 Release Notes
- 模糊测试失败不阻断构建
- 证据包始终生成，即使构建失败
- 完整的 SLSA 供应链可追溯性
### 🔍 代码检查类
#### codeql.yml - CodeQL 静态分析
- **用途**: 多平台静态安全分析
- **平台**: ubuntu-latest, windows-latest, macos-latest（矩阵构建）
- **语言**: Python
- **输出**: SARIF 格式安全报告，上传到 GitHub Security 标签页
- **特点**: 覆盖多个操作系统，确保跨平台安全性
#### ossar.yml - OSSAR 开源静态分析
- **用途**: 开源静态分析工具集成
- **平台**: windows-latest（特定平台支持）
- **输出**: SARIF 格式分析结果
- **限制**: 目前仅支持 Windows，其他平台支持计划中
#### dependency-review.yml - 依赖项安全审查
- **用途**: 检测 PR 中的依赖项漏洞
- **平台**: ubuntu-latest
- **触发**: 仅在 Pull Request 时运行
- **配置**:
- 失败级别: moderate（中等严重性）
- PR 评论: 始终添加评论
- 重试快照警告: 启用
- **输出**: PR 中添加依赖项审查评论
### 🧹 维护管理类
#### stale.yml - 陈旧 Issue 和 PR 管理
- **用途**: 自动标记和关闭长期无活动的 Issue 和 PR
- **平台**: ubuntu-latest
- **配置**:
- Issue 陈旧期限: 60 天
- PR 陈旧期限: 60 天
- 自动关闭期限: 30 天（标记后）
- 自定义标签: no-issue-activity, no-pr-activity
- 自定义消息: 中英文提示
- **功能**:
- 自动标记陈旧 Issue 和 PR
- 自动关闭长期未回复的内容
- 可恢复（回复后自动重新激活）
#### issue-labeler.yml - Issue 自动标签
- **用途**: 根据 Issue 内容自动添加标签和分配人员
- **平台**: ubuntu-latest
- **触发**: Issue 被打开、编辑或重新打开
- **配置**:
- 配置文件: .github/issue-rules.yml
- 使用 tag-ur-it Action
- **功能**:
- 自动标签匹配
- 自动人员指派
- 提升团队协作效率
#### issue-summary.yml - Issue AI 总结
- **用途**: 使用 AI 自动生成 Issue 总结
- **平台**: ubuntu-latest
- **触发**: Issue 被打开
- **功能**:
- 使用 Gitee AI (Qwen2.5-72B-Instruct) 生成总结
- 输出结构化信息：问题类型、核心摘要、关键信息、优先级
- 自动评论到 Issue
- 支持 Bug、Feature、Docs、Question、Other 分类
- 优先级评估（高/中/低）
#### labeler.yml - PR 智能标记
- **用途**: 分析 PR 并添加智能标签
- **平台**: ubuntu-latest
- **触发**: PR 被打开、同步或重新打开
- **功能**:
- 文件大小分析（限制: 100KB, 500行）
- PR 规模分析（限制: 5000行, 50文件）
- 类别标签（size、category、risk）
- 质量门禁（xlarge、large files、too many files）
- 自动评论 PR 总结
#### scorecard.yml - 安全评分
- **用途**: 对仓库进行安全评分，生成安全徽章
- **平台**: ubuntu-latest
- **输出**:
- SARIF 格式评分报告
- 发布到 OpenSSF REST API（公共仓库）
- Scorecard 徽章（可嵌入 README）
- 上传到 GitHub 代码扫描仪表板
- **特点**:
- 支持分支保护检查
- SARIF 工件保留 5 天
- 需要特殊权限（id-token: write）
## 工作流步骤详情
### Release 构建流程 (release.yml)
| 步骤 | 名称 | 说明 |
|----|-------------------|--------------------------|
| 0 | Harden Runner | 安全加固 Runner，审计所有出站调用 |
| 1 | Checkout 代码 | 获取完整 git 历史 |
| 2 | 设置 Python 3.11 | 配置 Python 运行环境 |
| 3 | 获取版本号 | 从 publish.yaml 读取版本信息 |
| 4 | 安装依赖 | 安装 requirements.txt 中的依赖 |
| 5 | 运行模糊测试 | 运行模糊测试（失败不阻断） |
| 6 | 创建发布目录 | 准备发布目录结构 |
| 7 | 复制项目文件 | 复制源代码、配置、文档、许可证 |
| 8 | 打包 ZIP | 创建发布 ZIP 包 |
| 9 | 计算 SHA256 哈希 | 计算发布包哈希值用于签名 |
| 10 | 生成 Release Notes | 从 git 历史自动生成更新日志 |
| 11 | 生成 SLSA 出处文件 | 符合 SLSA v1.0 标准的供应链证明 |
| 12 | 生成证据包 | 生成 CI 证据包（始终运行） |
| 13 | 创建 GitHub Release | 发布到 GitHub Releases |
### Issue 标签器流程 (issue-labeler.yml)
| 步骤 | 名称 | 说明 |
|----|---------------|----------------------|
| 1 | Harden Runner | 安全加固 Runner，审计所有出站调用 |
| 2 | Checkout 代码 | 获取完整 git 历史 |
| 3 | Tag-ur-it | 自动标签匹配和人员指派 |
### Issue 总结流程 (issue-summary.yml)
| 步骤 | 名称 | 说明 |
|----|---------------|------------------------------------|
| 1 | Harden Runner | 安全加固 Runner，审计所有出站调用 |
| 2 | Checkout 代码 | 获取完整 git 历史 |
| 3 | 安装 Python 依赖 | 安装 openai 库 |
| 4 | Gitee AI 生成总结 | 使用 Qwen2.5-72B-Instruct 生成结构化总结并评论 |
### PR 标记器流程 (labeler.yml)
| 步骤 | 名称 | 说明 |
|----|-----------------|------------------------|
| 1 | Harden Runner | 安全加固 Runner，审计所有出站调用 |
| 2 | Checkout 代码 | 获取完整 git 历史 |
| 3 | PR Insights 标记器 | 大小/类别/风险分析，质量门禁检查，自动评论 |
### 标记陈旧流程 (stale.yml)
| 步骤 | 名称 | 说明 |
|----|---------------|----------------------|
| 1 | Harden Runner | 安全加固 Runner，审计所有出站调用 |
| 2 | 标记陈旧 Issues | 标记 60 天无活动的 Issues |
| 3 | 标记陈旧 PRs | 标记 60 天无活动的 PRs |
| 4 | 自动关闭 | 30 天后自动关闭标记的内容 |
## 安全保障措施
### 1. 安全加固
- 所有工作流使用 `step-security/harden-runner` 加固 Runner
- 出站流量审计（egress-policy: audit）
- 限制不必要的权限（最小权限原则）
### 2. 依赖项安全
- **dependency-review.yml**: 检测 PR 中的依赖项漏洞
- **Dependabot**: 自动依赖更新（在 .github/dependabot.yml 中配置）
- **SBOM 生成**: 在证据包中包含软件物料清单
### 3. 供应链安全
- **SLSA 出处文件**: 符合 SLSA v1.0 标准的供应链证明
- **证据包签名**: 使用 Sigstore 签名
- **源代码验证**: 可验证构建来源和触发方式
### 4. 多层扫描
- **CodeQL**: 代码层面的安全漏洞检测
- **OSSAR**: 开源静态分析
- **Scorecard**: 仓库安全和最佳实践评分
## 输出产物
每个工作流产生的输出：
| 工作流 | 输出产物 | 位置 |
|-----------------------|------------------------|-------------------------------|
| release.yml | ZIP 包、SLSA 出处文件、证据包、签名 | GitHub Releases |
| codeql.yml | SARIF 报告 | GitHub Security 标签页 |
| ossar.yml | SARIF 报告 | GitHub Security 标签页 |
| scorecard.yml | SARIF 报告、Scorecard 徽章 | GitHub Security / OpenSSF API |
| dependency-review.yml | PR 评论 | Pull Request |
| stale.yml | Issue/PR 标签、自动关闭 | Issues / Pull Requests |
| issue-labeler.yml | Issue 标签、指派 | Issues |
| issue-summary.yml | Issue 总结评论 | Issues |
| labeler.yml | PR 标签、总结评论、质量检查 | Pull Requests |
## 维护建议
1. **定期更新 Actions 版本**: 定期检查并更新使用的 GitHub Actions 版本
2. **监控定时任务**: 确保定时任务正常运行
3. **审查安全警报**: 及时处理 GitHub Security 标签页中的警报
4. **保持依赖项更新**: 使用 Dependabot 自动更新依赖
5. **管理 Issue 规则**: 定期审查和更新 .github/issue-rules.yml 配置以优化标签和指派规则
