---
tags: [microservice, cicd, gitops, github-actions, argocd, kubernetes, helm]
create time: 2026-05-05 14:30
---

# CI/CD 与 GitOps — 参考手册

## 概述

微服务架构下的自动化交付体系。**一次构建，多处部署**是核心哲学——镜像不随环境重新编译，只改 K8s ConfigMap。本文档是总入口：顶层概念、决策矩阵、速查表见本页；详细教程和实操指南在子文档中。

---

## 快速导航

| 主题 | 定位 | 文档 |
|------|------|------|
| Pipeline 搭建 | **教程**：从 0 到 1 写出一个能跑的流水线 | [[03-CICD与GitOps/01-CICD基础与实践]] |
| GitOps & ArgoCD | **教程**：Push → Pull 架构迁移、Application CRD | [[03-CICD与GitOps/02-GitOps与ArgoCD]] |
| Helm 模板 | **操作手册**：values.yaml、Go 模板、多环境覆盖 | [[03-CICD与GitOps/03-Helm模板管理]] |
| 安全 & 发布策略 | **决策指南**：Secret 选型、Canary vs Blue-Green | [[03-CICD与GitOps/04-安全与发布策略]] |

---

## 架构全景

```mermaid
flowchart LR
    Dev["开发者 push"] --> CI["GitHub Actions\n(CI: 测试→构建→Push镜像)"]
    CI -->|"新镜像"| REG["Container Registry"]

    Dev2["开发者 PR manifest"] --> MANIFEST["Git Manifest Repo"]

    subgraph Cluster["K8s Cluster"]
        Argo["ArgoCD"] -->|"自动同步"| WORKLOADS["Pod / Service / ..."]
    end

    MANIFEST -.->|Watch 变动| Argo

    style CI fill:#e8f5e9
    style Argo fill:#fff3e0
    style WORKLOADS fill:#e3f2fd
```

**核心分工**：**CI/CD 管"怎么建"**（构建、扫描、推送镜像），**GitOps 管"怎么维持"**（Git 声明 → 集群自动同步）。

---

## 标签策略速查

| Tag | 示例 | 用途 | 安全性 |
|-----|------|------|--------|
| `latest` | `nginx:latest` | ❌ 开发调试 | ❌ 可被覆盖，不可回滚 |
| 语义版本 | `v1.2.3` | ✅ 人类阅读、快速参考 | ⚠️ 仍可被更新覆盖 |
| Commit SHA | `sha256:a1b2c3d` | ✅ 机器精确引用、精确回滚 | ✅ 全局唯一、不可变 |
| Run Number | `v123` | ✅ GitHub Actions 快速参考 | ⚠️ 单次 workflow 内唯一 |

> **推荐**：同时打 `sha256:{commit}` + `v{run_number}`。生产回滚优先用 Commit SHA。

---

## Pipeline 阶段对照

| 阶段 | 做什么 | 工具举例 | 详见 |
|------|--------|---------|------|
| 触发过滤 | 只对相关代码变更构建 | `paths`, `pull_request` | [[03-CICD与GitOps/01-CICD基础与实践]] |
| 测试 | 单元测试 + 集成测试 | Jest, pytest, go test | [[03-CICD与GitOps/01-CICD基础与实践]] |
| 安全扫描 | 镜像/依赖漏洞检测 | Trivy, Snyk | [[03-CICD与GitOps/04-安全与发布策略]] |
| 构建+推送 | Docker image 构建并推仓库 | docker build/push | [[03-CICD与GitOps/01-CICD基础与实践]] |
| Staging 验证 | 预发布环境冒烟测试 | kubectl set image | [[03-CICD与GitOps/01-CICD基础与实践]] |
| Production | 灰度放量，人工审批关卡 | Canary, Blue-Green | [[03-CICD与GitOps/04-安全与发布策略]] |

---

## 部署驱动模式对比

| 维度 | 传统 CI/CD (Push) | GitOps (Pull) |
|------|------------------|---------------|
| 部署驱动 | CI 服务器主动推送 | Git 仓库变动触发拉取 |
| 状态源 | CI pipeline 历史 | Git commit history |
| 漂移检测 | 通常无 | 持续比对，自动修复 |
| 安全边界 | CI 需直连 K8s | ArgoCD 集群内运行 |
| 回滚方式 | 回到上一次的 pipeline | `git revert` + 自动同步 |
| 代表工具 | Jenkins, GitHub Actions | ArgoCD, Flux |

> **选型建议**：团队规模 < 20 人时 Push 模式足够。≥ 50 人或多环境场景建议迁移到 GitOps。

---

## Secret 管理方案对比

| 方案 | 适用场景 | 优点 | 缺点 |
|------|---------|------|------|
| K8s 原生 Secret | 小规模内部团队 | 零成本，开箱即用 | etcd 明文存储 |
| ESO (External Secrets) | 已有 Vault / AWS SSM | Git 中无密文 | 需维护额外组件 |
| SOPS + sealed-secrets | ArgoCD 用户 | 加密文件可提交到 Git | 需管理 PKI |
| 云厂商 Secret Manager | 深度绑定单一云平台 | 审计完善 | 平台锁定 |

> **渐进路径**：K8s Secret → 接入云厂商 Secret Manager → 引入 ESO 实现多云解耦。

---

## 发布策略对比

| 维度 | Rolling Update | Canary | Blue-Green | Experiment |
|------|---------------|--------|------------|------------|
| 停机时间 | 可能有抖动 | 零 | 零 | 零 |
| 复杂度 | 低 | 中 | 中高 | 高 |
| 资源消耗 | 1x | 1.5x | 2x | 2x+ |
| 回滚速度 | 慢（完整重建） | 快（切流量） | 秒级 | 秒级 |
| 典型场景 | 内部服务 | 用户-facing | 重要版本 | A/B 测试 |

---

## 编排工具选型

| 服务规模 | 推荐方案 | 理由 |
|----------|---------|------|
| < 10 个服务 | Kustomize / 裸 YAML | 复杂度高于收益 |
| 10~50 个服务 | Helm | 模板复用价值明显 |
| > 50 个服务 | Helm + Kustomize overlays | Helm 管模板，Kustomize 管环境差异 |

---

## 关键决策流程图

### Secret 选型决策

```mermaid
flowchart TD
    START["开始选型"] --> SIZE["团队 < 20人?"]
    SIZE -- 是 --> K8SSECRET["✅ K8s 原生 Secret"]
    SIZE -- 否 --> CLOUD["深度绑定云厂商?"]
    CLOUD -- 是 --> SECRETMGR["✅ Cloud Secret Manager"]
    CLOUD -- 否 --> GITOPS["使用 ArgoCD?"]
    GITOPS -- 是 --> SOPS["✅ SOPS + sealed-secrets"]
    GITOPS -- 否 --> ESO["✅ External Secrets Operator"]

    style K8SSECRET fill:#e8f5e9
    style SECRETMGR fill:#e3f2fd
    style SOPS fill:#fff3e0
    style ESO fill:#f3e5f5
```

### 渐进式采纳路径

```mermaid
flowchart LR
    STEP1[("1. 自动化构建+Push")] --> STEP2[("2. Staging + 审批")] --> STEP3[("3. GitOps, Git 即真相源")]

    style STEP1 fill:#e8f5e9
    style STEP2 fill:#fff3e0
    style STEP3 fill:#e3f2fd
```

---

## 附录：常用命令速查

### GitHub Actions
```bash
# 查看 workflow 运行记录
gh run list --workflow deploy.yml

# 手动触发 workflow
gh workflow run deploy.yml --ref main
```

### kubectl
```bash
# 滚动更新指定镜像
kubectl set image deployment/order-service \
  order=registry.example.com/order-service:v1.2.3 -n production

# 查看 rollout 状态
kubectl rollout status deployment/order-service -n production --timeout=120s

# 回滚到上一版本
kubectl rollout undo deployment/order-service -n production
```

### ArgoCD CLI
```bash
argocd app sync order-service                          # 手动同步
argocd app diff order-service                          # Git vs 实际差异
argocd app history order-service                       # 同步历史
argocd app rollback order-service                      # 回滚
```

### Helm
```bash
helm upgrade --install order-service ./charts/order-service -n production
helm upgrade --install order-service ./charts/order-service -n staging --set image.tag=v1.2.4-dev
helm template order-service ./charts/order-service       # 仅渲染，不安装
helm history order-service -n production                 # Release 历史
```

---

## 关联笔记

- [[01-容器化]] — Docker 镜像构建是 CI/CD 的第一步
- [[02-Kubernetes]] — K8s 是部署的目标平台
- [[04-SRE实践]] — 错误预算影响发布策略
- [[05-监控告警]] — Prometheus + Alertmanager 为 Canary 提供指标支撑