第三章：核心功能需求（Core Functional Requirements）

3.1 仓库连接与触发（Repository Integration & Trigger）

功能目标

实现与主流代码仓库（GitHub / GitLab / Gitee）的一键接入和触发。

功能点

• OAuth2 授权接入

  • 用户通过“连接 GitHub”按钮完成授权。
  • 支持私有仓库（需 Token）。

• 触发条件

  • push 到分支；
  • tag 匹配版本号；
  • PR 合并；
  • 定时（Cron）；
  • 手动执行。

• 事件过滤

  • 按分支、路径、提交信息关键词。

• 触发记录

  • 保存在 trigger_events 表，供审计与追踪。

验收标准

• 能正确接收来自 GitHub Webhook 的事件；
• 对非法 Token 拒绝请求；
• 能支持并行构建触发；
• 所有触发事件带唯一 traceId。

3.2 构建与打包（Build & Package）

功能目标

实现跨语言的自动化构建流程。

功能点

• 预设构建模板

  • Go: go build -o app .
  • Node.js: npm ci && npm run build
  • Python: pip install -r requirements.txt
  • Java: mvn package -DskipTests

• 依赖缓存

  • 缓存路径可定义；
  • 基于 Hash 生成缓存 Key；
  • 构建时间减少 ≥ 40%。

• 构建镜像

  • 可选择基础镜像（如 golang:1.23, node:20-alpine）。

• 产物打包

  • 支持 tar, zip, binary, docker image。
  • 自动上传至 Artifact Store。

• 版本号生成

  • 优先取 Git Tag；
  • 无 Tag 时自动生成 v0.1.<commitSHA>。

验收标准

• 构建失败时应输出完整日志；
• 可缓存依赖并验证缓存命中率；
• 每次构建产物均有唯一 hash；
• 上传成功后在 UI 可查看并下载。

3.3 制品管理（Artifact Management）

功能目标

管理构建输出的制品、版本与生命周期。

功能点

• 版本记录

  • 版本号、构建来源、提交人。

• 下载与访问

  • 提供带签名的下载链接；
  • 可设置下载次数上限。

• 生命周期策略

  • 默认保留 30 天；
  • 可自定义清理规则。

• 安全

  • 每个 Artifact 生成 SHA256 校验；
  • 支持镜像签名（cosign）。

验收标准

• 所有制品均可追溯到具体 PipelineRun；
• 删除旧版本后，回滚不可使用；
• 上传 1GB 制品在 30 秒内完成。

3.4 部署目标（Deployment Targets）

功能目标

支持多形态部署环境：K8s、SSH 主机、Docker、Serverless。

K8s 部署

• 解析 YAML（支持 Helm 模板）；
• 可设置 Namespace；
• 自动注入镜像标签；
• 回滚到上次成功版本；
• 可通过 readinessProbe 验证健康。

SSH 部署

• 支持批量主机；
• 上传打包文件；
• 执行 pre / post 钩子；
• 支持 rootless 模式。

Docker 部署

• 远程拉取镜像；
• 重启目标容器；
• 支持 Compose 文件。

Serverless 部署

• 自动打包 zip；
• 上传到 AWS Lambda / Cloud Run；
• 配置环境变量。

验收标准

• 多目标并行部署时互不干扰；
• 部署日志实时可见；
• 错误时触发自动回滚；
• 每个部署均有唯一部署 ID。

3.5 环境与配置管理（Environment & Configuration）

功能点

• 环境分层：dev / staging / prod；
• 支持变量覆盖；
• 环境变量注入（系统 + 用户自定义）；
• 配置文件模板化（${VAR} 替换）；
• 变量作用域：Global → Project → Environment；
• 支持 Secret 引用（如 ${{ secrets.DB_PASS }}）。

验收标准

• 各环境变量隔离；
• Secret 值不在日志中暴露；
• 更新变量可触发重新部署。

3.6 密钥与安全策略（Secret Management & Security Policy）

功能点

• 加密存储（AES-256-GCM）；

• 按项目或环境作用域；

• Secret 注入方式：

  • 环境变量；
  • 文件挂载（如 .env）；

• 授权控制（仅 Maintainer 可修改）；

• 审计追踪修改历史；

• 失效策略：过期自动销毁。

验收标准

• 密钥明文不应出现在任何日志；
• 修改密钥立即生效；
• 删除密钥不影响历史构建。

3.7 部署策略与回滚（Deployment & Rollback）

功能点

• 策略类型

  • Rolling Update（滚动更新）
  • Blue-Green（蓝绿）
  • Canary（金丝雀）

• 自动回滚触发

  • 健康检查失败；
  • Error Rate > 5%；
  • Manual rollback。

• 版本历史

  • 保留最近 N 次部署；
  • 可快速恢复。

验收标准

• 部署失败 30 秒内可完成回滚；
• 回滚版本一致性验证通过；
• UI 展示部署差异信息。

3.8 日志与审计（Logging & Audit）

功能点

• 实时日志流（WebSocket）；
• 日志分级（INFO/WARN/ERROR）；
• 审计记录操作（trigger, deploy, rollback）；
• 可按用户/项目筛选；
• 导出 CSV/PDF。

验收标准

• 所有操作均有唯一 auditId；
• 日志存储 90 天；
• 搜索性能 < 1 秒。

3.9 通知与集成（Notifications & Integrations）

功能点

• 通知渠道：Email / Slack / 飞书 / Webhook；
• 通知事件：构建成功/失败、部署完成、审批请求；
• 模板可自定义；
• Webhook 支持签名校验。

验收标准

• 可配置多种通知方式；
• 失败事件必须触发告警；
• 通知延迟 < 3 秒。

3.10 控制台与 UI 功能（Console & UI）

页面模块

1. Dashboard

   • 显示近期构建、部署状态；
   • 成功率统计、平均耗时。

2. Projects

   • 项目列表；
   • 按状态筛选。

3. Pipelines

   • 历史流水线；
   • 每步执行状态。

4. Artifacts

   • 制品列表、下载、删除；
   • 显示版本与来源。

5. Environments

   • 环境变量与部署历史；
   • 一键回滚。

6. Settings

   • 成员管理、通知、策略。

7. Runners

   • 在线状态、并发数、版本。

验收标准

• 页面加载时间 < 2s；
• 所有状态自动刷新；
• 提供暗黑模式；
• 可移动端适配。