📚 课程目录第4章连接Git仓库与认证配置

4. 连接Git仓库与认证配置

在 OpenShift GitOps 中，Argo CD 是实际执行“拉取期望状态”的组件。它需要持续访问 Git 仓库，读取 Kustomize、Helm 或纯 YAML 清单，再与集群中的实时状态比对。因此，仓库接入与认证配置是整条持续交付链路的起点。如果这一步不稳定，后续的同步、回滚、漂移检测都会失去意义。本节围绕四种典型接入方式展开：HTTPS 公开仓库、HTTPS 私有仓库、SSH 私有仓库，以及 Webhook 自动同步，并说明凭证如何管理、如何验证。

一、HTTPS 与 SSH 的接入差异

Argo CD 的仓库连接本质上是一个“客户端到 Git 服务端”的认证问题。HTTPS 方式使用用户名加密码或访问令牌（Token），SSH 方式使用私钥与 known_hosts 校验。两者在配置字段、Secret 结构和网络要求上都有区别。

HTTPS：仓库地址形如 https://git.example.com/team/app-config.git，认证信息放在 username 与 password 字段，Token 通常作为 password 使用。适合大多数 GitLab、GitHub、Gitea 场景，也便于配合 Webhook。
SSH：仓库地址形如 git@git.example.com:team/app-config.git，认证信息是 sshPrivateKey，并需要提供 knownHosts 或关闭严格主机校验。适合不允许暴露 HTTPS 凭据、或已有 SSH 密钥体系的团队。

选择原则可以概括为：如果仓库平台支持 Webhook 且团队能接受 Token 轮换，优先 HTTPS；如果安全策略要求密钥不落地为可复用密码，或仓库只开放 SSH，则使用 SSH。两者可以并存，同一 Argo CD 实例可同时管理多个不同认证方式的仓库。

二、HTTPS 私有仓库的凭证配置

在 OpenShift GitOps 中，Argo CD 通常安装在 openshift-gitops 命名空间。为私有 HTTPS 仓库创建凭证，最直接的方式是创建一个带特定标签的 Secret。以下示例使用 Token 作为密码，用户名可填 git 或平台要求的固定值。

apiVersion: v1
kind: Secret
metadata:
  name: argocd-repo-https
  namespace: openshift-gitops
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: https://git.example.com/team/app-config.git
  username: git
  password: glpat-xxxxxxxxxxxxxxxxxxxx

应用后，可以用 oc get secret -n openshift-gitops -l argocd.argoproj.io/secret-type=repository 确认 Secret 已存在。随后在 Argo CD 控制台的 Settings → Repositories 中应能看到该仓库，状态为 Successful。如果显示 Failed，优先检查 Token 是否过期、用户名是否正确、以及仓库地址是否与 Secret 中的 url 完全一致（包括大小写和 .git 后缀）。

Token 建议使用只读权限的 Deploy Token 或 Project Access Token，避免使用个人账号的长期密码。Token 轮换时只需更新 Secret 中的 password 字段，Argo CD 会在下一次连接时使用新值。

三、SSH 私有仓库的接入

SSH 方式需要生成一对密钥，将公钥配置到 Git 平台的 Deploy Key 中，私钥写入 Secret。私钥必须是 PEM 格式，且不能带 passphrase，否则 Argo CD 无法自动解锁。known_hosts 用于校验服务端主机指纹，避免中间人攻击。

ssh-keygen -t ed25519 -C "argocd@openshift" -f argocd_deploy_key -N ""

apiVersion: v1
kind: Secret
metadata:
  name: argocd-repo-ssh
  namespace: openshift-gitops
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: git
  url: git@git.example.com:team/app-config.git
  sshPrivateKey: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    ...（私钥内容）...
    -----END OPENSSH PRIVATE KEY-----
  knownHosts: |
    git.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...

knownHosts 可以通过 ssh-keyscan git.example.com 获取，但更稳妥的做法是从平台文档或管理员处取得官方指纹，避免被伪造的扫描结果误导。配置完成后，同样在 Repositories 页面确认状态。SSH 方式下如果连接失败，常见原因是私钥格式错误、knownHosts 缺失、或 Git 平台未把公钥加入 Deploy Key。

四、Webhook 自动同步

默认情况下，Argo CD 每 3 分钟轮询一次仓库。对于需要快速响应的环境，可以配置 Webhook，让 Git 平台在 push 或 merge 事件发生时主动通知 Argo CD，从而立即触发刷新。Webhook 只负责“通知”，不携带仓库凭据，因此它不能替代前面的认证配置，而是认证成功后的加速手段。

以 GitLab 为例，在仓库的 Settings → Webhooks 中填写 Argo CD 的地址，例如 https://argocd.example.com/api/webhook，并设置一个 Secret Token。然后在 Argo CD 的 argocd-secret 中配置对应的 webhook.gitlab.secret。GitHub 则使用 webhook.github.secret，Gitea 使用 webhook.gitea.secret。配置完成后，可以在 Webhook 页面点击 Test，观察 Argo CD 是否收到事件并触发刷新。

Webhook 地址必须能被 Git 平台访问。如果 Argo CD 部署在私有网络，需要确保 Git 平台能通过公网或专线到达该地址。若无法开放入站，可以保留轮询作为兜底，但同步延迟会回到分钟级。

五、验证与排障要点

完成配置后，建议按以下顺序验证：第一，在 Argo CD 控制台确认仓库状态为 Successful；第二，创建一个最小 Application 指向该仓库，观察是否能正常生成资源树；第三，手动触发一次同步，确认集群状态与仓库一致；第四，向仓库推送一次变更，观察 Webhook 是否让同步在数秒内发生。如果第三步失败，问题通常在仓库内容或 Kustomize 路径；如果第四步失败，问题通常在 Webhook 配置或网络可达性。

现象	优先检查	常见原因
仓库状态 Failed	Secret 的 url、username、password	Token 过期、地址不一致、权限不足
SSH 连接被拒绝	sshPrivateKey、knownHosts	私钥带 passphrase、公钥未加入 Deploy Key
Webhook 无响应	Argo CD 地址、Secret Token	网络不可达、Token 不匹配、事件类型未勾选
同步延迟仍为分钟级	Webhook 是否真正触发	Webhook 未生效，回退到轮询

把仓库接入和认证配置做扎实，后续的 Application 定义、同步策略和漂移检测才有可靠基础。实际工程中，建议把 Secret 的创建纳入 GitOps 自身的管理范围，或至少用 SealedSecret、External Secrets 等方式避免明文凭据长期停留在 YAML 中。这样，仓库连接本身也成为可审计、可复现的交付物。