1.文档概述

1.1  背景与适用范围

本手册面向腾讯云环境下的云原生运维团队，完整描述基于 K3s 与 Traefik v3 部署 ArgoCD 的全流程。适用于互联网、制造业、新能源等行业的中小规模 GitOps 平台建设场景。安装配置已针对国内网络环境（镜像拉取、大型 Chart 渲染超时、gRPC 路由）做生产级调优，并遵循 GitOps 核心理念。

1.2  技术架构

整体采用「入口层统一终结 TLS，内部 HTTP 明文」的分层架构，如下所示：

用户浏览器 / argocd CLI
        │
        ▼
Traefik v3（TLS 终结，443）
        │
        ▼
argocd-server（HTTP 明文，--insecure）
   │        │         │
   │        │         └──► Redis（会话缓存）
   │        └──────────► Repo Server（Helm / Kustomize 渲染）
   └───────────────────► Application Controller（同步 / 健康检查）
        │
        ▼
GitHub / GitLab / 企业 Git 服务（SSH Deploy Key 或 HTTPS Token）

架构说明：外部仅暴露 Traefik，ArgoCD 后端不直接面向公网；TLS 只在入口层终结，后端维持集群内 HTTP 明文，降低证书管理复杂度；Git 仓库默认只读，避免将 GitOps 控制面变成回写系统。

1.3  版本与环境信息

2.安装前置准备

2.1  客户端工具确认

在执行任何安装步骤前，确保以下工具已就绪并版本正确：

# 确认各工具版本
kubectl version --client
helm version
git --version
argocd version --client

# 测试 GitHub SSH 连通性（按需替换为内网 Git 服务）
ssh -T git@github.com

2.2  工程目录规范

建议统一工程目录，后续所有操作均在此目录下进行：

gitops-platform/
├── argocd/
│   └── install/
│       └── values.yaml          # ArgoCD Helm values
├── traefik/
│   └── argocd-traefik-routes.yaml
└── backup/

2.3  国内镜像策略

在国内网络场景下，所有 ArgoCD 官方镜像须提前同步至阿里云 ACR私有镜像仓库，以保证版本一致性与可追溯性。

注意：所有镜像、TLS 证书、SSH 私钥均不得明文提交进 Git 仓库。仓库中只存放可审计的配置声明，机密信息统一托管至密钥管理系统（如腾讯云 KMS 或 Vault）。

2.4  创建命名空间

kubectl create namespace argocd

2.5  导入 TLS 证书

将域名证书导入集群，供 Traefik 入口层引用：

kubectl create secret tls argocd-tls \
  -n argocd \
  --cert=/home/ops/ssl/argocd.example.com_bundle.pem \
  --key=/home/ops/ssl/argocd.example.com.key

注意：TLS 证书由 Traefik 统一管理，ArgoCD 后端只接收集群内部流量，无需在 Pod 层面再次配置证书。

3.Helm 安装配置

3.1  添加 Helm Chart 仓库

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

# 确认目标 Chart 版本存在
helm search repo argo/argo-cd --versions | head
-----------------------------------------------------------------
NAME            CHART VERSION   APP VERSION     DESCRIPTION                                       
argo/argo-cd    9.5.15          v3.4.2          A Helm chart for Argo CD, a declarative, GitOps...
argo/argo-cd    9.5.14          v3.4.2          A Helm chart for Argo CD, a declarative, GitOps...
argo/argo-cd    9.5.13          v3.4.1          A Helm chart for Argo CD, a declarative, GitOps...
argo/argo-cd    9.5.12          v3.4.1          A Helm chart for Argo CD, a declarative, GitOps...
argo/argo-cd    9.5.11          v3.3.9          A Helm chart for Argo CD, a declarative, GitOps...
argo/argo-cd    9.5.10          v3.3.8          A Helm chart for Argo CD, a declarative, GitOps...
argo/argo-cd    9.5.9           v3.3.8          A Helm chart for Argo CD, a declarative, GitOps...
argo/argo-cd    9.5.8           v3.3.8          A Helm chart for Argo CD, a declarative, GitOps...
argo/argo-cd    9.5.7           v3.3.8          A Helm chart for Argo CD, a declarative, GitOps...

3.2  生产基线 Values 详解

以下 values.yaml 为腾讯云 + K3s + Traefik v3 中小规模环境的生产最小可用基线。其中 repo-server 执行超时由默认 90 秒提升至 300 秒，以兼容大型 Helm Chart、复杂 Kustomize 及私有依赖下载场景。

# ──────────────────────────────────────────────────────────────────
# 文件路径：~/gitops-argocd/argocd/install/values.yaml
# ──────────────────────────────────────────────────────────────────
 
global:
  image:
    repository: <私有镜像仓库>/argoproj/argocd
    tag: v3.3.8
  domain: argocd.example.com
 
configs:
  params:
    # argocd-server 以 HTTP 明文运行，TLS 由 Traefik 统一终结
    server.insecure: "true"
    # 控制 Application Controller → Repo Server 的 RPC 超时（单位：秒）
    controller.repo.server.timeout.seconds: "300"
  cm:
    admin.enabled: true
    # 协调间隔：120s ± 60s（含抖动，防止大规模集群同时打满 Git 服务）
    timeout.reconciliation: 120s
    timeout.reconciliation.jitter: 60s
    # 0s 表示不设硬限制，即使协调长时间未完成也不强制中断
    timeout.hard.reconciliation: 0s
  rbac:
    policy.matchMode: glob
 
server:
  extraArgs:
    - --insecure
    # 控制 argocd-server API → Repo Server 的等待超时
    - --repo-server-timeout-seconds=300
  ingress:
    # 关闭 Helm Chart 自带 Ingress，改用 Traefik IngressRoute
    enabled: false
 
controller:
  replicas: 1
  resources:
    requests:
      cpu: 250m
      memory: 256Mi
    limits:
      cpu: "1"
      memory: 512Mi
 
repoServer:
  env:
    # 控制 Helm/Kustomize 渲染命令本身的执行超时
    - name: ARGOCD_EXEC_TIMEOUT
      value: 300s
  resources:
    requests:
      cpu: 200m
      memory: 256Mi
    limits:
      cpu: "1"
      memory: 512Mi
 
redis:
  image:
    repository: <私有镜像仓库>/redis
    tag: 8.6.2-alpine   # 请在私有仓库中确认该 Tag 可用
 
dex:
  # 暂不启用 SSO，如需接入 OIDC 可在后期开启
  enabled: false

超时参数说明（三层联动）：

3.3  安装 / 升级命令

进入安装目录后执行以下命令，首次安装与后续升级均使用同一条命令：

cd ~/gitops-argocd/argocd/install
 
helm upgrade --install argocd argo/argo-cd \
  --version 9.5.9 \
  -n argocd \
  -f values.yaml \
  --wait \
  --timeout 10m

3.4  部署状态验证

执行以下命令观察 Pod 启动状态，重点关注三个指标：

# 实时监控 Pod 状态
kubectl get pods -n argocd -w
 
# 查看最新事件（排查镜像拉取失败、OOM 等异常）
kubectl get events -n argocd --sort-by=.lastTimestamp

验证重点：repo-server 是否反复重启、controller 是否长时间 NotReady、所有镜像是否均从私有仓库拉起。

4.Traefik 路由配置

4.1  配置目录结构

建议将 Traefik 相关配置统一存放，便于 GitOps 管理：

traefik/
├── argocd-traefik-routes.yaml    # 本节完整配置（一文件三资源）

注意：K3s v1.32+ 内置 Traefik v3，语法与 v2 有差异：头部匹配使用 Header()，不是旧版的 Headers()；中间件跨命名空间引用需写成 <namespace>-<name>@kubernetescrd。

4.2  路由配置清单

以下一个 YAML 文件包含三个资源：HTTP→HTTPS 重定向中间件、HTTPS 路由、HTTP 路由。

# ──────────────────────────────────────────────────────────────────
# 文件名：argocd-traefik-routes.yaml
# 作用：为 ArgoCD 配置 Traefik 路由，实现：
#   1. HTTP（80）自动跳转 HTTPS（443）
#   2. HTTPS 反向代理至 ArgoCD Server（TLS 在此终结）
# 适用：K3s v1.32+（内置 Traefik v3）
# ──────────────────────────────────────────────────────────────────
 
# ── 资源 1：中间件 - HTTP 到 HTTPS 的 301 永久重定向 ──
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: argocd-https-redirect
  namespace: argocd
spec:
  redirectScheme:
    scheme: https
    permanent: true     # true = 301 永久重定向，有利于 SEO 和浏览器缓存
 
---
# ── 资源 2：HTTPS 路由 - 提供正式服务，执行 TLS 终结 ──
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: argocd-web
  namespace: argocd
spec:
  entryPoints:
    - websecure               # 绑定至 Traefik websecure 入口（443）
  routes:
    - kind: Rule
      match: Host(`argocd.example.com`)
      services:
        - name: argocd-server
          port: 80            # argocd-server Service 的 HTTP 端口
  tls:
    secretName: argocd-tls   # 引用第 2.5 节中创建的 TLS Secret
 
---
# ── 资源 3：HTTP 路由 - 接收 80 端口流量并触发重定向 ──
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: argocd-http
  namespace: argocd
spec:
  entryPoints:
    - web                     # 绑定至 Traefik web 入口（80）
  routes:
    - kind: Rule
      match: Host(`argocd.example.com`)
      middlewares:
        - name: argocd-https-redirect   # 引用资源 1 的中间件
      services:
        - name: argocd-server
          port: 80            # 实际不会收到流量，Traefik 要求至少声明一个 service
# 应用配置
kubectl apply -f traefik/argocd-traefik-routes.yaml
 
# 验证路由是否生效
kubectl get ingressroute -n argocd
curl -I http://argocd.example.com    # 预期返回 301 跳转
✅ 建议：UI 与 CLI 统一走 443，CLI 使用 --grpc-web 参数。如组织内明确要求原生 gRPC，需额外添加 h2c IngressRoute。

5.初始登录与密码管理

5.1  获取初始管理员密码

ArgoCD 安装成功后，初始管理员密码自动生成并存入 Secret，执行以下命令获取：

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d && echo

5.2  修改密码与安全建议

首次登录后应立即修改密码：

# 登录（--grpc-web 适配 Traefik 不支持原生 gRPC 的场景）
argocd login argocd.example.com --grpc-web
 
# 修改密码
argocd account update-password \
  --account admin \
  --current-password '<初始密码>' \
  --new-password '<强密码，不少于 16 位>'

6.Git 仓库接入

6.1  生成 Deploy Key

🔧 错误修正：原文命令 ssh-keygen ... -N 缺少参数，会导致交互式询问。正确写法为 -N "" 表示空口令，适合自动化场景。

ssh-keygen -t ed25519 \
  -C "argocd-deploy-key" \
  -f ~/.ssh/argocd_deploy_key \
  -N ""

6.2  Git 平台配置

将公钥（argocd_deploy_key.pub 内容）添加至 Git 仓库的 Deploy Keys：

• 权限默认设置为只读（不勾选 write access）

• 仅在确实需要自动回写的极少数场景下，才赋予写权限

• 一个 Deploy Key 对应一个仓库，不同仓库使用不同 Key

6.3  创建仓库 Secret

将 SSH 私钥以 Kubernetes Secret 形式注入集群（stringData 字段仅限初始创建，不要将私钥提交至 Git）：

apiVersion: v1
kind: Secret
metadata:
  name: gitops-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
type: Opaque
stringData:
  url: git@github.com:org/repo.git
  sshPrivateKey: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    <此处粘贴私钥内容>
    -----END OPENSSH PRIVATE KEY-----
kubectl apply -f gitops-repo-secret.yaml

⚠ 注意：请勿将含有 sshPrivateKey 的 Secret YAML 提交至 Git 仓库，应使用 Sealed Secrets 或外部密钥注入方案管理。

6.4  验证仓库连通性

# 列出已注册仓库
argocd repo list --grpc-web
 
# 测试指定仓库连接
argocd repo get git@github.com:org/repo.git --grpc-web

7.App of Apps 初始化

App of Apps 模式通过「根应用管理子应用」实现平台与业务的分层治理：平台团队只维护根应用，业务团队只维护自己目录下的 Application 或 ApplicationSet，互不干扰，变更可审计。

# 创建根应用
argocd app create root-app \
  --repo git@github.com:org/gitops-repo.git \
  --path apps \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace argocd \
  --revision main \
  --sync-policy automated \
  --auto-prune \
  --self-heal \
  --grpc-web
 
# 触发首次同步
argocd app sync root-app --grpc-web
 
# 查看应用状态
argocd app get root-app --grpc-web

建议：应用数量增多后，建议引入 ApplicationSet（支持 Git Generator、矩阵 Generator 等），减少重复 YAML，统一管理多环境 / 多集群部署。

8.备份与恢复

8.1  备份对象清单

8.2  备份命令

mkdir -p ~/gitops-argocd/backup
 
# 配置 ConfigMap
kubectl get configmap -n argocd argocd-cm     -o yaml > backup/argocd-cm.yaml
kubectl get configmap -n argocd argocd-rbac-cm -o yaml > backup/argocd-rbac-cm.yaml
 
# TLS Secret
kubectl get secret -n argocd argocd-tls       -o yaml > backup/argocd-tls.yaml
 
# 所有 Application 定义
kubectl get applications -A                    -o yaml > backup/all-applications.yaml
 
# Traefik 路由
kubectl get ingressroute -n argocd            -o yaml > backup/ingressroutes.yaml

8.3  恢复顺序说明

恢复顺序直接影响控制器是否能正常接管已有资源，建议按以下顺序执行：

9.升级策略

9.1  升级前准备

每次升级前须完成以下检查，避免升级引发数据不兼容或服务中断：

• 查阅 ArgoCD 官方 Release Notes，确认是否存在 Breaking Changes（尤其注意大版本跨越）

• 确认私有镜像仓库中新版本镜像已同步完毕

• 在测试环境完成验证后，再执行生产升级

• 执行备份（参考第八章）

# 更新 Helm 仓库，获取最新 Chart 版本列表
helm repo update
helm search repo argo/argo-cd --versions | head -10

9.2  执行升级

将 values.yaml 中的镜像 tag 更新为新版本后，执行升级命令与安装命令完全相同：

# 修改 values.yaml 中的 image.tag
vim ~/gitops-argocd/argocd/install/values.yaml
 
# 执行升级
helm upgrade --install argocd argo/argo-cd \
  --version <新 Chart 版本> \
  -n argocd \
  -f values.yaml \
  --wait \
  --timeout 10m
 
# 升级后验证
kubectl get pods -n argocd
argocd version --grpc-web
argocd app list --grpc-web

9.3  回滚方案

若升级后出现异常，可通过 Helm 回滚至上一个 Release：

# 查看 Helm Release 历史
helm history argocd -n argocd
 
# 回滚至指定版本（REVISION 从上方命令获取）
helm rollback argocd <REVISION> -n argocd --wait --timeout 10m
 
# 确认回滚后 Pod 状态
kubectl get pods -n argocd

 注意：跨大版本（如 v2.x → v3.x）的回滚可能涉及 CRD Schema 不兼容，回滚前务必确认应用 CR 格式是否在旧版 CRD 中仍然有效。