📚 课程目录第4章 ArgoCD架构与组件

4. ArgoCD 架构与组件：API Server、Repo Server、Application Controller、Redis

ArgoCD 遵循 声明式 GitOps 模式，其内部采用微服务架构，由四个核心组件协同工作：API Server、Repo Server、Application Controller 和 Redis。理解每个组件的职责与交互流程，是搭建和运维 GitOps 流水线的基础。

4.1 核心组件总览

下表从功能、协议、关键特性三个维度对比四个组件：

组件	核心功能	通信协议	关键特性
API Server	暴露 REST/gRPC 接口，处理用户请求与 Webhook	HTTPS / gRPC	RBAC 鉴权、SSO 集成、CLI/UI 入口
Repo Server	拉取 Git 仓库，生成 Kubernetes 清单	gRPC（内部）	缓存仓库元数据、支持 Helm/Kustomize/Jsonnet
Application Controller	对比期望状态与实时状态，执行同步	gRPC / Kubernetes API	自动/手动同步、健康检查、Prune 清理
Redis	缓存与分布式锁	TCP（Redis 协议）	降低 Repo Server 负载、防止并发冲突

4.2 组件交互流程与架构图

下图展示了 ArgoCD 四个组件之间的数据流向与依赖关系：

4.3 组件深度解析

4.3.1 API Server

入口角色：所有用户操作（CLI、UI、CI/CD Webhook）均通过 API Server 鉴权后转发。
安全机制：内置 RBAC（基于角色的访问控制），支持 OIDC、LDAP、SAML 等 SSO 集成。
关键接口：/api/v1/applications（应用管理）、/api/v1/session（认证）、/api/v1/stream（事件推送）。

实践建议：生产环境务必为 API Server 配置 TLS 证书，并启用审计日志（--audit-log-path）以追踪变更操作。

4.3.2 Repo Server

核心职责：克隆 Git 仓库、执行 helm template / kustomize build 等渲染操作，生成最终 Kubernetes 清单。
缓存策略：将渲染后的清单存入 Redis，避免每次对比都重新拉取仓库。
安全隔离：Repo Server 运行在独立的 Pod 中，不直接访问 Kubernetes API，仅通过 gRPC 与 API Server 通信。

# Repo Server 典型启动参数示例
argocd-repo-server \
  --redis  redis://argocd-redis:6379 \
  --repo-cache-expiration 24h \
  --parallelism-limit 10

4.3.3 Application Controller

控制循环：每隔 --status-processors 配置的间隔（默认 3 分钟），对比 Git 中的期望状态与集群实时状态。
同步策略：支持 自动同步（检测到差异立即纠正）和 手动同步（需人工确认）。
Prune 行为：当 Git 中删除资源时，Controller 默认不会自动删除集群资源，需显式设置 syncPolicy.prune: true。

注意：自动同步 + 自动 Prune 组合风险较高。建议在集成测试阶段使用手动同步，生产环境再逐步启用自动同步，并配合 selfHeal 选项。

4.3.4 Redis

缓存层：存储 Repo Server 渲染后的清单、仓库元数据、Application Controller 的状态快照。
分布式锁：防止多个 Repo Server 实例同时拉取同一仓库导致冲突。
高可用：生产环境建议部署 Redis Sentinel 或 Redis Cluster，避免单点故障。

4.4 组件间通信协议总结

源组件	目标组件	协议	用途
用户/CI	API Server	HTTPS	提交同步请求、查询状态
API Server	Repo Server	gRPC	请求渲染清单
API Server	Application Controller	gRPC	下发同步指令
Repo Server	Redis	Redis 协议	读写缓存
Application Controller	Kubernetes API	HTTPS	对比/同步集群资源

4.5 组件部署拓扑示意

下图展示了一个高可用部署场景下各组件的 Pod 分布与外部依赖：

4.6 组件故障排查要点

  快速定位组件问题：
  API Server 无响应 → 检查 argocd-server Pod 日志，确认 TLS 证书是否过期。
Repo Server 拉取失败 → 检查 argocd-repo-server 日志中的 rpc error，确认 SSH 密钥或  权限。
Application Controller 不同步 → 查看 argocd-application-controller 日志中的 comparison 和 sync 关键字。
Redis 连接超时 → 确认 argocd-redis Service 是否正常，redis-cli ping 测试连通性。