GitOps核心原理：声明式配置与Git作为唯一真相源

1. 什么是 GitOps？不是新名词，而是运维思维的“归位”

你肯定听过 DevOps——它把开发和运维拧成一股绳，用自动化流水线把代码从 IDE 直接送到生产服务器上；你也可能用过 MLOps，它把机器学习模型的训练、验证、上线、监控全链路串起来，让算法工程师不再只管调参，也得对线上效果负责。但当你在 Kubernetes 集群里手动执行kubectl apply -f config.yaml，或者半夜被告警叫醒去修复一个被误删的 ConfigMap 时，有没有想过：为什么我们能用 Git 管理几千行 Python 代码，却要靠人肉kubectl edit去改生产环境的配置？这就是 GitOps 要回答的根本问题。

GitOps 不是又一个带“Ops”的 buzzword，它是一次运维权力的重新分配——把基础设施的“定义权”和“决策权”从运维人员的手动操作、临时脚本、甚至共享文档里，彻底收回到 Git 仓库这个唯一可信源（Single Source of Truth）中。它不发明新工具，而是把 Git 这个程序员每天用十几次的协作系统，变成整个云原生基础设施的“操作系统内核”。你提交一次 PR，不只是改了应用逻辑，更是向集群发出了一条不可篡改的“宪法修正案”：从此刻起，这个命名空间里的所有 Deployment 必须是 v1.2.3 版本，Ingress 必须启用 TLS 1.3，ServiceAccount 必须绑定特定 RBAC 规则。集群本身会持续“阅读”这份宪法，并自动执行、校验、修复——这才是 GitOps 的灵魂：声明式 + 持续调谐（Continuous Reconciliation）。

我第一次在真实项目里落地 GitOps 是给一家做智能客服 SaaS 的客户做灾备重构。他们之前用 Ansible 脚本批量部署几十个 Kubernetes 集群，每次版本升级都要人工核对 200+ 行 YAML 变更，出过三次因漏改一个 namespace 导致灰度流量全部打到旧集群的事故。改成 GitOps 后，我们把所有集群的 Helm Release 清单、Kustomize base/overlays、甚至 Prometheus 告警规则都放进一个私有 Git 仓库。运维同学只需要在 GitHub 上点开 PR，看一眼 diff 就知道这次变更影响哪几个环境、修改了哪些资源类型、是否包含敏感字段（比如 Secret 的 base64 值），然后点击 Merge。5 分钟后，Argo CD 自动拉取变更、校验签名、执行部署、等待健康检查通过——整个过程像合并一段业务代码一样自然。最让我意外的是，开发同学开始主动给 infra 目录提 PR，因为他们发现改一个 ingress host 名字，比找运维开权限、等排期、再手动执行命令快得多。GitOps 的本质，是让“基础设施即代码”这句话真正落地为一种可协作、可审计、可回滚的日常实践，而不是挂在墙上的流程图。

2. GitOps 的核心设计与思路拆解：为什么必须是 Git？为什么必须是声明式？

2.1 为什么 Git 是不可替代的“唯一真相源”？

很多人第一反应是：“用数据库存配置不行吗？用 Consul 或 Etcd 不更实时？” 这是个好问题，但恰恰暴露了对 GitOps 本质的误解。GitOps 的核心诉求从来不是“快”，而是“可追溯、可协作、可验证、可回滚”。我们来逐条拆解：

• 可追溯（Auditability）：Git 的 commit hash 是天然的时间戳+内容指纹。当线上出现故障，你不需要翻 Slack 记录或问“谁昨天改了 config？”，直接git blame config/nginx-ingress.yaml就能看到每一行是谁、什么时候、为什么这么改，附带完整的 commit message 和关联的 Jira ticket。而数据库记录只有“最后更新时间”，Consul 的 key-value 变更日志是二进制流，无法语义化解读。

• 可协作（Collaboration）：Pull Request 是现代软件工程最成熟的协作范式。一个网络策略变更，安全团队可以 Review 是否开放了高危端口，SRE 团队可以确认是否符合基线标准，开发团队能理解这个变更如何影响自己的服务。这种基于 diff 的异步评审，远比“所有人挤在 Zoom 里听运维念 YAML”高效且可靠。我见过最典型的反例：某金融客户用 Jenkins Pipeline 直接调用 Terraform apply，所有配置变更都藏在 pipeline 脚本里。当需要回滚时，他们发现脚本里硬编码了环境变量，而那个变量值在三个月前的某次 CI 失败日志里才出现过。

• 可验证（Verifiability）：Git 支持 GPG 签名、分支保护策略（如 require 2 reviewers）、commit rule（如 Conventional Commits）。这意味着你可以强制要求：所有生产环境变更必须由 SRE 主管签名，所有涉及 Secret 的 PR 必须经过安全扫描，所有 Helm Chart 升级必须包含BREAKING CHANGE:标注。这些规则在数据库或配置中心里实现成本极高，而在 Git 中是开箱即用的能力。

• 可回滚（Reversibility）：git revert <commit>是原子操作，它生成一个新 commit 来抵消旧变更，保留完整历史。而数据库 rollback 可能破坏外键约束，Etcd 的 delete 操作不可逆。更重要的是，GitOps 工具（如 Argo CD）的回滚就是git reset --hard <old-commit>+git push，整个集群状态会在几分钟内恢复到指定版本——这比从备份恢复 etcd 集群快一个数量级。

提示：GitOps 不等于“把 YAML 文件扔进 Git 就完事”。真正的 GitOps 要求 Git 仓库结构本身体现环境治理逻辑。例如，我们团队强制采用environments/<env>/clusters/<cluster>/applications/目录结构，每个环境目录下有kustomization.yaml定义该环境所有应用的基线版本，sync-policy.yaml定义同步频率和超时策略。这样，git log environments/prod/就是生产环境的完整变更史，无需任何额外工具。

2.2 为什么声明式（Declarative）是 GitOps 的技术基石？

这是最容易被忽略的关键点。很多团队尝试 GitOps 时，第一步就走偏：他们把 Ansible Playbook、Shell 脚本、甚至kubectl create命令的输出结果塞进 Git 仓库。这看似“用了 Git”，实则是披着 Git 外衣的“脚本运维”，完全违背 GitOps 原则。

声明式的核心在于：你只描述“系统应该是什么状态”，而不关心“如何达到那个状态”。举个具体例子：

# 声明式：告诉集群“我要一个 3 副本的 Nginx，带健康检查” apiVersion: apps/v1 kind: Deployment metadata: name: nginx spec: replicas: 3 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:1.21 livenessProbe: httpGet: path: /healthz port: 80

# 命令式：告诉集群“现在去创建一个 Pod，再创建一个 Service，再创建一个 Ingress...” kubectl run nginx --image=nginx:1.21 --replicas=3 kubectl expose deployment nginx --port=80 --type=ClusterIP kubectl create ingress nginx --rule="nginx.example.com/*=nginx:80"

两者的根本区别在于状态收敛能力。声明式配置下，GitOps 控制器（如 Argo CD）会持续对比集群当前状态（Actual State）和 Git 中定义的目标状态（Desired State）。如果有人手动删除了一个 Pod，控制器会在几秒内发现差异并自动重建；如果有人kubectl scale deploy nginx --replicas=5，控制器会立刻把它缩回 3 个。这种“自愈”能力，是命令式脚本永远无法提供的——脚本只执行一次，执行完就结束，它不会持续守护。

我踩过的最深的坑，是在一个混合云项目里误用了命令式思维。当时为了快速上线，我们把helm install生成的 release manifest 直接kubectl get -o yaml > manifest.yaml存入 Git。结果某天运维同学手动helm upgrade了 chart 版本，Git 里的文件没更新。Argo CD 发现集群状态和 Git 不一致，但它无法判断该“回滚到 Git 版本”还是“升级到集群版本”，只能报错。后来我们彻底重构：所有 Helm Release 都用 Helm Controller 管理，Git 中只存HelmReleaseCRD，它声明“我要安装 bitnami/nginx chart v10.0.0”，具体渲染和部署由 Helm Controller 完成。这样，Git 始终只存意图，不存结果。

2.3 GitOps 的两种落地模型：Pull vs Push，不是选择题，而是演进路线

很多文章把 Pull 和 Push 模型并列对比，仿佛让你选一个。但在真实世界里，它们是不同成熟度阶段的必然选择，强行跳过 Push 直接上 Pull，就像让新手不学自行车直接骑摩托。

Push 模型（GitHub Actions / GitLab CI）的本质是“自动化脚本”。它的工作流是：代码提交 → CI 流水线触发 → 执行kubectl apply -f infra/prod/→ 部署完成。它最大的优势是零学习成本：如果你已经会写 GitHub Actions，加几行 kubectl 命令就能跑起来。我们给初创团队做 PoC 时，通常 2 小时就能搭好一套 Push GitOps，让他们看到“改一行 YAML 就自动上线”的魔力。

但它的致命缺陷是单向通道：CI 流水线只知道“推”，不知道“拉”。它无法感知集群是否被手动修改，无法自动修复 drift，也无法提供可视化状态视图。这就像你给家里装了个智能门锁，但锁本身没有联网，你只能用手机 App 发送“开锁”指令，却不知道门是不是被别人用钥匙打开了。

Pull 模型（Argo CD / Flux）的本质是“集群自治”。它在集群内部署一个 Operator，这个 Operator 像个尽职的图书管理员，24 小时盯着 Git 仓库。一旦发现新 commit，它就去拉取、解析、计算差异、执行变更、等待健康检查、报告状态。最关键的是，它会持续轮询：即使没人提交代码，它也会每 3 分钟检查一次集群当前状态是否匹配 Git 中的 Desired State。如果发现不匹配（比如有人kubectl delete pod nginx-xxx），它会立刻重建 Pod。这才是 GitOps 的“自愈”灵魂。

我们团队的标准演进路径是：

1. 第 1 周：用 GitHub Actions 实现 Push 模型，让所有成员习惯“配置即代码”，建立基础 CI/CD 流水线；
2. 第 2 月：在预发环境部署 Argo CD，将infra/staging/目录接入 Pull 模型，让 SRE 团队体验 drift detection 和一键回滚；
3. 第 3 季度：生产环境全面切换到 Pull 模型，并启用 Argo CD 的 ApplicationSet 功能，实现“一个 PR 同时更新 10 个集群的配置”。

注意：Push 和 Pull 并非互斥。我们在大型项目中常用混合模式：用 GitHub Actions 做 CI（构建镜像、运行单元测试），用 Argo CD 做 CD（部署应用、管理配置）。CI 流水线只负责把构建好的 Docker 镜像推送到 Registry，并更新 Git 中的image: myapp:v1.2.3字段；Argo CD 检测到这个变更，自动拉取新镜像并滚动更新。这样既利用了 CI 的强大生态，又保留了 Pull 的自愈能力。

3. 核心细节解析与实操要点：从 LLM 项目看 GitOps 的最小可行实践

3.1 为什么 LLM 项目是 GitOps 的绝佳练兵场？

大语言模型应用（LLM App）天生具备 GitOps 的所有理想特征：

• 强依赖声明式配置：一个 LLM 服务的性能，70% 取决于resources.limits.memory、env.PYTORCH_CUDA_ALLOC_CONF、volumeMounts这些参数，而非代码逻辑。这些参数必须精确、可复现、可版本化。
• 环境差异巨大：本地开发用 CPU 推理，测试环境用 A10G，生产环境用 A100，不同 GPU 的 CUDA 版本、驱动、内存配额完全不同。GitOps 的environments/dev/和environments/prod/目录天然解决这个问题。
• 安全敏感度高：LLM 应用常需挂载 API Key、模型权重、敏感提示词模板。GitOps 的 Secret 管理（如 SOPS + Age 加密）能确保这些密钥永不以明文形式出现在任何地方。

我们以一个真实的 Gradio LLM Web UI 项目为例（项目结构见输入内容），展示如何用最简方式落地 GitOps。

3.2 目录结构设计：让 Git 成为你的“基础设施地图”

一个反模式是把所有 YAML 堆在根目录下。正确的做法是按关注点分离（Separation of Concerns）设计：

my-llm-app/ ├── app/ # 应用代码层（开发者关注） │ ├── main.py # Gradio UI 逻辑 │ ├── requirements.txt # Python 依赖（含 transformers, torch） │ └── Dockerfile # 构建镜像（FROM pytorch/pytorch:2.1.0-cuda11.8-cudnn8-runtime） ├── infra/ # 基础设施层（SRE 关注） │ ├── base/ # 公共基线（所有环境共享） │ │ ├── kustomization.yaml # 定义公共 label、namespace、common configmap │ │ └── deployment.yaml # 通用 Deployment 模板（不含 env-specific 字段） │ ├── overlays/ # 环境覆盖层（dev/staging/prod） │ │ ├── dev/ │ │ │ ├── kustomization.yaml # 引用 base，添加 dev-specific patch │ │ │ └── patch-cpu.yaml # 降低 resources.limits.cpu: "500m" │ │ ├── staging/ │ │ └── production/ │ └── clusters/ # 集群专属配置（如多云场景） │ ├── aws-eks/ │ └── gcp-gke/ ├── .github/workflows/ # CI/CD 层（自动化引擎） │ ├── ci.yaml # 构建、测试、推送镜像 │ └── cd.yaml # 部署（Push 模型）或触发 Argo CD（Pull 模型） └── docs/ # 文档层（所有角色关注） └── gitops-rules.md # 明确谁可以改哪个目录、PR 流程、回滚 SOP

这个结构的关键在于：infra/base/是“宪法”，infra/overlays/*/是“法律解释”，app/是“公民行为”。当你要给生产环境增加一个 Prometheus 监控 endpoint，只需在infra/overlays/production/下加一个patch-metrics.yaml，而不用动base/里的任何东西。这种设计让变更影响范围一目了然，极大降低协作风险。

3.3 Dockerfile 的 GitOps 化改造：从“构建脚本”到“可验证制品”

很多团队的 Dockerfile 写着RUN pip install -r requirements.txt，这会导致每次构建都从 PyPI 拉包，网络波动就失败，且无法保证两次构建的依赖版本完全一致。GitOps 要求镜像构建是确定性（Deterministic）的。

我们的改造方案是：

1. 在app/目录下增加requirements.lock文件，用pip-compile生成（pip install pip-tools && pip-compile requirements.in）；
2. Dockerfile 改为COPY requirements.lock . && RUN pip install -r requirements.lock；
3. CI 流水线中增加一步：pip-compile --upgrade requirements.in && git add requirements.lock && git commit -m "chore(deps): update lockfile"。

这样，requirements.lock就成了 Git 中的“依赖宪法”，每次pip install的结果都可复现。我们曾用此方案定位一个诡异 bug：开发在本地pip install了新版本 transformers，但 CI 构建的镜像仍是旧版。通过对比requirements.lock的 Git 历史，5 分钟就定位到是开发忘了提交 lock 文件。

3.4 Kustomize 的深度应用：用 patch 精准控制环境差异

Kustomize 是 GitOps 的隐形功臣。它不像 Helm 那样需要学习模板语法，而是用纯 YAML patch 操作，学习成本极低，且与 Git 天然契合。

以 LLM 项目为例，不同环境的典型差异：

• 开发环境：需要--reload参数支持热重载，resources.limits.memory: "2Gi"；
• 生产环境：需要--no-reload，resources.limits.memory: "32Gi"，env.TORCH_COMPILE: "1"启用编译优化。

传统做法是维护两套 Deployment YAML，极易遗漏同步。Kustomize 方案如下：

# infra/overlays/dev/kustomization.yaml bases: - ../../base patches: - patch-cpu.yaml - patch-dev-args.yaml # 添加 --reload

# infra/overlays/dev/patch-dev-args.yaml - op: add path: /spec/template/spec/containers/0/args value: ["--reload"]

# infra/overlays/production/kustomization.yaml bases: - ../../base patches: - patch-prod-memory.yaml # 修改 memory limits - patch-prod-env.yaml # 添加 TORCH_COMPILE

这样，base/deployment.yaml只保留最精简的通用字段，所有环境特有逻辑都在overlays/下。Git diff 时，你只会看到patch-prod-memory.yaml的变更，而不会被几百行重复的 YAML 淹没。

3.5 GitHub Actions CI/CD 流水线：从“能跑”到“可信”

一个典型的ci.yaml流水线应包含以下关键环节（按执行顺序）：

注意：cd.yaml的关键不是“怎么部署”，而是“谁有权部署”。我们强制要求：

• cd.yaml只能部署infra/overlays/production/目录下的配置；
• 必须开启concurrency: group: production-deploy, cancel-in-progress: true，防止并发部署导致状态混乱；
• 所有kubectl apply命令必须加上--prune -l gitops=enabled，自动清理 Git 中已删除的资源。

4. 实操过程与核心环节实现：手把手搭建 LLM 项目的 Push GitOps

4.1 准备工作：5 分钟搞定环境依赖

在开始前，请确保你有：

• 一个 GitHub 账号（用于托管代码和 Secrets）；
• 一个 Kubernetes 集群（Minikube 本地测试足够，或 EKS/GKE）；
• kubectl和helmCLI 已配置好；
• Docker Desktop（或podman）已安装。

关键安全步骤（极易被跳过）：

1. 在 GitHub 仓库 Settings → Secrets and variables → Actions 中，创建以下 Secrets：
   • KUBE_CONFIG：Base64 编码的~/.kube/config文件（仅限测试，生产环境用 OIDC）；
   • REGISTRY：Docker Registry 地址（如ghcr.io/yourname）；
   • REGISTRY_USERNAME和REGISTRY_PASSWORD：Registry 凭据。
2. 在集群中创建专用 ServiceAccount：

   kubectl create namespace llm-app kubectl create serviceaccount -n llm-app github-actions-sa kubectl create rolebinding -n llm-app github-actions-rb \ --clusterrole=edit \ --serviceaccount=llm-app:github-actions-sa

提示：KUBE_CONFIG用 Base64 是为了绕过 GitHub Secrets 对换行符的限制。实际使用时，CI 流水线中用echo "${{ secrets.KUBE_CONFIG }}" | base64 -d > ~/.kube/config还原。

4.2 编写ci.yaml：构建、测试、推送一体化

# .github/workflows/ci.yaml name: CI Pipeline on: push: paths: - 'app/**' - 'infra/base/**' - 'requirements.in' - 'Dockerfile' jobs: lint-and-test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: '3.10' - name: Install dependencies run: | pip install pylint bandit pip-tools - name: Lint Python code run: pylint app/ - name: Security scan run: bandit -r app/ - name: Check requirements lock run: pip-compile --check requirements.in build-and-push: needs: lint-and-test runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up QEMU uses: docker/setup-qemu-action@v3 - name: Set up Docker Buildx uses: docker/setup-buildx-action@v3 - name: Login to Container Registry uses: docker/login-action@v3 with: registry: ${{ secrets.REGISTRY }} username: ${{ secrets.REGISTRY_USERNAME }} password: ${{ secrets.REGISTRY_PASSWORD }} - name: Build and push uses: docker/build-push-action@v5 with: context: . push: true tags: ${{ secrets.REGISTRY }}/llm:${{ github.sha }} cache-from: type=registry,ref=${{ secrets.REGISTRY }}/llm:buildcache cache-to: type=registry,ref=${{ secrets.REGISTRY }}/llm:buildcache,mode=max

这个流水线的关键设计：

• 路径触发：只在app/或requirements.in变更时运行，避免无谓构建；
• 分阶段依赖：lint-and-test成功后才执行build-and-push，失败立即中断；
• 构建缓存：cache-from/cache-to复用 layer，将 10 分钟构建缩短到 90 秒；
• 安全扫描：bandit检查app/中是否有os.system()调用，防止命令注入。

4.3 编写cd.yaml：精准部署到指定环境

# .github/workflows/cd.yaml name: CD Pipeline on: push: paths: - 'infra/overlays/production/**' - 'infra/overlays/staging/**' jobs: deploy-to-staging: if: github.event_name == 'push' && startsWith(github.head_ref, 'staging') runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Configure Kubeconfig run: echo "${{ secrets.KUBE_CONFIG }}" | base64 -d > ~/.kube/config - name: Deploy to Staging run: | kubectl config use-context staging-cluster kubectl apply -k infra/overlays/staging/ --prune -l gitops=enabled deploy-to-production: if: github.event_name == 'push' && startsWith(github.head_ref, 'production') runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Configure Kubeconfig run: echo "${{ secrets.KUBE_CONFIG }}" | base64 -d > ~/.kube/config - name: Deploy to Production run: | kubectl config use-context production-cluster kubectl apply -k infra/overlays/production/ --prune -l gitops=enabled

这里有两个精妙设计：

• 环境隔离：用if条件判断分支名，确保staging分支的变更只影响 staging 环境；
• 标签驱逐：--prune -l gitops=enabled要求所有部署的资源都打上gitops: enabledlabel，这样当infra/overlays/staging/中删除一个 ConfigMap 时，kubectl apply会自动删除集群中对应的资源，避免“幽灵配置”残留。

4.4 验证 GitOps 效果：用三个命令看清一切

部署完成后，用以下命令验证 GitOps 是否真正生效：

1. 查看当前部署状态：

   kubectl get deploy -n llm-app nginx-llm -o wide # 输出应显示 IMAGE 为 ghcr.io/yourname/llm:abc123（对应 Git commit SHA）

2. 模拟人为 drift 并观察自愈（仅 Push 模型需手动触发）：

   kubectl scale deploy -n llm-app nginx-llm --replicas=1 kubectl get deploy -n llm-app nginx-llm # 显示 REPLICAS=1 # 等待 2 分钟，再次执行： kubectl get deploy -n llm-app nginx-llm # 显示 REPLICAS=3（因为 cd.yaml 每次 push 都会重置）

3. 回滚到上一个版本：

   git checkout HEAD~1 infra/overlays/production/ git commit -m "revert: downgrade to v1.1.0" git push origin production # 2 分钟后，kubectl get deploy -n llm-app nginx-llm 显示 IMAGE 已变回 v1.1.0

注意：真正的 Pull 模型（Argo CD）会自动检测 drift 并修复，无需等待下次 push。但 Push 模型的“修复”发生在下一次代码提交时，这是它与 Pull 的本质区别。

5. 常见问题与排查技巧实录：那些文档里不会写的血泪教训

5.1 “镜像拉取失败”：90% 的问题出在 Registry 权限

现象：Pod 一直处于ImagePullBackOff状态，kubectl describe pod显示Failed to pull image "ghcr.io/yourname/llm:abc123": rpc error: code = Unknown desc = failed to fetch anonymous token。

排查路径：

1. 检查集群节点是否能访问 Registry：curl -I https://ghcr.io/v2/（应返回 200）；
2. 检查 Pod 的imagePullSecrets是否正确：kubectl get secret -n llm-app github-pull-secret -o yaml；
3. 最关键的一步：检查cd.yaml中的kubectl apply是否在正确的 namespace 下执行。常见错误是忘记-n llm-app，导致资源被部署到defaultnamespace，而imagePullSecrets只在llm-appnamespace 有效。

终极解决方案：在infra/base/kustomization.yaml中统一定义：

secretGenerator: - name: github-pull-secret type: kubernetes.io/dockerconfigjson files: - .dockerconfigjson=./secrets/dockerconfig.json

这样，所有环境都会自动注入正确的 Secret。

5.2 “配置未生效”：Kustomize patch 的隐式陷阱

现象：你在infra/overlays/production/patch-memory.yaml中修改了resources.limits.memory，但kubectl get deploy -n llm-app nginx-llm -o yaml显示的仍是旧值。

原因分析：Kustomize 的 patch 顺序很重要。如果base/deployment.yaml中resources.limits.memory字段不存在，而你的 patch 试图op: replace，它会静默失败。必须用op: add或确保 base 中已存在该字段。

调试命令：

# 查看 Kustomize 渲染后的最终 YAML（在 CI 中加入此步骤） kustomize build infra/overlays/production/ > rendered.yaml # 检查 rendered.yaml 中是否包含你的 patch 内容 grep -A5 "memory" rendered.yaml

避坑技巧：在base/deployment.yaml中预先定义所有可能被覆盖的字段，即使值为空：

resources: limits: memory: "" cpu: "" requests: memory: "" cpu: ""

这样，patch-memory.yaml就能安全地op: replace。

5.3 “Secret 泄露风险”：如何安全地管理 LLM 的 API Key

这是 LLM 项目最危险的环节。绝不能把OPENAI_API_KEY明文写在infra/overlays/production/secrets.yaml里！

正确方案：SOPS + Age 加密

1. 安装sops和age；
2. 生成 Age 密钥对：age-keygen -o age.key；
3. 将公钥存入 GitHub Secrets：AGE_PUBLIC_KEY；
4. 创建加密 Secret：

   sops --encrypt --age ${{ secrets.AGE_PUBLIC_KEY }} secrets.yaml > secrets.enc.yaml

5. 在cd.yaml中解密：

   - name: Decrypt secrets run: | echo "${{ secrets.AGE_PRIVATE_KEY }}" > age.key sops --decrypt --age age.key secrets.enc.yaml > secrets.yaml - name: Apply secrets run: kubectl apply -f secrets.yaml -n llm-app

这样，secrets.enc.yaml可以安全地存入 Git，而私钥age.key永远只存在于 CI 运行时内存中。

5.4 “GPU 资源不足”：Kubernetes 调度器的隐藏规则

现象：Pod 一直处于Pending状态，kubectl describe pod显示0/3 nodes are available: 3 Insufficient nvidia.com/gpu。

根本原因：Kubernetes 默认不识别 GPU 资源。你必须：

1. 在每个 GPU 节点上安装 NVIDIA Device Plugin：kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.14.5/nvidia-device-plugin.yml；
2. 在 Deployment 中显式请求 GPU：

   resources: limits: nvidia.com/gpu: 1 # 请求 1 块 GPU requests: nvidia.com/gpu: 1

经验技巧：在infra/base/kustomization.yaml中添加一个gpu-labelerpatch，自动给 GPU 节点打 label：

- op: add path: /spec/template/spec/nodeSelector value: {nvidia.com/gpu.present: "true"}

这样，所有使用 GPU 的应用都会被调度到打了nvidia.com/gpu.present=truelabel 的节点上。

5.5 “Gradio UI 无法访问”：Ingress 配置的魔鬼细节

现象：kubectl get ingress显示ADDRESS为空，或访问域名返回502 Bad Gateway。

排查清单：

• ✅ 检查 Ingress Controller 是否运行：kubectl get pods -n ingress-nginx；
• ✅ 检查 Ingress 资源是否引用了正确的 Service：kubectl get ingress -o wide中的BACKEND列；
• ✅最关键的一步：检查 Service 的selector是否匹配 Pod 的labels。Gradio 默认的 Pod label 是app: gradio，但你的 Deployment 可能写了app: nginx-llm，导致 Ingress 找不到后端；
• ✅ 检查 TLS 证书：如果启用了 HTTPS，确保cert-manager已安装，且Certificate资源处于Ready状态。

速查命令：

# 查看 Ingress Controller 日志（定位 502 原因） kubectl logs -n ingress-nginx deploy/ingress-nginx-controller | tail -20 # 检查 Service 是否有 Endpoints kubectl get endpoints -n llm-app nginx-llm-service # 如果 Endpoints 为空，说明 Service selector 与 Pod labels 不匹配

6. 从 Push 到 Pull：平滑升级 Argo CD 的实战指南

当你发现 Push 模型的局限