生产环境 DevOps 实战 | 第 22 天：Argo CD 安装与配置——kubectl 安装、ingress、初始密码运维实战与AI漫画教程

第 22/60 天

引言

在前面的系列文章中，我们已经完成了 Tekton（CI）与 Harbor（制品仓库）的部署与实战，三条链路只剩下最后一环：Argo CD（CD / GitOps 持续交付）。从本篇文章开始，我们将用 7 天的时间深入 Argo CD 的安装、使用与集成。

Argo CD 是 CNCF 孵化的 GitOps 持续交付工具，它把「Git 仓库中的声明式配置」作为集群状态的唯一事实来源（Source of Truth），通过持续对比 Git 中声明的目标状态与集群实际运行状态，自动或手动地将集群收敛到期望状态。对于生产环境来说，Argo CD 解决了传统 CD 工具「脚本式发布不可审计、回滚困难、环境漂移无人发现」的三大痛点。

本文覆盖以下内容：

Argo CD 的核心架构与组件职责
三种安装方式对比（kubectl manifests / Helm / Operator），并给出生产推荐
使用 kubectl 安装 Argo CD 的完整步骤
初始密码获取、首次登录与密码修改
通过 Nginx Ingress 暴露 Web UI 与 gRPC 端口的配置实战
安装后的安全加固与常见问题排查

核心概念

Argo CD 的架构组件

Argo CD 安装后会创建 argocd 命名空间，核心组件如下：

组件	类型	职责
`argocd-server`	Deployment	API Server + Web UI + CLI 入口，负责认证、RBAC、应用管理
`argocd-repo-server`	Deployment	拉取 Git 仓库、生成 manifests（原生 YAML / Helm / Kustomize）
`argocd-application-controller`	StatefulSet	持续对比 Git 目标状态与集群实际状态，执行 Sync/自愈
`argocd-redis`	Deployment	缓存（可替换为外部 Redis 实现高可用）
`argocd-dex-server`	Deployment	可选 SSO 认证组件（对接 OIDC/LDAP）

核心工作流

Compare：Controller 每 3 分钟（默认 --status-processors 轮询间隔）对比 Git 声明与集群实际状态；
Sync：发现差异后，按 Sync 策略（自动/手动）将集群收敛到 Git 声明状态；
App of Apps：用一个 Application 管理一批 Application，实现多应用编排。

安装方式对比

方式	命令/工具	优点	缺点	适用场景
kubectl manifests	`kubectl apply -f install.yaml`	简单直接、易于审计	升级需手动管理 manifests	快速验证、学习
Helm Chart	`helm install argo-cd argo/argo-cd`	参数化配置、升级方便、社区维护	需要理解 Chart values	生产推荐
Operator	Argo CD Operator	声明式管理 Argo CD 自身	运维复杂度高、社区活跃度一般	大规模多实例托管

生产建议：生产环境优先选择 Helm 方式（或 Argo CD Operator），但为了理解组件构成与排查问题，本文先用 kubectl 方式安装演示，两者的最终资源形态是一致的。

版本选择

到 2026 年，Argo CD 已进入 v2.x 的成熟稳定期（本文以 v2.14.x 为例，请到官方 GitHub Releases 页面获取当前最新稳定版）。选择版本时注意：

优先选择最新 patch 版本（如 v2.14.3），修复安全漏洞；
升级前阅读 UPGRADING.md，跨大版本升级（如 v2.12 → v2.14）需关注 API 兼容性；
关注 CVE 公告，Argo CD 曾是 CVE 重灾区（如 SSRF、路径穿越），务必及时打补丁。

实战步骤

步骤 0：前置检查

安装前确认 Kubernetes 集群版本、kubectl 权限与集群连通性：

# 检查集群版本与 kubectl
kubectl version --client --short
kubectl cluster-info

# 确认有创建命名空间与 CRD 的权限（管理员权限）
kubectl auth can-i create namespace --as=system:admin

# 查看已安装的 CRD，避免与已有资源冲突
kubectl get crd | grep -i argoproj || echo "NO_ARGO_CRD_FOUND"

输出 NO_ARGO_CRD_FOUND 说明可以干净安装；若已有旧版 CRD，需要先清理或走升级流程。

步骤 1：使用 kubectl 安装 Argo CD

# 创建命名空间
kubectl create namespace argocd

# 下载官方 manifests（v2.14.3 为例，可替换为最新稳定版）
curl -sSL -o /tmp/argo-cd-install.yaml 
  https://raw.githubusercontent.com/argoproj/argo-cd/v2.14.3/manifests/install.yaml

# 应用 manifests（包含 CRD、RBAC、Deployment、Service 等全部资源）
kubectl apply -n argocd -f /tmp/argo-cd-install.yaml

install.yaml 是非高可用的单实例形态。生产环境建议使用 ha/install.yaml（位于仓库 manifests/ha 目录）或 Helm Chart 并开启高可用，我们将在第 35 天详细讲三件套的高可用部署。

步骤 2：确认部署状态

# 查看所有 Pod 是否就绪（约需 1-2 分钟拉取镜像）
kubectl get pods -n argocd -w

# 期望输出（STATUS 全部为 Running/1/1 或 2/2）
# NAME                                                READY   STATUS    RESTARTS   AGE
# argocd-application-controller-0                     1/1     Running   0          2m
# argocd-applicationset-controller-5f9f6f7b6c-xxxxx   1/1     Running   0          2m
# argocd-dex-server-7c9f8d9d6f-xxxxx                  1/1     Running   0          2m
# argocd-redis-6f8f9c9d8f-xxxxx                       1/1     Running   0          2m
# argocd-repo-server-6b9f7c6d9f-xxxxx                 1/1     Running   0          2m
# argocd-server-7d9f5c8d7f-xxxxx                      1/1     Running   0          2m

# 查看 Service
kubectl get svc -n argocd

argocd-server Service 默认类型为 ClusterIP，端口 80（HTTP）与 443（HTTPS/gRPC）。外部访问需要 port-forward（临时调试）或 Ingress（生产推荐）。

步骤 3：获取初始密码并登录

Argo CD 首次安装时会自动生成一个随机密码，存放在 argocd-initial-admin-secret 中：

# 获取初始密码（base64 解码）
kubectl -n argocd get secret argocd-initial-admin-secret 
  -o jsonpath="{.data.password}" | base64 -d
echo ""

# 临时通过 port-forward 访问 API/UI（仅调试用）
kubectl port-forward svc/argocd-server -n argocd 8080:443 &

# 安装并登录 Argo CD CLI（Linux amd64）
curl -sSL -o /usr/local/bin/argocd 
  https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
chmod +x /usr/local/bin/argocd
argocd version --client

# 登录（用户名 admin，密码为上一步输出）
argocd login localhost:8080 --username admin 
  --password <初始密码> --insecure

注意：初始密码是一次性的「引导凭据」。登录后务必立即修改，否则任何人只要能访问集群就能拿到 admin 权限。

步骤 4：修改密码并启用账号加固

# 交互式修改当前用户密码
argocd account update-password

# 或者通过环境变量非交互式修改
argocd account update-password 
  --current-password <旧密码> 
  --new-password '<强密码:至少8位含大小写数字特殊字符>'

生产加固建议（详细内容在第 34 天展开）：

# argocd-cm ConfigMap 片段：禁止匿名访问、关闭初始 admin 自动创建
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
  labels:
    app.kubernetes.io/name: argocd-cm
data:
  # 禁止匿名访问
  users.anonymous.enabled: "false"
  # 登录会话有效期（秒）
  server.rbac.logins.enforce.enabled: "true"

修改后重启 server 使其生效：

kubectl rollout restart deployment/argocd-server -n argocd

步骤 5：配置 Nginx Ingress 暴露 Web UI

生产环境通过 Ingress 暴露 Argo CD，需要同时处理 HTTPS（Web UI） 与 gRPC（CLI 的 argocd-server 443 端口）。以下为 Nginx Ingress Controller 的完整配置：

# argocd-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    # 强制 HTTPS 跳转
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
    # SSL Passthrough：将 TLS 流量透传到 argocd-server:443（gRPC 必需）
    nginx.ingress.kubernetes.io/ssl-passthrough: "true"
    # 后端协议 HTTPS（与 ssl-passthrough 二选一时使用）
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - argocd.example.com
      secretName: argocd-tls   # 存放 TLS 证书的 Secret
  rules:
    - host: argocd.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: argocd-server
                port:
                  number: 443

关键点：Argo CD CLI 使用 gRPC 与 server 通信，而 gRPC 无法被常规 HTTP 层七层代理正确转发，因此必须使用 ssl-passthrough（透传 TLS）或将 gRPC 走独立 Ingress。只配置 HTTP 80 端口会导致 CLI 登录报 rpc error: code = Unavailable，这是最高频的坑。

先准备证书 Secret（以自签名证书为例）：

# 生成自签名证书（生产请使用 Let's Encrypt / 企业 CA）
openssl req -x509 -nodes -days 365 -newkey rsa:2048 
  -keyout argocd-tls.key -out argocd-tls.crt 
  -subj "/CN=argocd.example.com" -addext "subjectAltName=DNS:argocd.example.com"

# 创建 TLS Secret
kubectl create secret tls argocd-tls -n argocd 
  --key argocd-tls.key --cert argocd-tls.crt

# 应用 Ingress 并验证
kubectl apply -f argocd-ingress.yaml
kubectl get ingress -n argocd
curl -k -I https://argocd.example.com

步骤 6：通过 Ingress 登录验证

# 通过域名登录 CLI（走 gRPC 443）
argocd login argocd.example.com --username admin 
  --password '<新密码>' --grpc-web

# 查看当前上下文并验证连通性
argocd context
argocd account get-user-info

# 验证可用性：注册一个测试仓库与测试应用
argocd repo add https://github.com/example/argocd-example-apps 
  --username <git用户名> --password <git密码或Token>
argocd app create guestbook 
  --repo https://github.com/example/argocd-example-apps 
  --path guestbook --dest-server https://kubernetes.default.svc 
  --dest-namespace default
argocd app get guestbook

浏览器访问 https://argocd.example.com，使用 admin 与新密码登录 Web UI，即可看到 Argo CD 的管理界面（默认浅色主题，可在设置中切换深色）。

步骤 7（可选）：改用 Helm 方式安装（生产推荐）

# 添加 Helm 仓库
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

# 安装 argo-cd（关键 values 示例）
helm install argocd argo/argo-cd --namespace argocd --create-namespace 
  --set server.ingress.enabled=true 
  --set server.ingress.ingressClassName=nginx 
  --set server.ingress.hostname=argocd.example.com 
  --set server.ingress.tls=true 
  --set server.ingress.annotations."nginx.ingress.kubernetes.io/ssl-passthrough"=true 
  --set server.ingress.annotations."nginx.ingress.kubernetes.io/backend-protocol"=HTTPS 
  --set controller.replicas=1 
  --set redis.enabled=true

Helm 方式的好处是：升级只需 helm upgrade，回滚只需 helm rollback，且 values 文件可以作为 GitOps 的一部分纳入版本管理——这也是我们后续第 26 天「Argo CD + Helm/Kustomize」的基础。

常见问题

1. 安装后 Pod 一直处于 `Pending` 或 `CrashLoopBackOff`

Pending 通常是节点资源不足（Argo CD 全家桶约需 1.5-2 CPU / 2-3 Gi 内存），检查 kubectl describe pod -n argocd <pod> 看是否 Insufficient cpu/memory；CrashLoopBackOff 常见于 RBAC 异常或镜像拉取失败，先看 kubectl logs -n argocd <pod> 定位具体错误。

2. `argocd login` 报 `rpc error: code = Unavailable desc = connection error`

几乎都是 gRPC 流量没有被正确转发导致的：CLI 走的是 443 gRPC 端口，而 Ingress 只配置了 HTTP 80，或者没有开启 ssl-passthrough。修复方法：为 Ingress 添加 nginx.ingress.kubernetes.io/ssl-passthrough: "true" 并指向 443 端口；或使用 --grpc-web 参数让 CLI 走 HTTP/1.1 兼容通道。

3. 初始密码为空或 `argocd-initial-admin-secret` 不存在

在较新版本中，如果 argocd-cm 中配置了 admin.enabled: "false" 或已通过 argocd.argoproj.io/secret-type 自定义了 admin 密码，则不会生成初始 secret。此时可以直接修改 argocd-secret 中的 admin.password 字段（使用 bcrypt 哈希，可用 htpasswd -bnBC 10 "" <密码> 生成），或者删除 argocd-cm 中的相关配置后重启 server 让系统重新生成。

4. Ingress 配置后访问返回 502/404

502 通常是后端协议不匹配：Nginx 用 HTTP 访问了 argocd-server 的 443（TLS）端口，需设置 backend-protocol: HTTPS 或使用 ssl-passthrough。404 则可能是 Ingress 的 path 与 Argo CD 的 base href 不一致——如果 Argo CD 配置了 server.rootpath，Ingress path 必须同步修改。

5. 升级 Argo CD 后 UI 白屏或 API 报错

多为跨大版本升级导致：CRD 版本不兼容、argocd-cm 中废弃字段未清理、Redis 版本不匹配。建议：升级前 kubectl get crd | grep argoproj 备份 CRD 列表与 argocd-cm/argocd-secret，升级后立即检查 argocd-server 与 controller 日志；跨大版本升级务必阅读官方 UPGRADING.md。

总结

本文完成了 Argo CD 从零到可用的完整安装流程，核心要点如下：

组件认知：Argo CD 由 server、repo-server、application-controller、redis 与可选的 dex 组成，各司其职，理解组件边界是排障的基础；
安装选型：快速验证用 kubectl manifests，生产环境推荐 Helm Chart（或 Operator），升级回滚都更可控；
入口配置：Ingress 必须正确处理 gRPC 流量（ssl-passthrough + 443 端口），否则 CLI 无法连接，这是最常见的坑；
安全基线：首次登录立即修改初始密码，关闭匿名访问，并把 Argo CD 自身的配置（argocd-cm 等）纳入 GitOps 管理；
下一步：安装只是开始，明天我们将进入「Argo CD Application 与 Sync 策略」实战，理解如何用 Git 声明驱动集群收敛，敬请期待第 23 天。

至此，Tekton（CI）→ Harbor（制品仓库）→ Argo CD（CD）三件套的「地基」已经全部打好，接下来 38 天我们将在这套地基上搭建完整的生产级 DevOps 体系。

文章版权归作者所有，未经允许请勿转载。

THE END