Kubernetes 集群越管越多，”改配置靠 kubectl 手敲、上线靠人肉点按钮”的老路子迟早出事：谁改了什么、什么时候改的，事后根本查不到。GitOps 的解法很直接——把集群期望状态全部放进 Git 仓库，由 Argo CD 这样的持续部署控制器自动比对并收敛状态。本文从安装、第一个应用到自动同步与多环境管理，带你把 Argo CD 真正跑起来。
一、为什么持续部署需要 GitOps
传统 CI/CD 工具是”推送”模式：流水线拿着凭证从外部往集群里执行 kubectl apply，凭证散落在 CI 系统里，变更历史靠日志拼接，出了问题很难回答”集群现在到底应该是什么样”。GitOps 把方向反过来：Git 仓库是唯一事实来源，集群侧的控制器主动”拉取”并收敛状态。下面的对比可以直观看出两种模式的差异。
| 对比维度 | GitOps 拉取模式 | 传统推送模式 |
|---|---|---|
| 状态来源 | Git 仓库（唯一事实源） | 流水线变量与脚本 |
| 集群凭证 | 只留在集群内 | 分散在 CI 系统中 |
| 变更审计 | Git 提交历史天然可审计 | 依赖 CI 日志人工拼接 |
| 配置漂移 | 控制器自动发现并纠正 | 无人发现，逐渐腐化 |
| 回滚方式 | git revert 即可 | 重跑旧版本流水线 |
一句话总结：推送模式把”部署”当成流水线的最后一步，拉取模式把”部署”当成集群永不停止的自我收敛。
二、GitOps 的四大核心原则
CNCF 的 OpenGitOps 工作组给 GitOps 下过一套可落地的定义，记住四条即可：
- 声明式：整套系统必须用声明式描述（Kubernetes YAML、Helm values、Kustomize overlay），而不是命令式脚本。
- 版本化且不可变：期望状态保存在 Git 中，自带完整版本历史，任何修改都有据可查。
- 自动拉取：由集群内的 Agent 主动从 Git 拉取期望状态，不允许外部系统推着改。
- 持续调和：Agent 不断比对”实际状态”与”期望状态”，发现漂移就自动纠正。
三、Argo CD 核心概念速览
Argo CD 是 CNCF 毕业项目，也是目前最主流的 Kubernetes GitOps 持续部署工具。理解两组概念就能上手：资源模型上，Application 是最小部署单元，把”一个 Git 源”映射到”一个集群目标”；App Project 则用来限制应用能使用哪些仓库和集群，是多团队治理的抓手。状态模型上，每个应用有两条独立的状态线，日常排障基本围绕它们展开。
| 状态维度 | 取值 | 含义 |
|---|---|---|
| Sync Status | Synced | 实际状态已与 Git 期望状态一致 |
| Sync Status | OutOfSync | 集群与 Git 有差异，等待或需要同步 |
| Health Status | Healthy / Progressing | 资源运行正常 / 正在发布中 |
| Health Status | Degraded / Missing / Suspended | 副本异常 / 资源缺失 / 被人工暂停 |
四、安装 Argo CD 并登录 CLI
安装只需两条命令，把官方清单应用到独立的 argocd 命名空间即可。为了后续演示，顺便装好命令行工具并完成登录。
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# 安装 CLI（macOS 用 Homebrew，Linux 可从 GitHub Releases 下载二进制）
brew install argocd
# 本地端口转发后获取初始管理员密码并登录
kubectl port-forward svc/argocd-server -n argocd 8080:443
argocd admin initial-password -n argocd
argocd login localhost:8080 --username admin --insecure生产环境不要长期用端口转发：建议通过 Ingress 暴露 UI，登录后立即修改 admin 密码或直接接入 SSO/统一认证，并按项目划分权限。
五、部署第一个应用
Argo CD 里”部署一个应用”就是创建一个 Application CR。下面这个清单把 GitHub 上的示例仓库 guestbook 目录同步到集群的 guestbook 命名空间，是官方最经典的入门示例。
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: guestbook
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/argoproj/argocd-example-apps.git
targetRevision: HEAD
path: guestbook
destination:
server: https://kubernetes.default.svc
namespace: guestbook
syncPolicy:
syncOptions:
- CreateNamespace=true用 kubectl apply 提交后，在 UI 里能看到应用处于 OutOfSync 状态，点击 Sync 或执行 argocd app sync guestbook 即可完成首次部署。source 部分的三要素——仓库地址、目标修订版本、路径——就是 GitOps 的”指针”，改指针就等于改发布版本。
六、自动同步、自愈与修剪
手动点 Sync 只适合试点。真正的 GitOps 要求配置合并进 Git 后自动生效，这就用到 automated 同步策略：
syncPolicy:
automated:
prune: true # Git 里删掉的资源，集群里也删掉
selfHeal: true # 有人手动改了集群，自动恢复成 Git 的样子
retry:
limit: 5
backoff:
duration: 5s
factor: 2
maxDuration: 3m两个开关都要敬畏。prune 意味着”删 Git 里的 YAML 就是删生产资源”，合并前务必看清 diff；selfHeal 会让任何绕过 Git 的手动变更（kubectl edit、kubectl scale）被悄悄打回——这不是 bug，而是 GitOps 纪律的体现：想改集群，先改 Git。
七、对接 Helm 与 Kustomize 做多环境
Argo CD 原生支持 Helm、Kustomize、Jsonnet 等多种配置格式，不需要在流水线里先渲染成裸 YAML。如果团队已经在用 Helm Chart 打包发布，直接在 source 里声明 chart 与 values 即可；多环境的差异化配置则推荐用 Kustomize 的 overlay 机制，dev、staging、prod 各一个目录，base 复用、差异收敛。
spec:
source:
repoURL: https://charts.example.com
chart: myapp
targetRevision: 1.4.2
helm:
releaseName: myapp
valueFiles:
- values-prod.yaml环境数量变多后，再按”每个环境一个 Application”的方式去维护会非常痛苦，业界通行做法是 App of Apps（用一个父应用管理一堆子应用清单）或 ApplicationSet（用模板批量生成应用），这两者可以叠加使用，建议在应用超过 10 个之后再引入。
八、与 CI 的分工边界
GitOps 落地后最常见的困惑是”那 CI 还要不要”。答案是分工不变：CI 负责”构建与验证”，产物是一个不可变的新镜像 tag；CD 负责”把新版本收敛到集群”。以 GitHub Actions 或 Jenkins 流水线 为例，流水线跑完测试后只做一件事——用新镜像 tag 更新 Git 仓库里的配置（提交或发 PR），之后的事全部交给 Argo CD。这个”改 Git”的动作可以用 Webhook 触发 argocd app sync 实现秒级生效，也可以放着让轮询自动发现。
九、回滚与日常排错
GitOps 的回滚方式有两种：回滚 Git（改回旧 tag 再合并）是首选，因为它让历史与集群始终一致；紧急情况下也可以用 CLI 直接回滚。注意一个高频坑：自动同步开启时，CLI 回滚会被下一次调和覆盖，必须先暂停同步。
# 查看部署历史
argocd app history guestbook
# 紧急回滚：先停自动同步，再回滚到指定版本
argocd app set guestbook --sync-policy none
argocd app rollback guestbook 3
# 排错三板斧：看差异、看事件、看控制器日志
argocd app diff guestbook
argocd app get guestbook
kubectl -n argocd logs deploy/argocd-application-controller --tail=100日常排障优先看应用的事件流（UI 里 Resources/Event 面板），80% 的同步失败是 YAML 校验错误、镜像拉不到或 RBAC 权限不足，控制器日志只在诡异问题 Last resort 时才需要翻。
十、生产落地最佳实践与常见坑
| 常见坑 | 典型现象 | 对策 |
|---|---|---|
| 密钥明文提交 Git | 仓库泄露即生产泄露 | 用 Sealed Secrets / External Secrets 管理，参见站内 ConfigMap 与 Secret 实战 |
| 绕过 Git 手改集群 | 改动被 selfHeal 静默打回 | 所有变更走 PR，紧急操作也必须事后补提交 |
| Application 数量失控 | 上百个 CR 管不过来 | App of Apps / ApplicationSet 统一管理 |
| 回滚被自动同步覆盖 | rollback 后瞬间又变回去 | 先 –sync-policy none 再 rollback，修复后恢复 |
| diff 噪音大 | 每次都显示无关字段漂移 | 配置 mutating webhook / ignoreDifferences 忽略已知抖动字段 |
另外建议给 Git 仓库开启分支保护：main 分支禁止直接 push，所有变更必须走 PR 评审。GitOps 的安全性一半来自凭证收敛，另一半就来自”合并即发布”这道不可绕过的评审关口。
十一、总结
落地 Argo CD 不需要一步到位：先用单个非核心应用跑通”Git 合并即部署”，验证同步策略与回滚流程；再把核心服务迁入，引入 App of Apps 治理应用规模；最后接上通知（Slack/钉钉）与镜像自动升级，形成完整闭环。当”集群里运行的东西”与”Git 里提交的东西”永远一致时，持续部署才真正从体力活变成可审计、可回滚的日常操作。
