vault backup: 2026-05-18 00:17:59

hhs/MS/05-部署运维/03-CICD与GitOps.md

@@ -1,176 +1,205 @@
 ---
-tags: [microservice, cicd, gitops, github-actions, argocd]
-create time: 2026-05-05
+tags: [microservice, cicd, gitops, github-actions, argocd, kubernetes, helm]
+create time: 2026-05-05 14:30
 ---
 
-# CI/CD 与 GitOps
+# 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
-    CODE["代码提交"] --> TEST["测试 & 静态分析"]
-    TEST --> SCAN["安全扫描"]
-    SCAN --> BUILD["构建镜像"]
-    BUILD --> PUSH["推送仓库"]
-    PUSH --> STAGING["Staging 验证"]
-    STAGING -->|"人工审批"| PROD["Production 部署"]
-    
-    style CODE fill:#e3f2fd
-    style TEST fill:#fff3e0
-    style SCAN fill:#fce4ec
-    style BUILD fill:#e8f5e9
-    style PUSH fill:#f3e5f5
-    style STAGING fill:#e0f7fa
-    style PROD fill:#c8e6c9
-```
+    Dev["开发者 push"] --> CI["GitHub Actions\n(CI: 测试→构建→Push镜像)"]
+    CI -->|"新镜像"| REG["Container Registry"]
 
-## CI/CD 设计原则
+    Dev2["开发者 PR manifest"] --> MANIFEST["Git Manifest Repo"]
 
-| 原则 | 说明 |
-|------|------|
-| **一次构建，多处部署** | 镜像不随环境重新编译，只改 K8s ConfigMap/环境变量 |
-| **语义化版本** | 镜像 tag 用 `v1.2.3`，tag 即版本溯源 |
-| **路径过滤** | 只对相关服务的代码变更触发构建 |
-| **Commit SHA 作为镜像 tag** | 保证精确回滚 |
-| **分阶段部署** | Staging → Production 的审批关卡不可跳过 |
-
-## GitHub Actions Pipeline 实战
-
-```yaml
-# .github/workflows/deploy.yml
-name: Deploy order-service
-on:
-  push:
-    branches: [main]
-    paths:
-      - "services/order/**"
-
-env:
-  REGISTRY: registry.example.com
-  IMAGE: order-service
-
-jobs:
-  # ========== Stage 1: Build & Test ==========
-  build-and-test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      
-      - name: Run tests
-        run: make test
-        
-      - name: Security scan
-        uses: aquasecurity/trivy-action@master
-        with:
-          scan-type: 'fs'
-          severity: 'CRITICAL,HIGH'
-      
-      - name: Build Docker image
-        run: |
-          docker build -t ${{ env.REGISTRY }}/${{ env.IMAGE }}:${{ github.sha }} \
-            -t ${{ env.REGISTRY }}/${{ env.IMAGE }}:v${{ github.run_number }} \
-            -f services/order/Dockerfile \
-            services/order
-      
-      - name: Push to registry
-        run: |
-          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login -u ${{ secrets.REGISTRY_USER }} --password-stdin
-          docker push ${{ env.REGISTRY }}/${{ env.IMAGE }}:${{ github.sha }}
-          docker push ${{ env.REGISTRY }}/${{ env.IMAGE }}:v${{ github.run_number }}
-
-  # ========== Stage 2: Deploy to Staging ==========
-  deploy-staging:
-    needs: build-and-test
-    runs-on: ubuntu-latest
-    environment: staging
-    steps:
-      - name: Deploy to staging
-        run: |
-          kubectl set image deployment/order-service \
-            order=${{ env.REGISTRY }}/${{ env.IMAGE }}:${{ github.sha }} \
-            --namespace=staging
-          kubectl rollout status deployment/order-service \
-            --namespace=staging --timeout=120s
-
-  # ========== Stage 3: Deploy to Production ==========
-  deploy-production:
-    needs: deploy-staging
-    runs-on: ubuntu-latest
-    environment: production
-    steps:
-      - name: Canary release (10% → 50% → 100%)
-        run: |
-          kubectl patch canary order-service --type merge \
-            -p '{"spec":{"weight":10}}'
-          
-          # ... 等待监控确认，逐步放大流量
-          echo "Monitor metrics before proceeding..."
-```
-
-## GitOps 工作流
-
-GitOps 的核心思想：**K8s 集群的状态 = Git 仓库中声明式配置的当前状态。**
-
-```mermaid
-flowchart LR
-    Dev["开发者 PR"] -->|"修改 K8s manifest"| Git[(Git Repo)]
-    
     subgraph Cluster["K8s Cluster"]
-        Argo["ArgoCD / Flux"] -->|同步| K8sState["Pod/Service/ConfigMap"]
+        Argo["ArgoCD"] -->|"自动同步"| WORKLOADS["Pod / Service / ..."]
     end
-    
-    Git -.->|Webhook| Argo
-    
-    Argo -->|"检测到差异"| Diff{"状态一致?"}
-    Diff -- 否 --> Sync["自动同步到 K8s ✅"]
-    Diff -- 是 --> OK["已一致 ⏸️"]
-    
-    style Git fill:#e3f2fd
+
+    MANIFEST -.->|Watch 变动| Argo
+
+    style CI fill:#e8f5e9
     style Argo fill:#fff3e0
-    style K8sState fill:#e8f5e9
+    style WORKLOADS fill:#e3f2fd
 ```
 
-### 与传统 CI/CD 的区别
+**核心分工**：**CI/CD 管"怎么建"**（构建、扫描、推送镜像），**GitOps 管"怎么维持"**（Git 声明 → 集群自动同步）。
 
-| 维度 | 传统 CI/CD | GitOps |
-|------|-----------|--------|
-| **部署驱动** | CI 服务器主动推送 | Git 仓库变动触发拉取 |
-| **状态源** | CI pipeline 的历史记录 | Git commit history |
-| **回滚方式** | 回到上一次的 pipeline | `git revert` + 自动同步 |
-| **漂移检测** | 通常无 | 持续比对，自动修复不一致 |
-| **代表工具** | Jenkins / GitLab CI / GitHub Actions | ArgoCD / Flux |
+---
 
-### GitOps 的优势
+## 标签策略速查
 
-1. **审计完整** — 所有变更都在 Git 中可追溯
-2. **回滚简单** — `git revert` 就是回滚操作
-3. **自修复** — ArgoCD 持续监测并修复集群状态偏离
-4. **多人协作** — 通过 PR Review 流程管控配置变更
+| Tag | 示例 | 用途 | 安全性 |
+|-----|------|------|--------|
+| `latest` | `nginx:latest` | ❌ 开发调试 | ❌ 可被覆盖，不可回滚 |
+| 语义版本 | `v1.2.3` | ✅ 人类阅读、快速参考 | ⚠️ 仍可被更新覆盖 |
+| Commit SHA | `sha256:a1b2c3d` | ✅ 机器精确引用、精确回滚 | ✅ 全局唯一、不可变 |
+| Run Number | `v123` | ✅ GitHub Actions 快速参考 | ⚠️ 单次 workflow 内唯一 |
 
-## Helm — K8s 的包管理
+> **推荐**：同时打 `sha256:{commit}` + `v{run_number}`。生产回滚优先用 Commit SHA。
 
-当每个服务都有几十行 YAML 时，Helm 能大幅简化部署：
+---
 
+## 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
-# 创建 Chart 模板
-helm create order-service
+# 查看 workflow 运行记录
+gh run list --workflow deploy.yml
 
-# 使用 values.yaml 参数化部署
-helm upgrade --install order-service ./charts/order-service \
-  --set image.tag=v1.2.3 \
-  --set replicas=3 \
-  --namespace=production
+# 手动触发 workflow
+gh workflow run deploy.yml --ref main
 ```
 
-> [!tip] 为什么需要 Helm？
-> 
-> 没有 Helm 时，每个服务都要手动维护 Deployment、Service、Ingress、ConfigMap 等几十个 YAML 文件。Helm 允许你把通用模板抽出来，只在 values.yaml 里改差异化配置。
+### 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 历史
+```
+
+---
 
 ## 关联笔记
 
-- [[05-部署运维/01-容器化]] — Docker 镜像构建是 CI/CD 的第一步
-- [[05-部署运维/02-Kubernetes]] — K8s 是部署的目标平台
-- [[05-部署运维/04-SRE实践]] — 错误预算影响发布策略
+- [[01-容器化]] — Docker 镜像构建是 CI/CD 的第一步
+- [[02-Kubernetes]] — K8s 是部署的目标平台
+- [[04-SRE实践]] — 错误预算影响发布策略
+- [[05-监控告警]] — Prometheus + Alertmanager 为 Canary 提供指标支撑