Argo CD 部署与 Jenkins(CI) / Argo CD(CD) 流程改造方案

01现状勘察结论

先把“当前真实跑着什么”钉死。下面每一条都是现场读出来的，不是推测。

1.1 节点与集群底座

4 个节点全部通过 Tailscale 组网，kubectl 的 API Server 挂在 Jenkins 那台机器上，它同时兼任控制平面：

1.2 若依微服务的实际形态

应用全部落在 ruoyi 命名空间，形态是「7 个 Deployment + 7 个 NodePort Service + 1 个 Ingress」：

另外几个关键事实：

• 镜像仓库：私有 Harbor 106.75.29.47:10086，项目 ruoyi-cloud，tag 一律是「秒级时间戳」（yyyyMMddHHmmss）。
• 拉取凭据：ruoyi 命名空间里有 harbor-secret / harbor-cred 两个 dockerconfigjson，Deployment 通过 imagePullSecrets 引用 harbor-secret。
• 配置管理：该命名空间只有一个 ConfigMap ruoyi-gateway-config（以 subPath 挂到 /home/ruoyi/application.yml）；其余服务的配置是打进镜像里的。Redis 指向 106.75.29.47:6379。
• Ingress：ruoyi-gateway-ingress，ingressClassName: nginx，无域名（host 为 *），全部 / 转发到 gateway。
• 前端不在集群里：ruoyi-ui 是宿主机 Nginx 直接托管 /opt/ruoyi/dist（/etc/nginx/conf.d/ruoyi.conf，server_name 106.75.30.92）。仓库里虽然有 ruoyi-ui 的 k8s 清单，但没有真的部署到集群。
• 中间件全在另一台机器：106.75.29.47 上开放了 3306(MySQL)、6379(Redis)、8848/9848(Nacos)、10086(Harbor)、80/8080。

1.3 Jenkins 现状

现有 Jenkinsfile 的部署逻辑（以 gateway 为例，原文摘要）

stage('代码编译打包')  →  mvn clean package -Dmaven.test.skip=true
stage('构建 Docker 镜像') →  docker build -t ${HARBOR_URL}:latest .  &&  docker tag ... :$VERSION
stage('推送镜像到 Harbor') →  docker push ...:latest && docker push ...:$VERSION
stage('部署到 K8s')     →  sed -i 's/:latest/:$VERSION/g' k8s/deployment.yaml
                          kubectl apply -f k8s/deployment.yaml -n ruoyi
post.success           →  docker rmi ...（清理本地镜像）

其中 VERSION = date '+%Y%m%d%H%M%S'，k8s/deployment.yaml 随代码仓库一起维护。

02目标架构与职责边界

改造后的职责划分用一句话概括：Jenkins 只负责“把代码变成镜像并把镜像题写进 Git”，Argo CD 负责“把 Git 里的期望状态搬到集群”。Jenkins 不再需要集群的写权限。

2.1 改造前后对比

2.2 关于 ruoyi-ui 前端的一个明确取舍

现状前端是宿主机 Nginx 托管静态目录，不在集群内。本次改造建议不动它，理由：它的发布物是静态文件而非镜像，纳入 GitOps 需要先把 ruoyi-ui 容器化后进集群，属于独立的架构调整，与本轮「引入 Argo CD」目标不同。文档里会给出一条可选路径（见 §10.6），但不作为本轮必须项。

03版本选型与兼容性论证

这一步是整份方案里最容易踩坑的地方，必须先定死。

因此本方案锁定 Argo CD v2.14.21（2.14 分支末版）。

3.1 装机位置与资源预算

集群内存偏紧（node1 76%、node2 93%），而 jenkins 节点带 control-plane 污点、Argo CD 的 Pod 不会调度上去。因此选 k8s-node3（7.4Gi 分配，当前 70%，余量约 2.2Gi，2 核）作为 Argo CD 的落脚点，并用 nodeSelector 固定，避免被调度到只剩几百 Mi 的 node1/node2 上导致 OOM。

limits 之和超过 node3 的 2 核，但这是 limit 不是预留，实际稳态占用通常在 300m / 600Mi 量级。requests 的 900Mi 是真正把 node3 余量吃掉的部分，仍在安全范围内。

04阶段一：安装 Argo CD（国内镜像全链路）

安装分三步：准备清单 → 把 3 个镜像搬进自己的 Harbor → apply 并打补丁。全程不依赖 quay.io 的裸网络。

4.1 先看清要装的到底是什么

v2.14.21 的 install.yaml（1425427 字节）一共 59 个资源段，需要的外部镜像只有 3 个：

安装会产生：3 个 CRD、7 个 ServiceAccount、若干 Role/Binding、7 个 ConfigMap、2 个 Secret、8 个 Service、6 个 Deployment、1 个 StatefulSet（application-controller）、7 个 NetworkPolicy。

4.2 国内镜像地址实测结果

4.3 第一步：准备安装清单

# 在 106.75.30.92 上执行
mkdir -p /root/argocd/{manifests,offline} && cd /root/argocd

# 下载 v2.14.21 官方安装清单（走国内加速）
curl -fL --retry 3 -o manifests/install-v2.14.21.yaml \
  https://gh-proxy.com/https://raw.githubusercontent.com/argoproj/argo-cd/v2.14.21/manifests/install.yaml

# 校验：应为 1425427 字节
wc -c manifests/install-v2.14.21.yaml

# 下载 argocd CLI（可选，但强烈建议装，后面验收和触发同步都要用）
curl -fL --retry 3 -o /usr/local/bin/argocd \
  https://files.m.daocloud.io/github.com/argoproj/argo-cd/releases/download/v2.14.21/argocd-linux-amd64
chmod +x /usr/local/bin/argocd && argocd version --client

4.4 第二步：把 3 个镜像搬进自己的 Harbor

虽然 quay.io 在本环境能直连，但用它拉取有两个问题：速度不稳定、集群对公网有外部依赖。既然已经有 Harbor，把它当作集群的唯一镜像入口是更干净的架构——顺带也让 Argo CD 自身的升级走同一套流程。

# 0) Harbor 里创建 infra 项目（若不存在）
#    也可以直接在执行 docker push 时由 Harbor 自动创建（若开启了自动创建项目）
#    手动创建：Harbor UI → 项目 → 新建项目 → 名称 infra → 私有

# 1) 登录 Harbor
docker login 106.75.29.47:10086 -u admin -p '@Pl000000'

# 2) 从国内镜像源拉取，重新打标签，推入 Harbor
set -e
HARBOR=106.75.29.47:10086

docker pull quay.m.daocloud.io/argoproj/argocd:v2.14.21
docker tag  quay.m.daocloud.io/argoproj/argocd:v2.14.21 ${HARBOR}/infra/argocd:v2.14.21
docker push ${HARBOR}/infra/argocd:v2.14.21

docker pull ghcr.m.daocloud.io/dexidp/dex:v2.41.1
docker tag  ghcr.m.daocloud.io/dexidp/dex:v2.41.1 ${HARBOR}/infra/dex:v2.41.1
docker push ${HARBOR}/infra/dex:v2.41.1

docker pull m.daocloud.io/docker.io/library/redis:7.2.11-alpine
docker tag  m.daocloud.io/docker.io/library/redis:7.2.11-alpine ${HARBOR}/infra/redis:7.2.11-alpine
docker push ${HARBOR}/infra/redis:7.2.11-alpine

# 3) 清理本地临时镜像，避免占满 /（当前 99G 盘已用 58%）
docker rmi quay.m.daocloud.io/argoproj/argocd:v2.14.21 \
           ghcr.m.daocloud.io/dexidp/dex:v2.41.1 \
           m.daocloud.io/docker.io/library/redis:7.2.11-alpine || true

mkdir -p /etc/containerd/certs.d/quay.io
cat > /etc/containerd/certs.d/quay.io/hosts.toml <<'EOF'
server = 'https://quay.io'

[host.'https://quay.m.daocloud.io']
  capabilities = ['pull', 'resolve']
  override_path = true
EOF
systemctl restart containerd      # 注意：重启 containerd 会短暂影响该节点上的容器运行时

4.5 第三步：改造清单并安装

cd /root/argocd
HARBOR=106.75.29.47:10086
cp manifests/install-v2.14.21.yaml manifests/install-harbor.yaml

# 把 3 个外部镜像全部替换成自己的 Harbor 地址
sed -i \
  -e "s#quay.io/argoproj/argocd:#${HARBOR}/infra/argocd:#g" \
  -e "s#ghcr.io/dexidp/dex:#${HARBOR}/infra/dex:#g" \
  -e "s#image: redis:7.2.11-alpine#image: ${HARBOR}/infra/redis:7.2.11-alpine#g" \
  manifests/install-harbor.yaml

# 确认替换干净：这里应该只剩下 infra/ 开头的 3 类镜像，没有 quay.io / ghcr.io / 裸 redis
grep -n 'image:' manifests/install-harbor.yaml | sort -u

# 创建命名空间并安装（CRD 体积大，必须 --server-side）
kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts -f manifests/install-harbor.yaml

随后给所有工作负载打上「节点固定 + 镜像拉取凭据 + 资源限额」的补丁。把下面这段存成 patch-argocd.sh：

#!/usr/bin/env bash
set -euo pipefail
NS=argocd
NODE=k8s-node3          # 内存余量最大的 worker
SECRET=harbor-secret    # 与 ruoyi 命名空间同源，在 argocd 命名空间里重建一份

# 先在 argocd 命名空间创建拉取凭据（从 ruoyi 命名空间复制，避免明文再写一遍）
kubectl get secret harbor-secret -n ruoyi -o yaml \
  | sed -e 's/namespace: ruoyi/namespace: argocd/' \
        -e '/resourceVersion:/d' -e '/uid:/d' -e '/creationTimestamp:/d' \
        -e '/kubectl.kubernetes.io\/last-applied-configuration/d' \
  | kubectl apply -f -

# 统一补丁：节点选择 + 拉取凭据
patch_one() {
  local kind=$1 name=$2
  kubectl -n $NS patch $kind/$name --type=strategic -p "{
    \"spec\":{\"template\":{\"spec\":{
      \"nodeSelector\":{\"kubernetes.io/hostname\":\"$NODE\"},
      \"imagePullSecrets\":[{\"name\":\"$SECRET\"}]
    }}}}" || echo "!! $kind/$name 打补丁失败"
}

patch_one statefulset argocd-application-controller
for d in argocd-repo-server argocd-server argocd-redis \
         argocd-applicationset-controller argocd-notifications-controller argocd-dex-server; do
  patch_one deployment $d
done

# 资源限额（贴近 §3.1 的预算）
kubectl -n $NS set resources statefulset/argocd-application-controller \
  --requests=cpu=200m,memory=384Mi --limits=cpu=1000m,memory=768Mi --containers='*'
kubectl -n $NS set resources deployment/argocd-repo-server \
  --requests=cpu=100m,memory=192Mi --limits=cpu=500m,memory=512Mi --containers='*'
kubectl -n $NS set resources deployment/argocd-server \
  --requests=cpu=50m,memory=128Mi --limits=cpu=300m,memory=256Mi --containers='*'
kubectl -n $NS set resources deployment/argocd-redis \
  --requests=cpu=30m,memory=64Mi --limits=cpu=200m,memory=128Mi --containers='*'
kubectl -n $NS set resources deployment/argocd-applicationset-controller \
  --requests=cpu=30m,memory=64Mi --limits=cpu=200m,memory=128Mi --containers='*'
kubectl -n $NS set resources deployment/argocd-notifications-controller \
  --requests=cpu=20m,memory=64Mi --limits=cpu=100m,memory=128Mi --containers='*'

bash patch-argocd.sh

# 等待就绪
kubectl -n argocd rollout status statefulset/argocd-application-controller --timeout=300s
kubectl -n argocd rollout status deployment/argocd-server --timeout=300s
kubectl -n argocd get pods -o wide

预期 7 个 Pod（server / repo-server / application-controller / redis / applicationset-controller / notifications-controller / dex-server）全部 Running，且都落在 k8s-node3 上。

kubectl -n argocd scale deployment/argocd-dex-server --replicas=0
kubectl -n argocd patch cm argocd-cm --type=merge -p '{"data":{"dex.config":""}}'

4.6 暴露 Web UI

集群已有 nginx IngressClass（NodePort 30080/30443），复用它是成本最低的做法。为了走纯 HTTP 便于起步，先把 Argo CD 自身的 TLS 关掉（由 Nginx 侧终结或直接明文内网访问）：

# 让 argocd-server 以 HTTP 提供服务（Ingress 后端用 HTTP）
kubectl -n argocd patch cm argocd-cmd-params-cm --type=merge \
  -p '{"data":{"server.insecure":"true"}}'
kubectl -n argocd rollout restart deployment/argocd-server
kubectl -n argocd rollout status  deployment/argocd-server

# 顺带把资源跟踪方式改成注解，避免 Argo CD 往你现有的资源上塞 label
kubectl -n argocd patch cm argocd-cm --type=merge \
  -p '{"data":{"application.resourceTrackingMethod":"annotation"}}'

# 存为 /root/argocd/manifests/argocd-server-ingress.yaml
cat <<'EOF' | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server-ingress
  namespace: argocd
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTP"   # 已设 server.insecure=true
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
spec:
  ingressClassName: nginx
  rules:
  - host: argocd.wanfeng.com          # 参考你现有的 jenkins.wanfeng.com 命名习惯
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 80
EOF

首次登录后立刻改掉初始密码：

argocd account update-password            # 或 kubectl -n argocd delete secret argocd-initial-admin-secret

4.7 安装验收清单

05阶段二：构建 GitOps 清单仓库

5.1 核心原则：第一版清单必须从“活着的集群”导出

5.2 导出并清洗清单

mkdir -p /root/argocd/gitops-bootstrap && cd /root/argocd/gitops-bootstrap

# 导出 ruoyi 命名空间的应用类资源（含 Deployment / Service / Ingress / ConfigMap）
kubectl get deploy,svc,ingress,cm -n ruoyi -o yaml > ruoyi-live-raw.yaml

# 检查：确认 gateway 的 volumeMounts 在导出的内容里（这是关键校验）
grep -n -A3 'volumeMounts' ruoyi-live-raw.yaml | head -20
grep -n 'ruoyi-gateway-config' ruoyi-live-raw.yaml

导出结果里会带一批必须剥掉的运行时字段，否则每次同步都会显示漂移。用下面这个清洗脚本处理（kubectl neat 或手工 jq 都可以，这里给纯 jq 版本，不引入额外插件）：

# 存为 clean.py，在 bootstrap 目录执行
cat > clean.py <<'PYEOF'
import subprocess, yaml, sys, re

DROP_META = ["creationTimestamp","resourceVersion","uid","generation",
             "selfLink","managedFields","annotations"]
KEEP_ANNOT = {"nginx.ingress.kubernetes.io/proxy-body-size",
              "nginx.ingress.kubernetes.io/proxy-read-timeout",
              "nginx.ingress.kubernetes.io/backend-protocol"}

docs = list(yaml.safe_load_all(open(sys.argv[1], encoding="utf-8")))
out = []
for d in docs:
    if not d or d.get("kind") == "List":
        for it in (d or {}).get("items", []): out.append(it)
        continue
    out.append(d)

def scrub(obj):
    if isinstance(obj, dict):
        for k in list(obj.keys()):
            if k in ("creationTimestamp","resourceVersion","uid","generation",
                     "selfLink","managedFields"):
                obj.pop(k, None)
            elif k == "annotations":
                a = obj.pop("annotations") or {}
                keep = {kk: vv for kk, vv in a.items()
                        if kk in KEEP_ANNOT or not kk.startswith(("kubectl.kubernetes.io",
                                                                  "deployment.kubernetes.io",
                                                                  "argocd.argoproj.io"))}
                if keep: obj["annotations"] = keep
            else:
                scrub(obj[k])
    elif isinstance(obj, list):
        for i in obj: scrub(i)
    return obj

res = [scrub(d) for d in out]
print(yaml.safe_dump_all(res, allow_unicode=True, sort_keys=False, default_flow_style=False))
PYEOF

python3 clean.py ruoyi-live-raw.yaml > ruoyi-live-clean.yaml
grep -n 'ruoyi-gateway-config' ruoyi-live-clean.yaml   # 仍然要在
grep -c 'last-applied-configuration' ruoyi-live-clean.yaml   # 应为 0

5.3 仓库目录结构

新建一个独立仓库，例如 https://gitee.com/pang_le/ruoyi-gitops.git。结构如下（按服务拆分，便于 Argo CD 用不同 Application 独立同步、独立回滚）：

ruoyi-gitops/
├── README.md
├── argocd/                         # Argo CD 自身资源（AppProject + Application）
│   ├── project-ruoyi.yaml
│   ├── app-ruoyi-gateway.yaml
│   ├── app-ruoyi-auth.yaml
│   ├── app-ruoyi-modules-system.yaml
│   ├── app-ruoyi-modules-gen.yaml
│   ├── app-ruoyi-modules-job.yaml
│   ├── app-ruoyi-modules-file.yaml
│   ├── app-ruoyi-visual-monitor.yaml
│   └── app-ruoyi-ingress.yaml
└── environments/
    └── prod/
        ├── kustomization.yaml
        ├── namespace.yaml          # 只在首次创建时用，之后 CreateNamespace=false
        ├── ingress.yaml
        ├── config/
        │   └── ruoyi-gateway-config.yaml
        └── services/
            ├── gateway/
            │   ├── kustomization.yaml
            │   ├── deployment.yaml
            │   └── service.yaml
            ├── auth/…
            ├── modules-system/…
            ├── modules-gen/…
            ├── modules-job/…
            ├── modules-file/…
            └── visual-monitor/…

每个服务的 kustomization.yaml 长这样，Jenkins 后续只改 newTag 这一行：

# environments/prod/services/gateway/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: ruoyi
resources:
  - deployment.yaml
  - service.yaml
images:
  - name: 106.75.29.47:10086/ruoyi-cloud/ruoyi-gateway
    newTag: prod-k8s-a3e752d          # ← Jenkins 每次只改这一行

deployment.yaml 里镜像就写“不含 tag”的地址，由 Kustomize 注入：

    spec:
      containers:
        - name: ruoyi-gateway
          image: 106.75.29.47:10086/ruoyi-cloud/ruoyi-gateway
          imagePullPolicy: IfNotPresent        # 原来 Always，改成 IfNotPresent 更省拉取
          volumeMounts:                        # ← 从线上导出的，务必保留
            - name: gateway-config
              mountPath: /home/ruoyi/application.yml
              subPath: application.yml
      volumes:
        - name: gateway-config
          configMap:
            name: ruoyi-gateway-config

5.4 推送仓库

cd /root/argocd/gitops-bootstrap
# 按 §5.3 的目录把 ruoyi-live-clean.yaml 拆分到各服务目录（拆分是一次性工作）
git init -b main
git add -A && git commit -m "chore: bootstrap GitOps manifests from live cluster (2026-09-23)"
git remote add origin https://gitee.com/pang_le/ruoyi-gitops.git
git push -u origin main

06阶段三：Argo CD 应用与项目配置

6.1 用 AppProject 划边界

AppProject 把「这个项目能用哪些 Git 仓库、能往哪些命名空间、能创建哪些资源类型」约束住。这是多团队环境下最重要的安全边界：

# argocd/project-ruoyi.yaml
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: ruoyi
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  description: 若依微服务（RuoYi-Cloud）生产环境
  sourceRepos:
    - https://gitee.com/pang_le/ruoyi-gitops.git
  destinations:
    - namespace: ruoyi
      server: https://kubernetes.default.svc
  # 只允许部署这些类型，防止误建 ClusterRole 之类的高危资源
  clusterResourceWhitelist: []
  namespaceResourceWhitelist:
    - group: apps
      kind: Deployment
    - group: ""
      kind: Service
    - group: ""
      kind: ConfigMap
    - group: networking.k8s.io
      kind: Ingress
  orphanedResources:
    warn: true

kubectl apply -f argocd/project-ruoyi.yaml
argocd proj get ruoyi

6.2 每个服务一个 Application

# argocd/app-ruoyi-gateway.yaml（其余 6 个服务同构，只改名称与路径）
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: ruoyi-gateway
  namespace: argocd
  annotations:
    argocd.argoproj.io/sync-wave: "10"        # 网关后于后端服务同步
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: ruoyi
  source:
    repoURL: https://gitee.com/pang_le/ruoyi-gitops.git
    targetRevision: main
    path: environments/prod/services/gateway
  destination:
    server: https://kubernetes.default.svc
    namespace: ruoyi
  syncPolicy:
    automated:
      prune: true          # Git 里删掉的资源，集群里也删掉
      selfHeal: true       # 有人手动改集群，自动纠偏回来
      allowEmpty: false
    syncOptions:
      - CreateNamespace=false      # ruoyi 已存在
      - ApplyOutOfSyncOnly=true    # 只 apply 有差异的资源，减少 API 压力
      - PruneLast=true
      - ServerSideApply=true
    retry:
      limit: 5
      backoff:
        duration: 10s
        factor: 2
        maxDuration: 3m
  revisionHistoryLimit: 20         # 保留 20 个历史版本，方便回滚

6.3 关于同步顺序的一个细节

若依的服务之间存在依赖（gateway 依赖后端服务注册到 Nacos，auth 依赖 system）。Argo CD 的 sync-wave 建议：

• 0：ConfigMap（ruoyi-gateway-config）
• 5：auth、modules-system、modules-gen、modules-job、modules-file、visual-monitor
• 10：gateway
• 20：Ingress

注意每个服务的 readinessProbe 是保证顺序的必要前提——目前 Deployment 没有配置探针（勘察确认 readinessProbe/livenessProbe 均为空）。没有探针时 Pod 一启动就被视为 Ready，滚动更新会出现“新 Pod 还没起来就被切断流量”的窗口。强烈建议这次一起补上，否则 Argo CD 的同步状态无法反映真实可用性。

          readinessProbe:
            tcpSocket: { port: 8080 }      # 或 /actuator/health
            initialDelaySeconds: 40
            periodSeconds: 10
            failureThreshold: 3
          livenessProbe:
            tcpSocket: { port: 8080 }
            initialDelaySeconds: 90
            periodSeconds: 20

6.4 让 Argo CD 感知到 Git 变更

Argo CD 默认每 3 分钟轮询一次 Git。要“提交即同步”，两种方式：

读取 webhook 的 secret 并配置（可选）：

kubectl -n argocd get secret argocd-secret -o jsonpath='{.data.webhook\.gitee\.secret}' | base64 -d; echo
# Gitee 侧：仓库 → 管理 → WebHooks → URL 填
#   http://<argocd入口>/api/webhook
# 密钥：用 argocd-cm 里 webhook.gitee.secret 配置的那个值

07阶段四：Jenkins 流水线改造

7.1 版本号规则：换成 Git 短 SHA

// 在 pipeline 顶层 environment 里
VERSION = "${BRANCH_NAME}-${GIT_COMMIT.take(7)}"     // 例：prod-k8s-a3e752d

7.2 改造后的 Jenkinsfile（以 gateway 为例）

pipeline {
    agent any
    tools {
        maven 'Maven-3.8.9'
        jdk   'JDK-17'
    }
    environment {
        APP_NAME       = 'ruoyi-gateway'
        NAMESPACE      = 'ruoyi'
        HARBOR         = '106.75.29.47:10086'
        IMAGE_REPO     = "${HARBOR}/ruoyi-cloud/${APP_NAME}"
        HARBOR_CRED_ID = 'harbor-credentials'
        GITOPS_REPO    = 'https://gitee.com/pang_le/ruoyi-gitops.git'
        GITOPS_DIR     = 'environments/prod/services/gateway'
        GITOPS_CRED_ID = 'gitee-gitops-credentials'    // 新增凭据，见 §7.3
        ARGOCD_APP     = 'ruoyi-gateway'
        ARGOCD_SERVER  = 'argocd-server.argocd.svc.cluster.local:80'
        VERSION        = "${env.BRANCH_NAME}-${env.GIT_COMMIT.take(7)}"
        MAVEN_OPTS     = '-Dmaven.compiler.source=17 -Dmaven.compiler.target=17 -Dproject.build.sourceEncoding=UTF-8'
    }
    options { disableConcurrentBuilds(); timestamps() }

    stages {
        stage('1. 编译打包 (CI)') {
            steps { sh 'mvn clean package -Dmaven.test.skip=true' }
        }

        stage('2. 构建并推送镜像 (CI)') {
            steps {
                withCredentials([usernamePassword(credentialsId: env.HARBOR_CRED_ID,
                                                  usernameVariable: 'HU', passwordVariable: 'HP')]) {
                    sh """
                        echo "\$HP" | docker login ${HARBOR} -u "\$HU" --password-stdin
                        docker build --build-arg JAR_FILE=target/${APP_NAME}.jar \
                                     -t ${IMAGE_REPO}:${VERSION} .
                        docker push ${IMAGE_REPO}:${VERSION}
                        docker rmi  ${IMAGE_REPO}:${VERSION} || true
                    """
                }
            }
        }

        stage('3. 更新 GitOps 仓库镜像版本 (CD 触发点)') {
            steps {
                withCredentials([usernamePassword(credentialsId: env.GITOPS_CRED_ID,
                                                  usernameVariable: 'GU', passwordVariable: 'GP')]) {
                    sh """
                        rm -rf .gitops-tmp
                        git clone -q \
                          https://\${GU}:\${GP}@gitee.com/pang_le/ruoyi-gitops.git .gitops-tmp
                        cd .gitops-tmp
                        git config user.email "jenkins@wanfeng.com"
                        git config user.name  "Jenkins CI"

                        cd ${GITOPS_DIR}
                        # 只改 kustomization.yaml 里的 newTag 一行，幂等且无副作用
                        sed -i -E "s#(newTag:).*#\\1 ${VERSION}#" kustomization.yaml
                        cd ../..

                        git add -A
                        git diff --cached --quiet && echo "镜像版本未变化，跳过提交" || {
                          git commit -m "ci(${APP_NAME}): bump image to ${VERSION} [skip ci]"
                          git push origin HEAD:main
                        }
                    """
                }
            }
        }

        stage('4. 等待 Argo CD 完成同步 (CD)') {
            steps {
                withCredentials([string(credentialsId: 'argocd-api-token', variable: 'ARGOCD_TOKEN')]) {
                    sh """
                        argocd app sync  ${ARGOCD_APP} --grpc-web --insecure \
                          --server ${ARGOCD_SERVER} --auth-token \$ARGOCD_TOKEN
                        argocd app wait  ${ARGOCD_APP} --grpc-web --insecure \
                          --server ${ARGOCD_SERVER} --auth-token \$ARGOCD_TOKEN \
                          --health --timeout 300
                    """
                }
            }
        }
    }

    post {
        success { echo "✅ 构建并发布成功：${IMAGE_REPO}:${VERSION}" }
        failure {
            echo "❌ 构建或发布失败，镜像 ${IMAGE_REPO}:${VERSION}"
            // 可选：自动回滚 —— 把 GitOps 仓库回退到上一个提交
            // sh "cd .gitops-tmp && git revert --no-edit HEAD && git push origin HEAD:main"
        }
    }
}

7.3 需要新增的两样东西

Argo CD Token 的生成方式（在装好 CLI 之后）：

# 建议为 CI 单独建一个账号，而不是用 admin
argocd account create ci-bot
argocd account generate-token --account ci-bot --expires-in 8760h

同时给它收权限（避免 CI 用超管令牌）：

kubectl -n argocd patch cm argocd-rbac-cm --type=merge -p '{"data":{
  "policy.csv":"p, role:ci, applications, sync, ruoyi/*, allow\np, role:ci, applications, get, ruoyi/*, allow\ng, ci-bot, role:ci\n"
}}'

7.4 各服务的分支与 Job 命名建议

你现在的模式是「一个服务一个 Multibranch Job、监听 prod* 分支」。这个模式本身没问题，改造时可以保留，只需注意：

• 新增的 GitOps 仓库是第 11 个仓库，它不需要建 Jenkins Job（它由 Argo CD 消费，不由 Jenkins 构建）。
• ruoyi-dependencies、ruoyi-common 这类只被依赖的父 POM 仓库，可以继续用现有方式（只需 install 到 Nexus / 本地仓库），不产生镜像也就不参与 Argo CD。
• 第一个先改的 Job，建议选 ruoyi-modules-gen 或 ruoyi-visual-monitor——它们在最边上，出错影响面最小。

08阶段五：灰度切换与验收

核心原则：新旧两套机制并存一段时间，逐个服务切换，任何一步都能立刻退回。

8.1 切换顺序

8.2 关键验收动作（可执行的验证脚本）

# A. Argo CD 视角：哪些应用不同步 / 不健康
argocd app list -o wide
argocd app get ruoyi-gateway
argocd app diff ruoyi-gateway          # 看具体差异在哪

# B. 集群视角：期望副本 vs 实际副本
kubectl -n ruoyi get deploy -o custom-columns=\
'NAME:.metadata.name,DESIRED:.spec.replicas,READY:.status.readyReplicas,IMAGE:.spec.template.spec.containers[0].image'

# C. 端到端可用性（沿用你已有的测试方式，补一条命令版）
curl -s -o /dev/null -w 'gateway  HTTP %{http_code}\n'  http://100.78.249.106:31080/
curl -s -o /dev/null -w 'ingress  HTTP %{http_code}\n' -H 'Host: 106.75.30.92' http://100.78.249.106:30080/

# D. 漂移检测演练（验证 selfHeal 确实在工作）
kubectl -n ruoyi label deploy ruoyi-gateway-deploy chaos-test=yes
sleep 60
kubectl -n ruoyi get deploy ruoyi-gateway-deploy -o jsonpath='{.metadata.labels}'; echo
# 期望：chaos-test 标签被 Argo CD 自动清除

# E. 回滚演练
argocd app history ruoyi-gateway
argocd app rollback ruoyi-gateway <REVISION_ID>

8.3 验收通过标准

• 所有 Application 状态为 Synced 且 Healthy。
• CI 触发一次代码变更后，全链路自动完成：无需人工 kubectl 介入。
• 故意手动改动集群 → 60 秒内被 selfHeal 纠正回来。
• 回滚演练成功：能在 2 分钟内把某个服务回到上一个版本。
• Jenkins 凭据中不再需要集群 kubeconfig。

09回滚、故障处理与运维

9.1 三级回滚手段

9.2 常见故障速查

9.3 日常运维要点

• 备份：Argo CD 的配置都在 argocd 命名空间，定期 kubectl -n argocd get cm,secret -o yaml > argocd-backup-$(date +%F).yaml。Application/AppProject 本身也建议纳入 Git（argocd/ 目录即可）。
• 升级：Argo CD 自身也用 GitOps 管起来是终态，但起步阶段手工升级更直观：替换 install.yaml 的版本号 → 重新 apply → 观察。升级前务必查当次 release note 的 breaking change。
• 监控：Argo CD 自带 Prometheus 指标（argocd-metrics / argocd-server-metrics Service 已存在）。可以接到你已有的 ELK 或后续上 Prometheus。核心告警指标：argocd_app_info{sync_status!="Synced"}、argocd_app_info{health_status!="Healthy"}。
• 清理：Harbor 上给 ruoyi-cloud 项目配保留策略（比如保留最近 30 个 tag），否则 SHA tag 会快速堆积。当前 / 已用 58%（57G/99G）。

10风险清单与注意事项

10.1 关于 imagePullPolicy

现在的 Deployment 是 Always。换成不可变 SHA tag 后，Always 只会带来额外的一次 registry 查询而不会有正确性收益，建议改 IfNotPresent，能明显减少 Harbor 压力和 Pod 启动时间。

10.2 关于 NodePort 泛滥

7 个 Service 全是 NodePort，其中 gateway 同时被 NodePort 31080 和 Ingress 暴露。这属于历史遗留。本次改造不建议顺手改（会变更访问入口），但可以在 GitOps 稳定后单独排期收敛为 ClusterIP + Ingress。

10.3 关于多个并发构建

Jenkins numExecutors=2，而每个 Job 都设了 disableConcurrentBuilds()。7 个服务同时提交时会有排队。改造后每条流水线多了一个「等 Argo CD 同步」的阶段（最长 5 分钟），需要评估构建队列是否会变长。如果出现堆积，可以把 --timeout 调小到 180s，或把「等待同步」改成只提交不等待（由 Argo CD 轮询/webhook 兜底）。

10.4 关于 ruoyi-ui 的三种后续路径

1. 保持现状（本轮）：宿主机 Nginx 托管，不进集群，不纳入 GitOps。
2. 容器化进集群：用现有 Dockerfile 构建 ruoyi-ui 镜像，Deployment + ConfigMap（ruoyi-ui-nginx-config 仓库里已有）+ Ingress，然后交给 Argo CD。
3. 保留静态目录但用 Argo CD 管清单：把 Nginx 配置纳入 GitOps（这块其实更适合 Ansible，不推荐）。

10.5 可选增强：用已有的 Casdoor 做 SSO

你机器上已经跑着 casbin/casdoor:latest，它本身就是 OIDC Provider。这样可以不装 Dex，直接在 argocd-cm 里配 oidc.config，用 Casdoor 做统一登录，和 /opt/maxkey、/opt/CASdoor 的现有 IAM 体系统一。属于本轮之后的增量优化。

10.6 可选增强：Argo CD Image Updater

如果你希望「CI 只管推镜像，GitOps 仓库的 tag 由 Argo CD 自动改写」，可以引入 Image Updater。但它需要写回 Git，并且要额外访问 Harbor 的 registry API。本轮不推荐——由 Jenkins 写 tag 更直观、可控性更强，也更符合「CI 管构建、CD 管部署」这个你想学的心智模型。

11附录：命令速查

11.1 安装链路（按顺序执行）

# 1 准备清单与 CLI
mkdir -p /root/argocd/manifests && cd /root/argocd
curl -fL --retry 3 -o manifests/install-v2.14.21.yaml \
  https://gh-proxy.com/https://raw.githubusercontent.com/argoproj/argo-cd/v2.14.21/manifests/install.yaml
curl -fL --retry 3 -o /usr/local/bin/argocd \
  https://files.m.daocloud.io/github.com/argoproj/argo-cd/releases/download/v2.14.21/argocd-linux-amd64
chmod +x /usr/local/bin/argocd

# 2 镜像入库（Harbor 项目 infra）
HARBOR=106.75.29.47:10086
docker login ${HARBOR} -u admin -p '@Pl000000'
docker pull quay.m.daocloud.io/argoproj/argocd:v2.14.21 && \
  docker tag quay.m.daocloud.io/argoproj/argocd:v2.14.21 ${HARBOR}/infra/argocd:v2.14.21 && \
  docker push ${HARBOR}/infra/argocd:v2.14.21
docker pull ghcr.m.daocloud.io/dexidp/dex:v2.41.1 && \
  docker tag ghcr.m.daocloud.io/dexidp/dex:v2.41.1 ${HARBOR}/infra/dex:v2.41.1 && \
  docker push ${HARBOR}/infra/dex:v2.41.1
docker pull m.daocloud.io/docker.io/library/redis:7.2.11-alpine && \
  docker tag m.daocloud.io/docker.io/library/redis:7.2.11-alpine ${HARBOR}/infra/redis:7.2.11-alpine && \
  docker push ${HARBOR}/infra/redis:7.2.11-alpine

# 3 改镜像并安装
sed -i -e "s#quay.io/argoproj/argocd:#${HARBOR}/infra/argocd:#g" \
       -e "s#ghcr.io/dexidp/dex:#${HARBOR}/infra/dex:#g" \
       -e "s#image: redis:7.2.11-alpine#image: ${HARBOR}/infra/redis:7.2.11-alpine#g" \
       manifests/install-v2.14.21.yaml
kubectl create namespace argocd
kubectl apply -n argocd --server-side --force-conflicts -f manifests/install-v2.14.21.yaml

# 4 打补丁（节点/凭据/资源/HTTP）
bash patch-argocd.sh
kubectl -n argocd patch cm argocd-cmd-params-cm --type=merge -p '{"data":{"server.insecure":"true"}}'
kubectl -n argocd patch cm argocd-cm --type=merge -p '{"data":{"application.resourceTrackingMethod":"annotation"}}'
kubectl -n argocd rollout restart deployment/argocd-server

# 5 登录
kubectl -n argocd port-forward svc/argocd-server 8080:80 --address 0.0.0.0 &
argocd login 127.0.0.1:8080 --insecure --username admin \
  --password "$(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d)"

11.2 常用运维命令

argocd app list -o wide                          # 所有应用状态一览
argocd app get <app>                              # 单应用详情（含资源树）
argocd app diff <app>                             # 差异明细
argocd app sync <app> --prune                    # 手动同步
argocd app history <app>                          # 历史版本
argocd app rollback <app> <rev>                   # 回滚
argocd app set <app> --sync-policy none           # 关自动同步（应急处置前必做）
argocd app set <app> --sync-policy automated --self-heal --auto-prune

kubectl -n argocd logs -f statefulset/argocd-application-controller   # 控制器日志
kubectl -n argocd logs -f deploy/argocd-repo-server                   # 渲染/拉取 Git 的问题看这里
kubectl -n argocd get events --sort-by=.lastTimestamp | tail -30

11.3 本次实测过的镜像 / 下载地址汇总