Argo CD 私有仓库接入全指南：凭据配置、证书信任与 Helm/OCI 仓库管理-迪斯科星球

Argo CD 私有仓库接入全指南：凭据配置、证书信任与 Helm/OCI 仓库管理

【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd

本文围绕 Argo CD（Kubernetes 的声明式持续部署工具）中私有 Git 仓库的接入与认证展开，系统讲解 HTTPS/SSH 凭据、GitHub App、Google Cloud Source、Azure 工作负载身份等主流认证方式，以及自签名 TLS 证书、SSH known hosts、凭据模板、Helm/OCI 私有仓库和 Git 子模块等进阶主题。读完本文，你将能够为私有仓库场景配置正确的认证方式、解决"x509 未知证书颁发机构"与"unknown SSH host"等常见报错，并掌握 CLI、Web UI 与声明式（Secret/ConfigMap）三种配置入口的完整用法。

前置须知：GitLab 等平台的`.git`后缀重定向问题

在开始配置任何凭据之前，先留意一个容易踩坑的细节：部分 Git 托管平台（尤其是 GitLab，以及自托管的 on-premise GitLab 实例）要求仓库 URL 必须携带.git后缀，否则它们会返回一个指向"带.git后缀 URL"的 HTTP 301 重定向。

Argo CD 不会跟随这类 301 重定向，因此如果你添加仓库时省略了.git，连接测试会失败。解决办法很简单：把仓库 URL 显式写成带.git后缀的形式，例如https://gitlab.example.com/group/project.git。

凭据（Credentials）配置总览

如果应用清单存放在私有仓库中，就必须为 Argo CD 配置仓库凭据。Argo CD 同时支持 HTTPS 与 SSH 两类 Git 凭据，覆盖了主流的认证协议。无论使用哪种方式，凭据最终都会以 Kubernetes Secret 的形式存储在 Argo CD 的命名空间中，由 repo-server 组件在拉取清单时使用。

HTTPS 用户名与密码凭据

需要用户名和密码认证的私有仓库，其 URL 通常以https://开头（而非git@或ssh://）。凭据可以通过 CLI 或 Web UI 两种方式配置。

方式一：CLI 配置

argocd repo add https://github.com/argoproj/argocd-example-apps --username <username> --password <password>

方式二：Web UI 配置

导航到Settings/Repositories，进入仓库管理页面；
点击Connect Repo using HTTPS按钮，填写仓库 URL 与用户名/密码；
点击Connect，Argo CD 会先测试连接，测试通过后仓库即被添加。

使用 Access Token（访问令牌）

除了用户名和密码，更推荐使用各托管平台颁发的访问令牌（Access Token）。请按照你的 Git 托管服务的说明生成令牌：

GitHub：Personal Access Token
GitLab：Deploy Tokens（项目级部署令牌）
Bitbucket Server：Personal Access Tokens
Azure Repos：Personal Access Tokens

生成令牌后，使用任意非空字符串作为用户名，将访问令牌值作为密码来连接仓库。这里有几个平台特例需要记住：

某些服务要求用户名填写你的账户名，而不是任意字符串；
Bitbucket Cloud 与 Bitbucket Data Center 必须将用户名指定为x-token-auth。

提示：argocd repo add命令在 CLI 层面对参数做了严格校验。从 cmd/argocd/commands/repo.go 的源码可以看到，--ssh-private-key-path只允许用于 SSH 仓库、--gcp-service-account-key-path只允许用于 HTTPS 仓库、--tls-client-cert-path与--tls-client-cert-key-path必须成对出现，否则命令会直接报错终止，避免把无效的凭据组合写入集群。

HTTPS 仓库的 TLS 客户端证书

如果你的仓库服务器要求使用 TLS 客户端证书（mutual TLS）进行认证，可以为argocd repo add命令添加两个开关，分别指定本地文件中存放的客户端证书与其对应的私钥：

argocd repo add https://repo.example.com/repo.git --tls-client-cert-path ~/mycert.crt --tls-client-cert-key-path ~/mycert.key

注意事项：

--tls-client-cert-path与--tls-client-cert-key-path必须始终一起指定，源码中对此有显式校验；
如果仓库服务器同时要求用户名/密码，可与--username、--password开关组合使用；
证书与私钥数据必须是PEM 格式，不支持 PKCS12 等其他格式；
私钥不能设置密码保护，否则 Argo CD 无法使用；
在 Web UI 中添加 HTTPS 仓库时同样可以粘贴 TLS 客户端证书与私钥，但粘贴时务必避免产生多余换行或额外字符。

从存储层面看，这些证书内容会以tlsClientCertData、tlsClientCertKeyData等键写入仓库 Secret，可参考 util/db/repository_secrets.go 中的读写逻辑。

SSH 私钥凭据

需要 SSH 私钥认证的私有仓库，其 URL 通常以git@或ssh://开头（而非https://）。

CLI 方式：

argocd repo add git@github.com:argoproj/argocd-example-apps.git --ssh-private-key-path ~/.ssh/id_rsa

UI 方式：

导航到Settings/Repositories；
点击Connect Repo using SSH，输入 URL 并粘贴 SSH 私钥；
点击Connect测试连接并完成添加。

两个易错点：

粘贴私钥时：Web UI 文本框中不能有多余换行或额外字符，否则私钥解析会失败；
非标准端口：如果 SSH 服务运行在非标准端口，必须使用ssh://风格的 URL 来指定端口。scp 风格（git@yourgit.com:yourrepo）的 URL不支持指定端口，任何端口号都会被当作仓库路径的一部分。

版本兼容提示：Argo CD 2.4 起升级到 OpenSSH 8.9，而 OpenSSH 8.8 已经移除了对ssh-rsaSHA-1 密钥签名算法的支持。如果你的 SSH 服务器仍依赖旧算法，请参考升级指南中关于 SSH 服务器兼容性测试与绕过方案的说明。

GitHub App 凭据

托管在 GitHub.com 或 GitHub Enterprise 上的私有仓库，可以使用 GitHub Application 的凭据访问。请先在 GitHub 上创建应用，并确保应用至少拥有仓库Contents的Read-only权限（这是最低要求）。

CLI 方式：

argocd repo add https://github.com/argoproj/argocd-example-apps.git --github-app-id 1 --github-app-installation-id 2 --github-app-private-key-path test.private-key.pem

如果是 GitHub Enterprise 的私有仓库，需要额外添加--github-app-enterprise-base-url https://ghe.example.com/api/v3标志；
--github-app-installation-id标志是可选的。省略时，Argo CD 会根据仓库所属组织自动发现 installation ID。

UI 方式：

导航到Settings/Repositories；
点击Connect Repo using GitHub App，选择类型：GitHub或GitHub Enterprise，输入 URL、App Id、Installation Id（可选）以及应用的私钥；选择GitHub Enterprise类型时还需填写 GitHub Enterprise Base URL；
点击Connect测试连接。

提示：在 UI 中粘贴 GitHub App 私钥时同样要确保没有意外换行或多余字符。CLI 命令的完整参数清单可参见 cmd/argocd/commands/repo.go 中的示例，githubAppID 等字段会以githubAppID键持久化到仓库 Secret（见 util/db/repository_secrets.go）。

Google Cloud Source

托管在 Google Cloud Source 上的私有仓库，可以使用 JSON 格式的 Google Cloud 服务账号密钥访问。请先在 Google Cloud 中创建服务账号，并确保其至少拥有该 Google Cloud 项目的Source Repository Reader权限（最低要求）。

CLI 方式：

argocd repo add https://source.developers.google.com/p/my-google-cloud-project/r/my-repo --gcp-service-account-key-path service-account-key.json

UI 方式：

导航到Settings/Repositories；
点击Connect Repo using Google Cloud Source，输入 URL 与 JSON 格式的服务账号密钥；
点击Connect测试连接。

Azure Container Registry / Azure Repos（Azure Workload Identity）

Argo CD 支持使用 Azure Workload Identity 访问 Azure Container Registry（ACR）与 Azure Repos 中的私有仓库。使用前需要完成以下准备工作：

为 Pod 打标签：给 repo-server 的 Pod 添加azure.workload.identity/use: "true"标签；
创建联合身份凭据（Federated Identity Credential）：为 repo-server 的服务账号生成 Azure 联合身份凭据；
为服务账号添加注解：在 repo-server 服务账号上添加azure.workload.identity/client-id: "$CLIENT_ID"注解（CLIENT_ID来自工作负载身份）；
配置 ACR 权限：为工作负载身份授予 Azure Container Registry 或 Azure Repos 所需的权限；
设置 ACR Token 资源变量：将 Argo CD repo-server 的环境变量AZURE_ARM_TOKEN_RESOURCE设置为https://containerregistry.azure.net，Argo CD 才能请求有效的 ACR 访问令牌。

源码佐证：该环境变量在 util/helm/creds.go 中被读取（env.StringFromEnv("AZURE_ARM_TOKEN_RESOURCE", ...)），默认值为https://management.core.windows.net，因此对接 ACR 时必须显式覆盖为https://containerregistry.azure.net。

CLI 方式（Helm OCI 仓库）：

argocd repo add contoso.azurecr.io/charts --type helm --enable-oci --use-azure-workload-identity

CLI 方式（Azure Repos）：

argocd repo add https://contoso@dev.azure.com/my-projectcollection/my-project/_git/my-repo --use-azure-workload-identity

UI 方式：

导航到Settings/Repositories，点击+ Connect Repo；
在连接页面选择连接方式为VIA HTTPS，类型选择git或helm；
输入仓库 URL；如果类型是 helm，还需输入 name，并在需要时勾选Enable OCI；
勾选Use Azure Workload Identity；
点击Connect。

Secret 定义方式：也可以在仓库 Secret 中通过useAzureWorkloadIdentity: "true"开启（该字段在 util/db/repository_secrets.go 中通过boolOrFalse解析，并有对应测试用例验证，见 util/db/repository_secrets_test.go）：

apiVersion: v1 kind: Secret metadata: name: helm-private-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: type: helm url: contoso.azurecr.io/charts name: contosocharts enableOCI: "true" useAzureWorkloadIdentity: "true" --- apiVersion: v1 kind: Secret metadata: name: git-private-repo namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: type: git url: https://contoso@dev.azure.com/my-projectcollection/my-project/_git/my-repo useAzureWorkloadIdentity: "true"

Azure DevOps（Service Principal 服务主体）

Azure DevOps 仓库也可以使用服务主体（Service Principal）的凭据访问。请先按照微软官方文档创建服务主体并配置其对 Azure DevOps 的访问权限，并确保服务主体至少拥有包含仓库的Project的Project Readers权限（最低要求）。

CLI 方式：

argocd repo add https://dev.azure.com/my-devops-organization/my-devops-project/_git/my-devops-repo --azure-service-principal-tenant-id 12345678-1234-1234-1234-123456789012 --azure-service-principal-client-id 12345678-1234-1234-1234-123456789012 --azure-service-principal-client-secret test

如果使用的是非公有云（例如德国云等），还需要添加--azure-active-directory-endpoint https://login.microsoftonline.de标志。

UI 方式：

导航到Settings/Repositories；
点击Connect Repo，选择连接方式Via Azure Service Principal，输入 URL、Tenant Id、Client Id、Client Secret，以及非默认公有云时的 Active Directory Endpoint；
点击Connect测试连接。

凭据模板（Credential Templates）

如果多个仓库共享同一套凭据，不必为每个仓库重复配置。Argo CD 支持凭据模板：为某个 URL 前缀设置凭据后，所有以该前缀开头的仓库（且未配置自己的凭据）都会自动套用。

例如，为 URL 前缀https://github.com/argoproj设置凭据模板后，https://github.com/argoproj/argocd-example-apps等仓库都会自动使用这套凭据。

Web UI 方式：在Connect repo using SSH或Connect repo using HTTPS对话框中填写凭据信息，但不要点击Connect，而是选择Save as credential template。注意Repository URL字段只填前缀 URL（如https://github.com/argoproj），不要填完整仓库 URL。

CLI 方式：使用repocreds子命令管理凭据模板：

# 为 URL 前缀 https://github.com/argoproj 添加用户名/密码模板 argocd repocreds add https://github.com/argoproj --username youruser --password yourpass # 列出与删除凭据模板 argocd repocreds list argocd repocreds rm <url-prefix>

凭据模板要生效，必须同时满足两个条件：

目标仓库要么完全未配置，要么已配置但不含任何凭据信息；
凭据模板的 URL 必须是仓库 URL 的前缀。

配套说明与注意事项：

只有在匹配的仓库凭据模板配置好之后，才可以通过 CLI 或 Web UI 在不指定凭据的情况下添加需要认证的仓库；
前缀匹配遵循best match（最长匹配优先）原则：最长的匹配前缀优先级最高，定义的先后顺序不影响结果（这与 v1.4 之前的行为不同）。

下面是一个完整的 CLI 演示会话，展示了凭据模板的典型用法：

# 尝试添加私有仓库但不提供凭据 —— 失败 $ argocd repo add https://docker-build/repos/argocd-example-apps FATA[0000] rpc error: code = Unknown desc = authentication required # 为 https://docker-build/repos 下的所有仓库建立凭据模板 $ argocd repocreds add https://docker-build/repos --username test --password test repository credentials for 'https://docker-build/repos' added # 再次添加仓库（不指定凭据），URL 前缀命中模板 —— 成功 $ argocd repo add https://docker-build/repos/argocd-example-apps repository 'https://docker-build/repos/argocd-example-apps' added # 添加同一前缀下的另一个仓库，但显式指定了错误凭据 —— 失败（自带凭据不再使用模板） $ argocd repo add https://docker-build/repos/example-apps-part-two --username test --password invalid FATA[0000] rpc error: code = Unknown desc = authentication required

从实现上看，repo-server 在解析仓库凭据时会先从凭据模板中继承相关字段（包括UseAzureWorkloadIdentity等），再合并仓库自身配置，相关逻辑可见 reposerver/repository/repository.go。

自签名与不受信任的 TLS 证书

如果目标 HTTPS 仓库服务器使用的是自签名证书，或由 Argo CD 不认识的私有 CA 签发，出于安全考虑仓库将无法添加，典型报错为x509: certificate signed by unknown authority。此时有两种处理方案：

跳过服务器证书校验：使用--insecure-skip-server-verification标志添加仓库。⚠️ 这会使连接暴露于中间人攻击风险，仅建议用于非生产环境；
导入自定义 CA 证书：使用argocd cert add-tls命令将服务器证书或其签名 CA 的证书（PEM 格式）导入 Argo CD。这是推荐的生产级做法。

三个重要的补充说明：

对于无效的服务器证书（如服务器名不匹配、证书已过期），添加 CA 证书无效，唯一办法是使用--insecure-skip-server-verification标志，因此强烈建议让仓库服务器使用有效证书；
TLS 证书是按服务器（per-server）配置的，而非按仓库配置。同一台服务器下的多个仓库，证书只需配置一次；
argocd cert命令的变更传播到整个集群可能需要几分钟，具体取决于你的 Kubernetes 环境。

使用 CLI 管理 TLS 证书

列出已配置的 HTTPS 证书：

$ argocd cert list --cert-type https HOSTNAME TYPE SUBTYPE FINGERPRINT/SUBJECT docker-build https rsa CN=ArgoCD Test CA localhost https rsa CN=localhost

以不安全方式添加 HTTPS 仓库（不推荐用于生产）：

argocd repo add --insecure-skip-server-verification https://git.example.com/test-repo

导入 CA 证书并正常添加仓库（推荐）：

argocd cert add-tls git.example.com --from ~/myca-cert.pem argocd repo add https://git.example.com/test-repo

同时配置新旧两份证书（证书轮换场景）：可以一次为同一服务器添加多个 PEM（将多个 PEM 拼接后输入）。如果服务器即将更换证书（可能由不同的 CA 签发），可以同时保留旧证书与新证书；若旧证书已配置，使用--upsert标志一次性写入新旧两份：

cat cert1.pem cert2.pem | argocd cert add-tls git.example.com --upsert

提示：要替换服务器已有的证书，必须给cert add-tls命令加--upsert标志。

删除 TLS 证书：

argocd cert rm --cert-type https localhost

使用 Web UI 管理 TLS 证书

点击左侧导航栏的Settings，在设置菜单中选择Certificates；
该页面会列出所有已配置的证书，并提供添加 TLS 证书或 SSH known hosts 条目的入口；
点击Add TLS certificate，填写数据后点击Create。注意：只填写仓库服务器的 FQDN（不要写完整 URL），并将完整的 PEM 证书（包括----BEGIN CERTIFICATE----与----END CERTIFICATE----行）完整粘贴到文本框中；
删除证书时，点击证书条目旁的三点按钮，选择Remove并在确认对话框中确认。

使用声明式配置管理 TLS 证书

在自管理（declarative）的 Argo CD 部署中，所有 TLS 证书存放在 ConfigMap 对象argocd-tls-certs-cm中。更多细节可参考操作手册-声明式配置中关于"使用自签名 TLS 证书或由自定义 CA 签名的仓库"一节。

未知 SSH 主机（Unknown SSH Hosts）

如果通过 SSH 访问私有托管的 Git 服务，同样有两种方案：

跳过主机密钥校验：使用--insecure-skip-server-verification标志添加仓库。⚠️ 同样仅建议用于非生产环境（存在中间人攻击风险）；
导入服务器的 SSH 公钥：使用argocd cert add-ssh命令将服务器公钥（known_hosts格式）导入 Argo CD。这是推荐的生产级做法。可以通过ssh-keyscan工具获取服务器的公钥。

注意：argocd cert命令的变更传播需要几分钟。另外，从known_hosts文件导入时，其中的主机名或 IP 地址不能是哈希过的。如果known_hosts文件包含哈希条目（|1|...形式），则无法作为 CLI 或 UI 的输入源；若坚持使用哈希数据，只能走声明式配置，但这会破坏 CLI 与 UI 的证书管理功能，通常不推荐。

使用 CLI 管理 SSH Known Hosts

列出已配置的 SSH known host 条目：

$ argocd cert list --cert-type ssh HOSTNAME TYPE SUBTYPE FINGERPRINT/SUBJECT bitbucket.org ssh ssh-rsa SHA256:46OSHA1Rmj8E8ERTC6xkNcmGOw9oFxYr0WF6zWW8l1E github.com ssh ssh-rsa SHA256:uNiVztksCsDhcc0u9e8BujQXVUpKZIDTMczCvj3tD2s gitlab.com ssh ecdsa-sha2-nistp256 SHA256:HbW3g8zUjNSksFbqTiUWPWg2Bq1x8xdGUrliXFzSnUw gitlab.com ssh ssh-ed25519 SHA256:eUXGGm1YGsMAS7vkcx6JOJdOGHPem5gQp4taiCfCLB8 gitlab.com ssh ssh-rsa SHA256:ROQFvPThGrW4RuWLoL9tq9I9zJ42fK4XywyRtbOz/EQ ssh.dev.azure.com ssh ssh-rsa SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og vs-ssh.visualstudio.com ssh ssh-rsa SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og

添加 SSH known host 条目：使用argocd cert add-ssh命令，可以从文件添加（--from <file>），也可以在指定--batch后从stdin读取；两种方式输入都必须是 OpenSSH 客户端可识别的known_hosts格式。

用ssh-keyscan收集服务器全部公钥并导入：

ssh-keyscan server.example.com | argocd cert add-ssh --batch

直接导入现有known_hosts文件：

argocd cert add-ssh --batch --from /etc/ssh/ssh_known_hosts

删除 SSH known host 条目：

argocd cert rm bitbucket.org --cert-type ssh

如果同一主机存在多种密钥子类型（如上例中 gitlab.com 同时有ssh-rsa、ssh-ed25519、ecdsa-sha2-nistp256三种），只想删除其中一种时，可以用--cert-sub-type进一步缩小范围：

argocd cert rm gitlab.com --cert-type ssh --cert-sub-type ssh-ed25519

使用 Web UI 管理 SSH Known Hosts

点击左侧导航栏的Settings，选择Certificates；
在证书管理页面点击Add SSH known hosts，将 SSH known hosts 数据粘贴到输入框中。注意：粘贴时条目的 key 数据不能有换行，然后点击Create；
删除条目时，点击条目旁的三点按钮，选择Remove并确认。

使用声明式配置管理 SSH Known Hosts

在自管理（declarative）的 Argo CD 部署中，所有 SSH 公钥存放在 ConfigMap 对象argocd-ssh-known-hosts-cm中（相关写入逻辑可参考 util/settings/settings.go）。更多细节请参考操作手册-声明式配置中的"SSH Known Host Public Keys"一节。

受保护的 Helm 仓库与 OCI 私有仓库

Helm chart 可以来自受保护的 Helm 仓库或 OCI 私有注册中心。配置方法与普通 Git 仓库类似，只需将仓库类型指定为helm（针对 HTTPS 仓库）。

CLI 方式：为argocd repo add指定--type标志：

argocd repo add https://argoproj.github.io/argo-helm --type=helm <additional-flags>

UI 方式：

导航到Settings/Repositories；
点击Connect Repo；
连接方式选择VIA HTTPS；
类型（Type）选择helm；
点击Connect测试连接。

受保护的 OCI 注册中心：Helm chart 存放在 OCI 注册中心时，需显式声明来源是 OCI 中的 Helm chart。使用 CLI 时指定--enable-oci标志：

argocd repo add registry-1.docker.io/bitnamicharts --type=helm --enable-oci=true <additional-flags>

注意：引用 OCI 注册中心时，应省略oci://协议前缀，直接写注册中心地址。

UI 方式则是在添加基于 HTTPS 的helm仓库时勾选Enable OCI复选框。需要说明的是，在 Secret 定义中enableOCI: "true"与useAzureWorkloadIdentity: "true"等布尔字段均有对应的字符串解析逻辑，可参考 util/db/repository_secrets.go 中的boolOrFalse实现。

自定义 HTTP User-Agent

部分 Helm 仓库提供商（如 Wikimedia）的机器人访问策略要求特定的 User-Agent 请求头。默认情况下，Argo CD 会对所有 Helm 仓库请求自动发送argocd-repo-server/<version> (<platform>)格式的 User-Agent。

如需自定义 User-Agent（例如加入组织名或联系方式），可在argocd-repo-serverDeployment 上设置ARGOCD_HELM_USER_AGENT环境变量：

apiVersion: apps/v1 kind: Deployment metadata: name: argocd-repo-server spec: template: spec: containers: - name: argocd-repo-server env: - name: ARGOCD_HELM_USER_AGENT value: "my-org/argocd (team@example.com)"

该环境变量对所有Helm 仓库请求全局生效。

Git 子模块（Submodules）

Argo CD 原生支持 Git 子模块，且会自动检测并拉取。需要留意的是：

如果子模块仓库需要认证，其凭据必须与父仓库的凭据一致；
可通过设置环境变量ARGOCD_GIT_MODULES_ENABLED=false关闭子模块支持。该环境变量的名称在 common/common.go 中以EnvGitSubmoduleEnabled = "ARGOCD_GIT_MODULES_ENABLED"定义，对应 repo-server 的开关。

声明式配置入口

以上所有仓库与凭据配置，在 Argo CD 的自管理（declarative）部署模式下都可以通过 Kubernetes 原生对象声明：仓库与凭据模板使用带argocd.argoproj.io/secret-type: repository标签的 Secret，TLS 证书存放在argocd-tls-certs-cmConfigMap，SSH known hosts 存放在argocd-ssh-known-hosts-cmConfigMap。完整的字段清单与示例请参考操作手册-声明式配置中的 Repositories 一节，这也是 GitOps 模式下将仓库凭据纳入版本管理、实现完全声明化运维的推荐做法。

<output_article_end>

【免费下载链接】argo-cdDeclarative Continuous Deployment for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/ar/argo-cd

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析