argo cd 必须部署在 kubernetes 集群中，因其核心服务（api server、repo server、application controller）依赖 k8s 原生 api（如 apiextensions.k8s.io/v1、rbac.authorization.k8s.io/v1），通过 crd 注册 application 资源并基于 informer 框架监听 git 与集群状态；它不是传统 linux 服务，无法脱离 k8s 运行。
Argo CD 不能直接在 Linux 主机上“安装运行”，它必须部署在 Kubernetes 集群中 —— 这是很多人踩坑的第一步。你看到的 argocd CLI 工具可以装在 Linux 本地，但核心服务（API Server、Repo Server、Application Controller）全是 Kubernetes 原生控制器，依赖 apiextensions.k8s.io/v1、rbac.authorization.k8s.io/v1 等 API，离了 K8s 就起不来。
为什么不能跳过 K8s 直接装 Argo CD？
Argo CD 不是传统意义上的 Linux 服务（比如 nginx 或 dockerd），它的设计模型就是 Kubernetes 控制器模式：
- 它通过
CustomResourceDefinition注册Application资源类型，这一步必须由 K8s API Server 支持 - 它用
Watch机制监听 Git 仓库变更和集群资源状态，底层依赖 K8s 的 informer 框架 - 它的 UI 和 API Server 是以
Deployment+Service形式运行在 K8s 中，不是 systemd service - 如果你强行用
docker run启动 argocd-server 容器，会立刻报错failed to get Kubernetes config或no route to host
Linux 上真正要做的三件事
你在 Linux 终端实际操作的是以下三项，每项都对应明确命令和检查点：
Convert Github Repository
下载
适用于以下场景：（1）用户提供 GitHub 仓库 URL 或本地仓库路径，并请求将其转换为其他格式；（2）用户请求导出 GitHub 仓库……
-
装好 kubectl 并连上目标 K8s 集群：运行
kubectl version --short能同时显示 client 和 server 版本；kubectl get nodes必须返回 Ready 状态节点 -
用 kubectl 把 Argo CD 控制器部署进集群：执行
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml；之后检查kubectl -n argocd get pod全部为Running -
在 Linux 本地装 argocd CLI（可选但强烈建议）：下载二进制（如
curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/download/v2.11.5/argocd-linux-amd64），加执行权限，验证argocd version输出 client 版本匹配集群服务端（v2.11.x 支持 K8s 1.33）
暴露 Argo CD Server 的常见误区
刚装完默认只能通过 kubectl port-forward 访问，生产环境改 LoadBalancer 类型时容易出错：
- 云厂商（AWS/Azure/GCP）自动分配公网 IP，但国内私有云或裸金属需先部署 metallb，否则
kubectl patch svc argocd-server -n argocd -p'{"spec": {"type": "LoadBalancer"}}'会卡在Pending - 用
NodePort方式要注意宿主机防火墙：确保30080（或你指定的端口）在 Linux 主机上开放，且kube-proxy正常工作 - 如果用 Ingress 暴露，必须确认
argocd-serverService 的port名为https（不是http），否则 TLS 终止会失败；Ingress 资源里得写spec.tls并挂载argocd-secret
Git 仓库配置和应用创建的关键参数
用 argocd app create 或 UI 添加应用时，最容易填错的是这几个字段：
-
--repo必须是 Git 仓库 HTTPS 地址（如https://gitee.com/your-org/app-manifests.git），SSH 地址（git@gitee.com:...）需要额外配 SSH 密钥，不推荐新手用 -
--path是相对仓库根目录的路径，比如清单在prod/nginx/，就填prod/nginx，不能带开头或结尾斜杠 -
--dest-namespace必须已存在（Argo CD 不会自动创建命名空间），提前运行kubectl create ns myapp-prod -
--sync-policy生产环境别直接开automated，至少加--auto-prune和--self-heal，避免误删资源后无法恢复
GitOps 的核心约束很硬：所有变更必须经 Git 提交触发，Argo CD 只做“拉取”和“比对”。哪怕你手欠在 K8s 里删了个 Pod，几秒后它就会被重建——这个行为不是 bug，是设计使然。真要调试，得盯住 argocd app get <name></name> 输出的 STATUS 和 HEALTH 字段，而不是去查 Linux 日志。
