CI/CD: K8S + Tekton + ArgoCD 深入浅出完全指南
🎯 一句话定位：这是一份让你从"不懂 CI/CD"到"能独立排查问题"的实战指南。
秒懂定位（30秒版）
这套系统解决什么问题：
没有 CI/CD：
改代码 → 手动打包 → 手动上传 → 手动部署 → 祈祷别出错 🙏
有了 CI/CD：
改代码 → git push → 喝杯咖啡 ☕ → 部署完成 ✅一句话精华：
Tekton 负责"造房子"（构建镜像）
ArgoCD 负责"搬家"（部署到 K8s）
Git 是"设计图纸"（唯一真相来源）适合谁看 ：需要使用这套 CI/CD 系统的开发者
看完能做什么：触发构建、查看日志、排查问题、回滚部署
一、架构总览（先看全貌）
整体流程图
┌─────────────────────────────────────────────────────────────────────────┐
│ CI/CD 就像一条自动化流水线 🏭 │
│ │
│ 👨💻 开发者 │
│ │ │
│ │ git push（把代码推上去） │
│ ▼ │
│ 📦 Git 仓库 │
│ │ │
│ │ Webhook（自动通知） │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 🔧 Tekton（CI 阶段）------ "建筑工人" │ │
│ │ │ │
│ │ 收到通知 → 拉代码 → 编译 → 打包成镜像 → 推到 Harbor │ │
│ │ │ │
│ │ 就像：收到图纸 → 买材料 → 施工 → 建好房子 → 交付 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ 镜像推送完成 │
│ ▼ │
│ 🏪 Harbor（镜像仓库）------ "仓库" │
│ │ │
│ │ ArgoCD 监听 Git 仓库的 k8s 配置 │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 🚀 ArgoCD（CD 阶段）------ "搬家公司" │ │
│ │ │ │
│ │ 监听 Git → 发现配置变化 → 自动部署到 K8s │ │
│ │ │ │
│ │ 就像：看设计图 → 发现要换家具 → 自动搬新家具进去 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ✅ 服务上线，用户可以访问了！ │
└─────────────────────────────────────────────────────────────────────────┘核心组件速查表
| 组件 | 角色 | 生活比喻 | 访问地址 |
|---|---|---|---|
| Git | 代码仓库 | 设计图纸存放处 | gitee.com/<YOUR_USERNAME>/<YOUR_REPO> |
| Tekton | CI 引擎 | 建筑工人 | - |
| Harbor | 镜像仓库 | 建材仓库 | http://<MASTER_IP>:<HARBOR_PORT> |
| ArgoCD | CD 引擎 | 搬家公司 | http://<MASTER_IP>:<ARGOCD_PORT> |
| K8s | 运行环境 | 房子（服务运行的地方） | - |
二、环境信息（记住这些地址）
集群节点
| 节点 | IP | 角色 | 记忆口诀 |
|---|---|---|---|
| k8s-master | <MASTER_IP> | 控制节点 | "master 是老大" |
| k8s-worker1 | <WORKER1_IP> | 工作节点 | "worker1 干活" |
| k8s-worker2 | <WORKER2_IP> | 工作节点 | "worker2 也干活" |
服务访问地址（建议收藏）
🏪 Harbor（镜像仓库）
地址：http://<MASTER_IP>:<HARBOR_PORT>
账号：admin
密码：<HARBOR_PASSWORD>
用途：查看构建好的镜像
🚀 ArgoCD（部署管理）
地址：http://<MASTER_IP>:<ARGOCD_PORT>
账号：admin
密码：<ARGOCD_PASSWORD>
用途：查看部署状态、手动同步
🔔 Tekton Webhook（CI 触发器）
地址：http://<WORKER_IP>:<WEBHOOK_PORT>
用途：Git 推送时自动触发构建
🌐 Web API（服务入口）
地址：http://<MASTER_IP>:<WEB_PORT>
用途：测试服务是否正常
示例：curl http://<MASTER_IP>:<WEB_PORT>/api/user/1三、日常操作指南（最常用的操作）
🚀 操作1：触发一次构建
场景：你改了代码，想部署到测试环境
方式1：推送代码（推荐，全自动）
bash
# 在你的代码目录
cd /path/to/your/repo
# 正常的 Git 操作
git add .
git commit -m "feat: 你的修改说明"
git push
# 然后...就没有然后了！
# Tekton 会自动构建，ArgoCD 会自动部署
# 你可以去喝杯咖啡 ☕方式2：手动触发（调试用）
bash
# 如果 Webhook 没触发，可以手动创建 PipelineRun
ssh root@<MASTER_IP> 'kubectl create -f /path/to/pipelinerun-v2.yaml'👀 操作2：查看构建状态
场景：想知道构建到哪一步了
bash
# 查看最近的 PipelineRun
ssh root@<MASTER_IP> 'kubectl get pipelineruns -n tekton-pipelines --sort-by=.metadata.creationTimestamp | tail -5'
# 输出示例：
# NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME
# service-test-auto-abc123 True Succeeded 10m 5m
# service-test-auto-def456 Unknown Running 2m <none>
# 状态说明：
# True + Succeeded = ✅ 构建成功
# Unknown + Running = 🔄 正在构建
# False + Failed = ❌ 构建失败查看详细进度：
bash
# 查看某个 PipelineRun 的所有 TaskRun
ssh root@<MASTER_IP> 'kubectl get taskruns -n tekton-pipelines | grep service-test-auto-abc123'
# 输出示例：
# service-test-auto-abc123-build-user True Succeeded 10m
# service-test-auto-abc123-build-product True Succeeded 10m
# service-test-auto-abc123-build-trade True Succeeded 8m
# service-test-auto-abc123-build-web True Succeeded 9m📋 操作3：查看构建日志
场景：构建失败了，想看看哪里出错
bash
# 第一步：找到失败的 TaskRun
ssh root@<MASTER_IP> 'kubectl get taskruns -n tekton-pipelines | grep False'
# 第二步：查看日志
# 格式：kubectl logs <pod-name> -n tekton-pipelines -c step-<step-name>
# 查看克隆代码的日志
ssh root@<MASTER_IP> 'kubectl logs <pod-name> -n tekton-pipelines -c step-clone'
# 查看构建镜像的日志
ssh root@<MASTER_IP> 'kubectl logs <pod-name> -n tekton-pipelines -c step-build-and-push'🔄 操作4：查看部署状态
场景：想知道服务有没有部署成功
bash
# 查看 ArgoCD Application 状态
ssh root@<MASTER_IP> 'kubectl get applications -n argocd'
# 输出示例：
# NAME SYNC STATUS HEALTH STATUS
# service-test Synced Healthy
# 状态说明：
# Synced + Healthy = ✅ 部署成功，服务正常
# Synced + Progressing = 🔄 正在部署
# OutOfSync = ⚠️ Git 和集群不一致，需要同步
# Degraded = ❌ 服务有问题
# 查看具体的 Pod 状态
ssh root@<MASTER_IP> 'kubectl get pods -n service-test'🔙 操作5：回滚部署
场景：新版本有 bug，需要回滚
方式1：Git revert（推荐）
bash
cd /path/to/your/repo
# 回滚到上一个版本
git revert HEAD
git push
# ArgoCD 会自动同步回滚后的配置方式2：K8s rollout（临时）
bash
# 回滚某个服务
ssh root@<MASTER_IP> 'kubectl rollout undo deployment/user-service -n service-test'
# 注意：如果 ArgoCD 开启了 selfHeal，会自动改回 Git 配置
# 所以这只是临时方案，最终还是要改 Git🔧 操作6：手动触发 ArgoCD 同步
场景：不想等 3 分钟轮询，想立即同步
bash
ssh root@<MASTER_IP> 'kubectl annotate application service-test -n argocd argocd.argoproj.io/refresh=hard --overwrite'或者通过 UI：
- 访问 http://<MASTER_IP>:<ARGOCD_PORT>
- 登录（admin/<ARGOCD_PASSWORD>）
- 点击 service-test 应用
- 点击 "Sync" 按钮
四、故障排查指南（遇到问题看这里）
🔍 排查思路（像侦探一样）
问题发生了！别慌，按这个顺序排查：
1️⃣ 构建有没有触发？
└── 看 PipelineRun 有没有创建
2️⃣ 构建成功了吗？
└── 看 TaskRun 状态
3️⃣ 镜像推送了吗？
└── 去 Harbor 看看
4️⃣ ArgoCD 同步了吗？
└── 看 Application 状态
5️⃣ Pod 启动了吗？
└── 看 Pod 状态和日志问题1：推送代码后没有触发构建
症状：git push 了，但是没有新的 PipelineRun
排查步骤：
bash
# 1. 检查 EventListener 是否在运行
ssh root@<MASTER_IP> 'kubectl get pods -n tekton-pipelines | grep listener'
# 应该看到 el-gitee-listener-xxx Running
# 2. 检查 EventListener 日志
ssh root@<MASTER_IP> 'kubectl logs -n tekton-pipelines -l eventlistener=gitee-listener --tail=20'
# 3. 检查 Git Webhook 配置
# 访问你的 Git 仓库 Webhook 设置页面
# 确认 URL 是 http://<WORKER_IP>:<WEBHOOK_PORT>常见原因：
| 原因 | 解决方案 |
|---|---|
| EventListener Pod 挂了 | 重启 Pod |
| Webhook URL 配置错误 | 修改为正确的 URL |
| 网络不通 | 检查防火墙，确保端口开放 |
问题2：构建失败 - TaskRun Failed
症状：PipelineRun 显示 Failed
排查步骤：
bash
# 1. 找到失败的 TaskRun
ssh root@<MASTER_IP> 'kubectl get taskruns -n tekton-pipelines | grep False'
# 2. 查看失败原因
ssh root@<MASTER_IP> 'kubectl describe taskrun <taskrun-name> -n tekton-pipelines | tail -30'
# 3. 查看具体日志
ssh root@<MASTER_IP> 'kubectl logs <pod-name> -n tekton-pipelines --all-containers'常见原因及解决：
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
ImagePullBackOff |
镜像拉取失败 | 检查 Harbor 是否正常，镜像是否存在 |
TaskRunTimeout |
构建超时 | Go 编译慢，已设置 2h 超时，等待即可 |
error resolving dockerfile |
找不到 Dockerfile | 检查 Dockerfile 路径是否正确 |
502 Bad Gateway |
Harbor 服务异常 | 检查 Harbor Pod 状态 |
问题3：镜像推送失败 - 401 Unauthorized
症状 ：构建日志显示 401 Unauthorized
原因：Harbor 认证失败
解决：
bash
# 检查 Harbor Secret 是否存在
ssh root@<MASTER_IP> 'kubectl get secret harbor-kaniko-secret -n tekton-pipelines'
# 如果不存在，重新创建
# 参考 02_tekton/pipelines/harbor-secret-v2.yaml问题4：ArgoCD 显示 OutOfSync
症状：Application 状态是 OutOfSync
原因：Git 仓库配置和集群状态不一致
解决：
bash
# 手动触发同步
ssh root@<MASTER_IP> 'kubectl annotate application service-test -n argocd argocd.argoproj.io/refresh=hard --overwrite'问题5：Pod 一直 CrashLoopBackOff
症状：Pod 不断重启
排查步骤：
bash
# 1. 查看 Pod 日志
ssh root@<MASTER_IP> 'kubectl logs <pod-name> -n service-test --tail=50'
# 2. 查看 Pod 事件
ssh root@<MASTER_IP> 'kubectl describe pod <pod-name> -n service-test | tail -20'常见原因：
| 原因 | 解决方案 |
|---|---|
| 健康检查失败 | 检查 livenessProbe 配置 |
| 配置错误 | 检查 ConfigMap |
| 依赖服务不可用 | 检查 etcd/数据库连接 |
问题6：服务无法访问
症状：curl http://<MASTER_IP>:<WEB_PORT>/api/user/1 失败
排查步骤：
bash
# 1. 检查 Pod 是否运行
ssh root@<MASTER_IP> 'kubectl get pods -n service-test'
# 2. 检查 Service 是否存在
ssh root@<MASTER_IP> 'kubectl get svc -n service-test'
# 3. 检查 Pod 日志
ssh root@<MASTER_IP> 'kubectl logs -n service-test -l app=web-service --tail=30'五、深入理解（想知道为什么）
CI 部分：Tekton 是怎么工作的？
生活比喻：Tekton 就像一个自动化的建筑工地
┌─────────────────────────────────────────────────────────────────────────┐
│ Tekton 工作原理（建筑工地比喻） │
│ │
│ 📋 Task（任务）= 一道工序 │
│ 比如"砌墙"这道工序，包含： │
│ - Step 1: 准备砖头（git clone） │
│ - Step 2: 砌墙（docker build） │
│ - Step 3: 刷漆（docker push） │
│ │
│ 🏗️ Pipeline（流水线）= 整个建筑项目 │
│ 包含多道工序，可以同时进行： │
│ - 工序1: 建卧室（build-user） │
│ - 工序2: 建客厅（build-product） ← 这些可以同时进行！ │
│ - 工序3: 建厨房（build-trade） │
│ - 工序4: 建卫生间（build-web） │
│ │
│ 🚀 PipelineRun（运行实例）= 今天的施工 │
│ "今天开始建张三家的房子" │
│ 每次 git push 都会创建一个新的 PipelineRun │
└─────────────────────────────────────────────────────────────────────────┘Triggers 三剑客：
Git 推送代码
│
▼
EventListener（门卫）
│ "有人来了！"
▼
TriggerBinding（翻译官）
│ "他说要建 abc123 版本的房子"
▼
TriggerTemplate（包工头）
│ "好的，我来安排施工"
▼
PipelineRun（开始施工）CD 部分：ArgoCD 是怎么工作的？
生活比喻：ArgoCD 就像一个强迫症管家
┌─────────────────────────────────────────────────────────────────────────┐
│ ArgoCD 工作原理（强迫症管家比喻） │
│ │
│ 📖 Git 仓库 = 家居设计图 │
│ "客厅要放红色沙发，卧室要放蓝色床" │
│ │
│ 🏠 K8s 集群 = 实际的房子 │
│ "现在客厅放的是绿色沙发" │
│ │
│ 👨🔧 ArgoCD = 强迫症管家 │
│ 每 3 分钟检查一次： │
│ "设计图说要红色沙发，但现在是绿色的！" │
│ "不行！必须换成红色的！"（自动同步） │
│ │
│ 🔧 selfHeal = 自动纠正 │
│ 有人偷偷把沙发换成黄色的 │
│ 管家发现后："不对！设计图说是红色！换回来！" │
│ │
│ 🗑️ prune = 清理多余 │
│ 设计图上删掉了茶几 │
│ 管家："设计图上没有茶几了，搬走！" │
└─────────────────────────────────────────────────────────────────────────┘CI 和 CD 的分工
┌─────────────────────────────────────────────────────────────────────────┐
│ CI 和 CD 的分工 │
│ │
│ 【Tekton 的职责】CI = Continuous Integration（持续集成） │
│ │
│ 代码 ──────────────────────────────────────▶ 镜像 │
│ │ │
│ ├── 拉取代码 │
│ ├── 编译代码 │
│ ├── 运行测试 │
│ ├── 构建镜像 │
│ └── 推送到 Harbor │
│ │
│ ═══════════════════════════════════════════════════════════════════════│
│ │
│ 【ArgoCD 的职责】CD = Continuous Deployment（持续部署） │
│ │
│ Git 配置 ─────────────────────────────────▶ K8s 集群 │
│ │ │
│ ├── 监听 Git 仓库 │
│ ├── 比较配置差异 │
│ ├── 同步到集群 │
│ └── 监控健康状态 │
│ │
│ 【它们的连接点】 │
│ │
│ Tekton 构建完镜像 → 更新 Git 仓库中的镜像 tag → ArgoCD 检测到变化 │
│ → 自动部署新镜像 │
└─────────────────────────────────────────────────────────────────────────┘六、配置文件说明（想改配置看这里）
目录结构
devops_platform/
├── 02_tekton/
│ ├── pipelines/
│ │ ├── build-service-task-v2.yaml # 🔧 Task：怎么构建一个服务
│ │ ├── pipeline-simple-v2.yaml # 🔗 Pipeline：构建哪些服务
│ │ ├── pipelinerun-v2.yaml # 🚀 手动触发模板
│ │ └── harbor-secret-v2.yaml # 🔐 Harbor 认证
│ └── triggers/
│ ├── trigger-template.yaml # 📋 自动触发时创建什么
│ ├── trigger-binding.yaml # 🔍 从 Webhook 提取什么参数
│ ├── event-listener.yaml # 👂 监听 Webhook
│ └── event-listener-service.yaml # 🌐 暴露给外部访问
│
├── 04_argocd/
│ └── applications/
│ └── service-test-app.yaml # 📦 ArgoCD 应用配置
│
└── k8s/ # K8s 部署配置（ArgoCD 监听这里）
├── configmaps.yaml
├── user/deployment.yaml
├── product/deployment.yaml
├── trade/deployment.yaml
└── web/deployment.yaml关键配置解读
1. build-service-task-v2.yaml（构建任务）
yaml
# 这个文件定义了"怎么构建一个服务"
steps:
- name: clone # 步骤1：拉代码
image: alpine/git
- name: build-and-push # 步骤2：构建并推送
image: kaniko
args:
- --registry-mirror=<HARBOR_ADDRESS> # 🔑 关键：用 Harbor 做镜像代理
- --insecure-pull # 🔑 关键：允许 HTTP 拉取
- --single-snapshot # 🔑 关键：加速构建
timeout: 2h # 🔑 关键：Go 编译慢，给足时间什么时候需要改这个文件？
- 想修改构建参数
- 想添加新的构建步骤（如运行测试）
- 构建超时需要调整
2. pipeline-simple-v2.yaml（流水线）
yaml
# 这个文件定义了"构建哪些服务"
tasks:
- name: build-user # 构建 user-service
params:
- name: dockerfile
value: dockerfiles/Dockerfile.user
- name: build-product # 构建 product-service（并行）
- name: build-trade # 构建 trade-service（并行）
- name: build-web # 构建 web-service（并行）什么时候需要改这个文件？
- 新增了一个微服务
- 想改变构建顺序（串行/并行）
- 想修改某个服务的 Dockerfile 路径
3. service-test-app.yaml（ArgoCD 应用）
yaml
# 这个文件定义了"ArgoCD 监听什么、部署到哪里"
source:
repoURL: https://gitee.com/<YOUR_USERNAME>/<YOUR_REPO>.git
path: k8s # 🔑 关键：监听 k8s 目录
directory:
recurse: true # 🔑 关键：递归扫描子目录
destination:
namespace: service-test # 🔑 关键：部署到哪个 namespace
syncPolicy:
automated:
prune: true # 🔑 关键：删除 Git 中没有的资源
selfHeal: true # 🔑 关键：自动修复手动修改什么时候需要改这个文件？
- 想监听不同的 Git 仓库或分支
- 想部署到不同的 namespace
- 想关闭自动同步（改为手动）
七、命令速查表（复制粘贴即用）
CI 相关（Tekton）
bash
# 查看 Tekton 组件状态
ssh root@<MASTER_IP> 'kubectl get pods -n tekton-pipelines'
# 查看最近的 PipelineRun
ssh root@<MASTER_IP> 'kubectl get pipelineruns -n tekton-pipelines --sort-by=.metadata.creationTimestamp | tail -5'
# 查看某个 PipelineRun 的 TaskRun
ssh root@<MASTER_IP> 'kubectl get taskruns -n tekton-pipelines | grep <pipelinerun-name>'
# 查看构建日志
ssh root@<MASTER_IP> 'kubectl logs <pod-name> -n tekton-pipelines -c step-build-and-push --tail=100'
# 查看 EventListener 日志
ssh root@<MASTER_IP> 'kubectl logs -n tekton-pipelines -l eventlistener=gitee-listener --tail=50'
# 删除所有 PipelineRun（清理）
ssh root@<MASTER_IP> 'kubectl delete pipelineruns --all -n tekton-pipelines'CD 相关（ArgoCD）
bash
# 查看 ArgoCD 组件状态
ssh root@<MASTER_IP> 'kubectl get pods -n argocd'
# 查看 Application 状态
ssh root@<MASTER_IP> 'kubectl get applications -n argocd'
# 查看 Application 详情
ssh root@<MASTER_IP> 'kubectl describe application service-test -n argocd'
# 手动触发同步
ssh root@<MASTER_IP> 'kubectl annotate application service-test -n argocd argocd.argoproj.io/refresh=hard --overwrite'
# 查看 ArgoCD 日志
ssh root@<MASTER_IP> 'kubectl logs -n argocd -l app.kubernetes.io/name=argocd-server --tail=50'服务相关
bash
# 查看服务 Pod 状态
ssh root@<MASTER_IP> 'kubectl get pods -n service-test'
# 查看服务日志
ssh root@<MASTER_IP> 'kubectl logs -n service-test -l app=user-service --tail=30'
ssh root@<MASTER_IP> 'kubectl logs -n service-test -l app=web-service --tail=30'
# 重启服务
ssh root@<MASTER_IP> 'kubectl rollout restart deployment -n service-test'
# 回滚服务
ssh root@<MASTER_IP> 'kubectl rollout undo deployment/user-service -n service-test'
# 测试 API
curl http://<MASTER_IP>:<WEB_PORT>/api/user/1Harbor 相关
bash
# 检查 Harbor 健康状态
curl -s -u admin:<HARBOR_PASSWORD> http://<MASTER_IP>:<HARBOR_PORT>/api/v2.0/health
# 查看 service-test 项目的镜像
curl -s -u admin:<HARBOR_PASSWORD> http://<MASTER_IP>:<HARBOR_PORT>/api/v2.0/projects/service-test/repositories | python3 -m json.tool
# 查看 Harbor Pod 状态
ssh root@<MASTER_IP> 'kubectl get pods -n devops'八、金句总结（记住这些就够了）
📌 CI/CD 的本质：
"代码推送后，自动构建、自动部署，人只需要写代码"
📌 Tekton 的角色：
"建筑工人 ------ 把代码变成镜像"
📌 ArgoCD 的角色：
"强迫症管家 ------ 让集群状态和 Git 配置保持一致"
📌 排查问题的顺序：
"触发了吗？→ 构建成功了吗？→ 镜像推送了吗？→ 同步了吗？→ Pod 启动了吗？"
📌 最重要的一句话：
"Git 仓库是唯一真相来源，所有修改都要通过 Git"九、延伸学习
想深入了解 Tekton：
- 📖 Tekton 官方文档
- 📖 本项目教程：
02_tekton/TEKTON_TUTORIAL.md
想深入了解 ArgoCD：
- 📖 ArgoCD 官方文档
- 📖 本项目教程：
04_argocd/ARGOCD_TUTORIAL.md
想了解遇到的问题：
- 📖 问题排查指南：
TROUBLESHOOTING.md
十、版本信息
| 项目 | 信息 |
|---|---|
| 文档版本 | v2.0 |
| 更新日期 | 2026-01-02 |
| 适用项目 | service-test 微服务 |
| Tekton 版本 | Pipeline v1.6.0, Triggers v0.34.0 |
| ArgoCD 版本 | v2.9.3 |
| 作者 | DevOps Team |
"好的 CI/CD 系统，就像一个靠谱的助手：你只管写代码，剩下的交给它。" 🚀