赛博兵工厂的自动化流水线：部署 ArgoCD 声明式 GitOps

📖 认识赛博兵工厂：为什么必须是 ArgoCD？

曾经，我们习惯于在终端里手动敲击 kubectl apply -f 来部署应用。但当集群规模扩大，这种方式会带来潜藏的“运维灾难”：没人记得谁在什么时间修改了哪条配置，集群的实际运行状态与本地文件发生“配置漂移”时难以察觉，一旦遭遇严重故障，想要精准、快速地回滚到上一个稳定版本简直是痴人说梦。

为了实现真正的“全自动交付”，我们必须引入 GitOps 理念——将 Git 仓库打造为集群状态的唯一真理源。而 ArgoCD，正是这套流水线上最核心的齿轮。

📜 官方特性白皮书 (Official Features)

根据 ArgoCD 官方文档，它为集群带来了以下三大降维打击般的核心能力：

🛡️ 声明式配置与版本控制 (Declarative Setup & Version Control) 所有的环境配置和应用定义（YAML/Helm/Kustomize）都被死死地锁定在 Git 仓库中。任何对集群的修改，都必须通过提交代码（Commit）和合并请求（PR）来完成，自带完美的审计日志。

🗃️ 自动化状态同步与自愈 (Automated Sync & Self-Healing) 告别手动干预。ArgoCD 能够自动将 Git 仓库中的期望状态同步到集群中。如果有人试图在集群内部手动篡改配置，ArgoCD 的自愈机制会瞬间将其覆盖，确保集群状态永远忠于代码。

🌍 直观的可视化管理 (Visual Management) 它提供了一个极其硬核且直观的 Web UI 面板。复杂的微服务架构、Pod 的健康状态、网络拓扑关系，在这里一览无余，点点鼠标即可完成应用的回滚与状态排查。

一句话总结它的工作原理 (How ArgoCD works)：

ArgoCD 就像是一个极其严苛且不知疲倦的“赛博监工”。它会 24 小时盯着你指定的 Git 仓库（图纸库），并不断与 K8s 集群的实际运行状态（施工现场）进行比对。一旦发现现场与图纸有一丝一毫的不一致，它就会立刻触发部署流程，强行把集群状态拉平。

🎬 施工演示录像 (Video Walk-through)

正在嗅探浏览器语言并加载赛博录像...

---

🔨 核心施工流程 (Installation Steps)

官方安装指南

为了剥离复杂的依赖，我们这次不使用 Helm，直接采用官方最硬核、最原生的声明式安装指令进行基建。

步骤 1：下发官方一键浇筑指令

掏出你的终端，直接向集群下达这两条官方原版指令，建立 ArgoCD 专属的独立园区并拉起所有核心组件：

# 1. 划拨专属的隔离命名空间
kubectl create namespace argocd

# 2. 强制拉取并应用官方稳定版图纸
kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

执行后，集群会疯狂拉起相关的 CRD、控制器和 Redis 缓存。你可以使用 kubectl get pods -n argocd -w 盯紧组件的启动进度，直到全部变为 Running。

步骤 2：联动 Cilium，打通专属 VIP 负载均衡通道

默认情况下，ArgoCD 的 UI 面板（argocd-server）只在集群内部可见（ClusterIP）。为了让我们能从局域网直接访问，我们需要召唤底层铺设的 Cilium L2 负载均衡器，为它分配一个专属的靓号 IP。

我已经将标准化网络图纸归档在了 GitHub 仓库中。请前往仓库获取文件，并务必将其中的占位符替换为你自己实际局域网中规划的可用 IP：

👉 获取网络图纸：infrastructure/argocd/service.yaml

在本地修改完成后，将这张网络图纸提交给集群执行覆盖：

kubectl apply -f service.yaml

步骤 3：破译初始最高权限密码

ArgoCD 在建成时，会在底层生成一个高强度的初始 admin 密码，并将其封装在 Kubernetes 的 Secret 保险箱中。

执行以下“破译”指令，通过 base64 反向解码提取你的初始明文密码：

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

(⚠️ 施工警告：请将终端输出的这段随机字符串妥善保存，我们马上就要用到它。)

🎉 竣工验收：进入赛博指挥中心

打开你的浏览器，直接访问我们刚刚配置的 VIP 通道： 👉 https://10.0.10.53 (⚠️ 记得替换为你自己实际修改的 IP)

(注：因为使用的是自签名证书，浏览器可能会提示不安全，点击“高级” -> “继续访问”即可。)

在极具科技感的登录界面中，输入账号 admin，密码填入刚刚破译的那串字符。点击登录后，属于你的 GitOps 自动化流水线地基，至此彻底落成！

🛡️ 战后安全清理：重铸指挥官密钥

这串由机器随机生成的初始密码既反人类又难记。作为赛博总指挥，登录后的第一件事就是必须将其换成我们自己的专属密钥。

1. 进入个人中心：在 ArgoCD Web UI 的左侧边栏，点击最下方的 User Info (用户信息) 图标。
2. 触发更新指令：在弹出的面板中，点击右上角的 UPDATE PASSWORD 按钮。
3. 完成密钥交接：
   • Current Password：粘贴你刚才用 base64 破译出来的初始乱码密码。
   • New Password / Confirm：输入你自己的高强度专属密码。
4. 保存并重新接入：点击 SAVE 保存。为了安全起见，ArgoCD 会立刻切断当前的会话并将你踢出系统。使用你刚刚设置的新密码重新登录，彻底夺回这座指挥中心的绝对控制权！

---

🔗 资源接入：配置集群与 Git 仓库授权

在正式开始全自动布线之前，我们需要在 ArgoCD 中完成两项基础的资产登记：确认集群状态与挂载 Git 图纸库。

1. 检查集群状态 (Clusters)

点击左侧边栏的 Settings（设置），进入 Clusters 界面。

此时你会看到名为 https://kubernetes.default.svc 的本地集群。这是 ArgoCD 默认安装后自带的“自管集群”。

• 状态说明：如果你看到 Status 显示为 Unknown，请不必担心。这是因为目前尚未有任何应用部署在该集群上，ArgoCD 还没有触发主动的健康检查。
• 预期结果：只要等到我们下发第一个应用图纸，这里的状态就会自动转为绿色的 Successful。

2. 挂载 Git 图纸库 (Repositories)

这是实现 GitOps 的关键一步。我们需要通过 HTTPS 协议将 GitHub 上的私有或公有仓库授权给 ArgoCD。

1. 进入仓库管理：点击 Settings -> Repositories。

2. 启动连接向导：点击左上角的 CONNECT REPO 按钮。

3. 配置连接参数：在弹出的侧边栏中，按照以下标准进行填写：

   • Choose connection method: 选择 via HTTPS。
   • Type: 选择 git。
   • Name: 为这个仓库起一个识别名称（例如：cyber-fortress-drawings）。
   • Project: 保持 default 即可。
   • Repository URL: 填入你的 Git 仓库 HTTPS 地址（例如：https://github.com/你的用户名/你的仓库名.git）。

4. 身份验证 (Credentials)：

   • Username: 填写你的 GitHub 用户名。
   • Password: ⚠️ 极度重要：这里必须填写你生成的 Personal Access Token (PAT)，而不是你的 GitHub 登录密码！
   • 如果你还没准备好这把“万能钥匙”，请参考这篇前置指南：🔑 GitHub PAT 生成完全手册。

5. 确认连接：点击底部蓝色的 CONNECT 按钮。

🎉 验证结果：绿色通行证

返回 Repositories 列表页面。如果看到你的仓库 CONNECTION STATUS 显示为绿色的 Successful，则说明通道已彻底打通！

现在，ArgoCD 已经具备了实时监听你 Git 仓库变动的权限。你的每一行代码变更，都将直接驱动集群现场的施工。

---

🏗️ 导入总控图纸：App of Apps 模式与一键部署

在传统的认知里，部署应用就是去 ArgoCD 界面上一次次点击 “NEW APP” 填写表单。但在真正的赛博堡垒中，我们绝不干这种重复的体力活。

我们将使用 GitOps 领域最经典的 App of Apps（应用套应用） 模式。简单来说，我们只向集群下发一份“总包合同”（Root App），这份总包合同会自动去 Git 仓库里把底层网络、存储、业务面板等所有的子图纸全部拉取出来，实现真正的一键全自动建城。

我已经为你准备好了一整套开箱即用的标准图纸库，请访问赛博工地的开源仓库： 👉 GitHub 仓库：besthomelab/k3s-homelab-gitops

第一步：Fork 并认领你的工地

千万不要直接使用我的原版仓库进行部署！因为里面写死了我的域名和参数。 请在 GitHub 上点击 Fork，将这份图纸复制到你自己的账号下。从此，它就是你独一无二的真理之源。

🔍 赛博工地移交指南：全局搜索与替换 (克隆后必做)

在把图纸下发给集群前，你必须在本地使用代码编辑器（如 VS Code）打开你 Fork 后的项目，参考下表执行全局搜索与替换。如果不做这一步，你的总监工（ArgoCD）将会一直跑来我的仓库拉图纸，你的集群将彻底脱离你的控制！

全局搜索关键字 (Search)	替换为你的数据 (Replace With)	涉及核心组件与作用说明
REPLACE_ME	你本地规划的具体参数	⚠️ 底层硬装：主要涉及局域网 LoadBalancer 靓号 IP、物理机器网卡名称、NFS 真实挂载路径等。
https://github.com/besthomelab/k3s-homelab-gitops.git	你的 Git 仓库 URL	🐙 总监工图纸源：极其重要！决定了 ArgoCD 从哪里拉取配置。必须全仓库替换，否则无法实现自我托管。
besthomelab.tech	你的专属域名	🌐 七层迎宾大门：主要涉及 Ingress 路由规则、TLS 证书签发、以及导航页等配置。

---

第二步：🔐 密码凭证的特殊处理 (极其重要)

因为本开源图纸库是公开展示的，所以绝对不能将明文密码直接推送到公开仓库中。对于你个人的赛博堡垒，强烈建议你 Fork 后在设置里将仓库改为私有 (Private)，以确保敏感配置仅对自己可见。

但哪怕是在你自己的私有仓库里，为了遵循 GitOps 最高的安全规范，我们也绝不让密码“明文裸奔”。本仓库使用了 Bitnami Sealed Secrets 技术。你可以把它理解为一种“单向加密信封”：只有你家集群的控制器才能拆开它。由于仓库里现有的 secret.yaml 是用博主的集群公钥加密的，你的集群绝对解不开！

你需要做的简单处理：

1. 在克隆下来的应用目录（如 apps/management/portainer/）中，找到 secret.template.yaml 模版。
2. 填入你自己的真实密码，然后使用 kubeseal 命令行工具将其加密，覆盖掉原本的 secret.yaml。
3. 提交并推送到你自己的仓库。

💡 如果这是你第一次接触，不知道如何安装和加密，请务必先查阅这篇核心安全指南： 👉 部署 Sealed Secrets，实现 100% 纯正的 GitOps 密码管理

第三步：两阶段浇筑，启动自动部署

在 Kubernetes 的架构中，业务应用严重依赖底层基础设施。如果地基没打好就盖高楼，应用必定会大规模崩溃。因此，我们的总包合同分为两期工程。

回到你的控制台终端，依次执行以下指令：

🚧 阶段一：浇筑基础设施大坝 提交包含存储和核心底座的母应用图纸：

kubectl apply -f bootstrap/root-infra.yaml

⏳ 喝口茶，打开你的 ArgoCD 网页控制台。你会看到 longhorn 等应用正在自动部署。必须等待它们全部变成绿色的 Healthy（约需 3-5 分钟），才能进行下一步。

🏢 阶段二：拉起上层业务应用 当地基完全稳固后，下发业务应用的图纸：

kubectl apply -f bootstrap/root-apps.yaml

切回 ArgoCD 面板，你会看到诸如监控、管理面板等工具如雨后春笋般全自动落成！

---

📖 进阶指引：读懂赛博监工的“操作法典”

当你的 App of Apps（应用套应用）跑起来，满屏亮起绿色的 Synced 状态后，你日常的维护重心就会转移到 ArgoCD 的可视化 Web 面板上。

在日后排查问题、点击应用的 SYNC 按钮，或者查看 APP DETAILS 时，你会看到琳琅满目的英文勾选项：Prune Last、ServerSideApply、Replace、Self Heal…… 这些开关每一个都掌握着赛博大楼的生杀大权。

在没有搞懂底层逻辑之前，千万不要在生产环境盲目勾选这些高级开关！ UI 界面只是新手村的辅助轮，YAML 代码才是咱们赛博堡垒的硬通货。

为了让你彻底吃透这位“赛博监工”的脾气，实现从“UI 点按玩家”到“纯 YAML 架构师”的硬核进阶，我特意为你编纂了一本全参数映射大典。

如果你想知道界面上的每一个按钮对应着底层图纸里的哪一行代码，或者手动同步时的四大指令到底有什么破坏力，请务必查阅并收藏这本法典：

👉 镇站之宝：ArgoCD 赛博监工全参数 UI 映射大典与操作指南

---

⚡ 终极加速：接入 GitHub Webhook 实现毫秒级响应

在默认配置下，ArgoCD 会每隔 3 分钟去 Git 仓库“轮询（Polling）”一次，对比现场与图纸的差异。虽然 3 分钟不算长，但在调试代码时，每次提交后都要干等或者去面板手动点 SYNC 按钮，依然让人觉得不够“赛博”。

为了实现真正的“Push 即部署”，我们需要让 GitHub 在收到代码的瞬间，主动向 ArgoCD 发送一个“图纸已更新”的信号——这就是 Webhook。

得益于我们在网络架构中架设的 Cloudflare Tunnel 隐形大桥或基于 OPNsense Caddy 的 IPv6 直连穿透，我们的内网 ArgoCD 现在已经可以安全地接收来自公网的请求了。

[!CAUTION]

🚨 首席架构师的避坑指南：纯 IPv6 域名的“单相思”问题

虽然我们在 IPv6 穿透篇 中成功实现了公网直连，但请务必注意：GitHub 的 Webhook 发送服务器目前仅支持 IPv4 协议。

如果你的 argocd.k3s... 域名在 Cloudflare 中仅配置了 AAAA 记录（灰云/DNS Only），GitHub 的服务器在解析时会因为找不到 A 记录（IPv4）而直接报错 failed to connect to host。

🏗️ 终极方案：纯血 GitOps 的双层 Secret 架构

很多教程会让你手动敲击命令去修改 ArgoCD 的核心密码箱。作为首席架构师，我们坚决抵制这种违背 GitOps 原则的“暗箱操作”。得益于 ArgoCD 官方提供的 Alternative 特性，我们可以通过巧妙的引用机制，将 Webhook 密码也实现 100% 的代码化，且绝对不暴露明文。

第一步：锻造独立的加密密码箱 (Sealed Secret)

我们需要先在本地创建一个独立的 Secret，把真实的 Webhook 接头暗号放进去，并用 kubeseal 加密。

如果你还没有接头暗号，可以打开终端，执行以下命令生成一串极其安全的随机字符串：

# 生成 32 位高强度随机密码（请复制并妥善保存，稍后 GitHub 配置需要用到）
openssl rand -base64 32

👉 获取密码箱图纸模版：infrastructure/argocd/webhook-secret.template.yaml (注意：此模版中必须包含 app.kubernetes.io/part-of: argocd 标签，这是官方特性生效的硬性要求。)

将生成的暗号填入本地模版的 github-secret 字段后，执行以下命令进行非对称加密，生成集群可读的密文图纸：

# 加密并输出为最终的 sealed secret 文件
kubeseal --format yaml < infrastructure/argocd/webhook-secret.template.yaml > infrastructure/argocd/webhook-secret.yaml

⚠️ 赛博防泄漏最高级警告： 加密指令执行完毕后，你的本地模版文件里依然残留着刚才填写的明文密码！ 请立刻执行 git checkout infrastructure/argocd/webhook-secret.template.yaml 将该文件强行还原为初始的空白状态，或者手动清空密码字段。绝对、绝对不能把带有明文密码的模版 git commit 到仓库中！

第二步：为总监工下发“寻宝图” (Kustomize Patch)

接下来，我们不需要在 Git 里写明文密码，而是给 ArgoCD 的主保险箱打个补丁，告诉它：“密码别找我，去刚才建的那个新保险箱里拿”。 👉 获取寻宝图补丁：infrastructure/argocd/patch-argocd-secret.yaml (你可以在源码中看到，里面的值是以 $ 开头的纯引用指令。因为没有真实密码，直接提交到公开仓库绝对安全！)

第三步：统筹组装与本地沙盘推演 (Kustomization)

最后，在总装清单 kustomization.yaml 中，将上述两个文件（一个 Resource，一个 Patch）包含进去。 👉 获取最终装配图纸：infrastructure/argocd/kustomization.yaml

🧪 赛博架构师的本地质检： 在将这些修改 git push 到 GitHub 之前，我们需要在本地验证 Kustomize 的组装逻辑是否正确、有没有语法拼写错误。在终端执行以下推演指令：

# 在本地预览最终生成的纯 YAML（不会对集群产生任何实际影响）
kubectl kustomize infrastructure/argocd/

如果在输出的巨量 YAML 中没有报错，你能找到 argocd-secret 并且里面成功合并了我们刚刚打的 webhook.github.secret 补丁，就说明图纸组装完美无缺！可以直接 Push 交给系统全自动部署。

---

第四步：在图纸库装配发报机 (GitHub 设置)

1. 打开你 Fork 的 k3s-homelab-gitops 仓库主页。
2. 点击右上角的 Settings -> 左侧边栏的 Webhooks -> 点击 Add webhook。
3. 按照以下绝密参数进行填报：
   • Payload URL: https://argocd.k3s.besthomelab.tech/api/webhook (⚠️ 务必替换为你的域名，且必须以 /api/webhook 结尾)
   • Content type: 下拉选择 application/json (必须是 JSON，否则监工无法解析)
   • Secret: 填入你在第一步中写入底层密码箱的那个“超强接头暗号”。
   • Which events would you like to trigger this webhook?: 选择 Just the push event.
4. 点击 Add webhook 保存。

🎯 见证奇迹的时刻

配置完成后，GitHub 会立刻发送一条测试 Ping 数据包。如果你看到这条记录前面出现了一个 绿色的勾号 (✅)，这意味着整条赛博流水线已彻底打通！

从此以后，你在本地敲下 git push 回车键的同一秒钟，ArgoCD 就会光速响应，K3s 集群的齿轮将立刻开始轰鸣！

---

📐 架构师的绘图板：赛博堡垒两大核心部署模版

在熟悉了 ArgoCD 的界面之后，我们要正式建立赛博工地的规矩：真正的架构师，从不在 UI 界面上点选表单创建应用。 UI 界面只是我们的“施工监控大屏”，所有的应用部署指令，都必须通过编写 Application 资源的 YAML 图纸来完成。为了避免每次部署新应用都要从头手搓复杂的参数，我为你提炼了两套万能施工模版，它们涵盖了 HomeLab 中 99% 的应用部署场景。

你可以在我的 GitHub 仓库 templates/argocd-apps 目录下找到它们：

📦 模版一：Helm 多源混合部署 (Helm Multi-Source)

在云原生世界里，绝大多数开源软件（如 Longhorn、Prometheus）都提供了官方的 Helm Chart。但如果我们直接用官方的，怎么注入我们自己的专属配置呢？这就需要用到**“多源混合部署”**技术。

• 适用场景： 需要引用外部官方的 Helm 仓库作为“骨架”，同时使用我们自己 Git 仓库里的 values.yaml 文件作为“软装”来覆盖默认参数。
• 核心原理： ArgoCD 会同时拉取官方的 Chart 包和本地的 Git 仓库，将其在内存中合并后，下发给 K8s 集群。这样既保证了软件版本与官方同步，又实现了配置代码的私有化管理。
• 获取图纸： 👉 helm-multi-source-template.yaml

📄 模版二：纯 YAML 静态清单部署 (Raw YAML)

并不是所有应用都需要重量级的 Helm。有时候，我们只想跑一个简单的 Nginx 静态网站，或者部署一个自己写的 Python 小脚本，只需要手写原生的 Deployment、Service 和 Ingress 即可。

• 适用场景： 没有 Helm Chart，完全由你自己手写的纯原生 K8s YAML 文件集合。
• 核心原理： 采用 Directory（目录扫描）引擎。ArgoCD 会直接盯着你指定的 Git 文件夹，把里面的所有合法的 YAML 文件一股脑儿糊到集群里。模版中还内置了“赛博过滤网”（Exclude 规则），防止 ArgoCD 把用来参考的密码明文模版（*template*）误部署到集群中。
• 获取图纸： 👉 raw-yaml-template.yaml

---

💡 施工小贴士： 以后每当你想在赛博堡垒里加盖一座新建筑，只需要复制上面对应的模版，把里面的 <APP_NAME>、<PATH_TO_APP_DIR> 等尖括号占位符替换成你的真实路径，然后把它推送到 Git 仓库。你的监工 ArgoCD 就会立刻感知到新图纸，全自动完成剩余的所有基建工作！