argocd 命令使用详解

一份详细的 ArgoCD CLI 命令使用指南，按「基础准备→核心命令（按使用场景分类）→高级用法→实用技巧」的结构整理，覆盖日常运维90%以上的场景，新手也能快速上手。

一、前置准备

1. 安装 ArgoCD CLI

方式1：官方二进制包（推荐）

# Linuxcurl-sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64chmod+x argocd-linux-amd64sudomvargocd-linux-amd64 /usr/local/bin/argocd# Maccurl-sSL -o argocd-darwin-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-darwin-amd64chmod+x argocd-darwin-amd64sudomvargocd-darwin-amd64 /usr/local/bin/argocd# Windows（PowerShell）Invoke-WebRequest -Uri https://github.com/argoproj/argo-cd/releases/latest/download/argocd-windows-amd64.exe -OutFile argocd.exe# 把 argocd.exe 加入系统环境变量

方式2：通过 kubectl 端口转发（无需要本地安装，应急使用）

# 端口转发（后台运行，默认端口8080）kubectl port-forward svc/argocd-server -n argocd8080:443&# 所有 argocd 命令后添加 --port 8080 --insecure 即可使用argocd app list --port8080--insecure

2. 登录 ArgoCD 集群

场景1：直接访问 ArgoCD Server（有公网/集群内访问地址）

# 基本登录命令（默认用户名 admin，密码需获取）argocd login<argocd-server地址>[可选参数]# 示例1：HTTP 访问（不验证证书，测试/内网环境）argocd login argocd.example.com:80 --insecure --username admin --password<你的密码># 示例2：HTTPS 访问（带证书，生产环境）argocd login argocd.example.com:443 --certificate-authority /path/to/ca.crt --username admin# 示例3：使用端口转发登录（本地无公网访问）argocd login localhost:8080 --insecure --username admin

场景2：获取默认 admin 密码（新部署的 ArgoCD）

# 从 Secret 中提取默认密码（部署后自动生成，需解码）kubectl -n argocd get secret argocd-initial-admin-secret -ojsonpath="{.data.password}"|base64 -d&&echo

登录后可选操作：修改 admin 密码

argocd account update-password --current-password<旧密码>--new-password<新密码>

二、核心命令详解（按使用场景分类）

场景1：应用（Application）管理（最常用）

应用是 ArgoCD 的核心资源，所有同步、查询、修改操作都围绕应用展开。

1. 查看应用列表

# 基础列表argocd app list# 筛选命名空间下的应用argocd app list --namespace<应用命名空间># 格式化输出（json/yaml，便于脚本处理）argocd app list -o json argocd app list -o yaml

2. 查看应用详情（定位故障核心命令）

# 基础详情argocd app get<应用名># 详细信息（含同步日志、资源状态、阻塞原因，推荐故障排查使用）argocd app get<应用名>--verbose# 仅查看应用的同步状态和资源差异argocd app get<应用名>--diff

3. 创建应用

# 命令行直接创建（简单场景）argocd app create<应用名>\--repo<Git仓库地址>\# 如 https://github.com/your/repo.git--path<Git仓库内配置文件路径>\# 如 k8s/apps/xxx--target-revision<Git分支/标签/提交>\# 如 main、v1.0.0--dest-server<K8s集群地址>\# 默认为 https://kubernetes.default.svc（本地集群）--dest-namespace<应用部署命名空间>\# 如 default、your-namespace# 示例：创建一个名为 demo-app 的应用argocd app create demo-app\--repo https://github.com/your/k8s-manifests.git\--path demo-app/prod\--target-revision main\--dest-namespace demo\--sync-policy automated# 启用自动同步（可选）# 从 YAML 文件创建（复杂场景，推荐纳入Git版本控制）argocd app create -f<application.yaml>

4. 同步应用（手动触发）

# 基础同步argocd appsync<应用名># 强制同步（解决不可变字段、资源冲突，核心应急命令）argocd appsync<应用名>--force# 同步时跳过钩子（PreSync/PostSync，应急时使用）argocd appsync<应用名>--force --skip-hooks# 仅同步指定资源（避免全量同步，提高效率）argocd appsync<应用名>--resource<资源类型>/<资源名>\--resource deployment/demo-app\--resource job/update-bucket-config

5. 终止正在进行的同步（解决卡 Syncing 问题）

argocd app terminate<应用名>

6. 修改应用配置（无需重新创建）

# 示例1：启用自动同步和自动清理（Prune）argocd appset<应用名>--sync-policy automated --auto-prune# 示例2：修改Git仓库路径或分支argocd appset<应用名>--path new/path/in/git --target-revision dev# 示例3：添加同步选项（强制替换不可变资源）argocd appset<应用名>--sync-optionReplace=true# 示例4：暂停应用同步（禁止自动/手动同步，维护时使用）argocd appset<应用名>--pause# 恢复同步argocd appset<应用名>--unpause

7. 删除应用

# 仅删除 ArgoCD 中的应用记录，不删除 K8s 集群中的实际资源（推荐）argocd app delete<应用名># 同时删除 ArgoCD 应用记录和 K8s 集群中的资源（谨慎使用，生产环境需确认）argocd app delete<应用名>--cascade

场景2：仓库（Repository）管理

管理 ArgoCD 关联的 Git 仓库/Helm 仓库，用于拉取应用配置。

1. 添加 Git 仓库（无认证）

argocd repoadd<Git仓库地址>--name<仓库别名>（可选）# 示例argocd repoaddhttps://github.com/your/k8s-manifests.git --name my-k8s-repo

2. 添加带认证的 Git 仓库（HTTPS 用户名/密码）

argocd repoaddhttps://github.com/your/private-repo.git\--username<Git用户名>\--password<Git密码/个人访问令牌（PAT）>

3. 添加带 SSH 认证的 Git 仓库

# 先确保本地有 SSH 密钥，且公钥已添加到 Git 仓库argocd repoaddgit@github.com:your/private-repo.git\--ssh-private-key-path<SSH私钥路径>\# 如 ~/.ssh/id_rsa--insecure-ignore-host-key# 忽略主机密钥验证（测试环境，生产不推荐）

4. 查看仓库列表和详情

# 列表argocd repo list# 详情（验证仓库连通性，排查拉取失败问题）argocd repo get<Git仓库地址/别名>

5. 删除仓库

argocd repo remove<Git仓库地址/别名>

场景3：集群（Cluster）管理

管理 ArgoCD 可部署应用的 K8s 集群（支持多集群部署）。

1. 查看 ArgoCD 已关联的集群

argocd cluster list# 注：默认包含本地集群（https://kubernetes.default.svc）

2. 添加外部 K8s 集群

# 方式1：使用 kubeconfig 文件（推荐，需本地有目标集群的 kubeconfig）argocd clusteradd<kubeconfig中的集群上下文名>\--name<集群别名>（可选）\--namespace<默认部署命名空间>（可选）# 方式2：手动指定 APIServer 地址和令牌argocd clusteradd<集群APIServer地址>\--token<K8s 服务账户令牌>\--name<集群别名>\--insecure# 忽略证书验证（测试环境）

3. 删除已关联的集群

argocd cluster remove<集群APIServer地址/别名>

场景4：用户（Account）与权限管理

管理 ArgoCD 本地用户（生产环境推荐集成 LDAP/OIDC，此处仅介绍本地用户）。

1. 查看当前登录用户

argocd accountwhoami

2. 修改当前用户密码

argocd account update-password

3. 列出所有本地用户

argocd account list

4. 创建/修改本地用户（需 ArgoCD 管理员权限）

# 编辑用户配置（直接修改 ConfigMap，ArgoCD 会自动加载）kubectl edit configmap argocd-cm -n argocd

场景5：日志与故障排查

# 查看应用的同步日志（实时跟踪，核心排查命令）argocd app logs<应用名>-f# -f 实时滚动输出，类似 tail -f# 查看 ArgoCD 组件日志（自身故障排查，如控制器卡死）argocd admin logs -n argocd# 需在 argocd 命名空间下执行

三、高级命令：admin 管理（管理员专用）

这类命令主要用于 ArgoCD 自身的运维和配置，需集群管理员权限。

1. 备份 ArgoCD 数据（核心运维命令）

argocd adminexport>argocd-backup-$(date+%Y%m%d).json

2. 恢复 ArgoCD 数据

argocd adminimport-<argocd-backup-20260129.json

3. 重启 ArgoCD 组件

argocd admin restart -n argocd# 等价于 kubectl rollout restart deployment -n argocd

4. 验证应用配置（提前排查 YAML 语法/资源冲突）

argocd admin validate<应用配置文件路径>

四、实用技巧与最佳实践

1. 命令别名简化：在.bashrc/.zshrc中添加别名，提高效率：

   aliasac="argocd"aliasaca="argocd app"aliasacl="argocd app list"aliasacg="argocd app get"aliasacs="argocd app sync"

   生效：source ~/.bashrc，之后可直接用acs <应用名>同步应用。

2. 脚本化批量操作：结合jq解析 JSON 输出，实现批量同步/排查：

   # 批量同步所有命名空间下的应用argocd app list -o json|jq -r'.[].metadata.name'|xargs-I{}argocd appsync{}--force

3. 避免重复登录：登录后 ArgoCD 会在~/.argocd/config中保存凭证，后续命令无需重复登录。

4. 生产环境禁用 --insecure：生产环境必须使用合法 SSL 证书，避免--insecure参数带来的安全风险。

总结

1. 核心流程：login（登录）→app create（创建应用）→app sync（同步应用）→app get（排查故障），覆盖日常大部分操作；
2. 应急命令：app terminate（终止卡壳同步）、app sync --force（强制同步）、admin export（备份），解决高频故障；
3. 最佳实践：复杂配置用 YAML 文件创建应用，不可变资源添加Replace=true注解，避免手动操作引入风险。

这份指南足够覆盖日常运维场景，若需某一命令的更细节用法，可执行argocd <命令> --help查看官方详细说明（如argocd app sync --help）。