《ArgoCD 部署 Nginx 的两种方式：Git 仓库模式 VS 命令行直连模式（踩坑实录）》

2026/7/10 12:35:13

一、前言

作为一款 GitOps 持续交付工具，ArgoCD 的核心逻辑是“Git 仓库即事实来源”。但在实际学习和测试过程中，很多初学者（包括我自己）都会遇到一个问题：手头没有现成的 Git 仓库怎么办？

于是我开始研究 ArgoCD 的两种部署方式：

标准模式：在 ArgoCD 中添加 Git 仓库链接，自动拉取 YAML。
纯命令行模式：不依赖任何 Git 仓库，直接通过kubectl apply -f提交 Application 资源。

本文将详细记录这两种方式的实操步骤及各自容易踩的坑。

二、标准模式：添加 Git 仓库链接（标准 GitOps）

这是 ArgoCD 设计的初衷，也是生产环境最推荐的方式。

2.1 准备 Git 仓库

你需要一个 GitHub/GitLab/Gitea 仓库，里面存放 Nginx 的deployment.yaml和service.yaml。

2.2 在 ArgoCD 中添加 Git 仓库（需要配置 SSH 私钥）

核心报错难点（实战踩坑）：
如果你直接配置了 Git 地址，但没有给 ArgoCD 提供 SSH 私钥，你会在 ArgoCD 界面或日志中看到一条非常经典的报错：

Failed to load target state: error creating SSH agent: "SSH agent requested but SSH_AUTH_SOCK not-specified"

如何修复这个报错？

# 1. 把 ~/.ssh/id_rsa 以 Secret 形式注入 ArgoCD kubectl create secret generic argocd-repo \ --namespace argocd \ --from-file=sshPrivateKey=~/.ssh/id_rsa # 2. 给 Secret 打上 ArgoCD 专用标签 kubectl label secret argocd-repo \ --namespace argocd \ argocd.argoproj.io/secret-type=repo-creds # 3. 重启 ArgoCD 组件 kubectl rollout restart -n argocd deployment argocd-server kubectl rollout restart -n argocd deployment argocd-repo-server

优点：配置好之后，只要 Git 仓库里的文件发生变化，ArgoCD 就能自动同步到 K8s 集群。
缺点：门槛较高，需要配置 SSH 密钥和仓库权限。

三、命令行直连模式：不通过 Git，直接提交 YAML

这是我在没有准备 Git 仓库时的应急玩法。

3.1 直接创建 Application CRD 资源

我们不需要从 Git 拉取，而是直接告诉 ArgoCD：“请把下面这段 YAML 定义的 Nginx 部署到我的集群里。”

yaml

# 创建 nginx 的 Deployment 应用 cat > argocd-nginx-deploy.yaml <<EOF apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: nginx-deploy namespace: argocd spec: destination: namespace: default server: https://kubernetes.default.svc project: default source: # 注意：这里我们不写 Git 地址，而是指向一个占位符 path: placeholder repoURL: https://kubernetes.default.svc targetRevision: HEAD EOF # 提交到集群 kubectl apply -f argocd-nginx-deploy.yaml

3.2 这个方式遇到的一个大坑：多文档 YAML 报错

如果你想把 Deployment 和 Service 写在一个 Application 里，ArgoCD 会直接给你一个红色的报错：

text

Unable to validate changes: expected a single document in the stream

这怎么办？
解法：拆分成两个 Application 分别创建。

bash

# 分别创建 Deployment 和 Service 的 Application kubectl apply -f argocd-nginx-deploy.yaml kubectl apply -f argocd-nginx-svc.yaml

优点：启动极快，完全不需要配置 Git 仓库和 SSH 密钥，适合快速体验。
缺点：无法实现自动同步（因为 ArgoCD 不知道你什么时候修改了代码），只能作为一个“可视化仪表盘”来使用。

四、两种方式的最终对比总结

维度	Git 仓库模式（标准）	命令行直连模式（纯YAML）
是否需要 Git 仓库	✅ 必须要有	❌ 不需要
是否需要 SSH 密钥	✅ 必须配置	❌ 不需要
能否自动同步	✅ 可以自动检测并同步	❌ 无法自动同步
适用场景	生产环境、多人协作	快速测试、临时纳管应用
部署门槛	较高	极低