经过多年的建设与治理，我的 Homelab 逐渐形成了一套覆盖本地与云端的基础设施，也沉淀出一套相对标准化的维护规范。从环境资料、配置管理到变更执行与验收，日常维护有了可以查阅和遵循的依据。
现行体系参考了之前多年在 SaaS 领域的治理实践经验。
用声明式配置和 GitOps 管理期望状态，通过监控与告警观察实际运行情况，把变更前的检查、执行步骤和恢复方式整理进 SOP。结合个人环境的规模和维护成本，我将这些经验逐步落实到 Homelab 的工程结构与操作规范中。
下面的架构图概括了目前的基础设施层次，以及贯穿其中的工程治理和可观测性能力。
长期维护下来，最主要的痛点是持续投入的精力，主要集中在几个方面：
-
各层组件都需要定期维护：Proxmox VE、Ceph、Kubernetes，以及运行在上面的服务组件，都需要升级、检查兼容性并处理配置变化。
-
各组件的升级都需要单独调研：逐一查阅版本说明，识别破坏性变更（breaking changes），评估对现有配置、数据和服务的潜在影响，再确定适合当前环境的升级路线。
-
执行与排障需要投入精力：除了逐项完成升级操作，遇到问题时还需要排查和处理。实际部署包含个性化配置，可能产生与标准环境不同的行为，需要结合现场配置、日志和运行状态定位原因，再验证处理结果。
以往，我通常每年安排几天固定的假期，对整套环境集中做一次维护。从梳理版本与升级路径，到逐项执行、观察状态和处理异常，大部分过程都需要自己持续跟进。标准化规范减少了重复摸索，却没有消除执行和验证所占用的精力。
随着 AI 在代码理解、任务规划和工具调用上的能力逐渐成熟，我开始考虑将更多维护操作交给 Agent。生产环境中的许多动作与决策，仍然需要人结合业务影响作出判断。对于自己的 Homelab，在做好关键数据冷备份、明确恢复路径的前提下，则有条件尝试让 AI 承担更多实际操作，由我把握关键决策和验收结果。
本文围绕工程化与上下文治理，分享如何让 Agent 理解已有环境、参与实际维护，以及过程中遇到的问题和使用体验。
上下文治理与工程化
引入 Agent 之前，我已经建立了较为完整的声明式 Git 仓库，通过 Kustomize 与 Argo CD 管理服务编排。同时，工程中整合了大量虚拟机和物理机的维护脚本，覆盖初始化、配置调整和日常维护等操作。长期积累的配置与脚本，为 AI 阅读环境、准备修改和复用操作流程提供了基础。
上下文文档治理
上下文以当前环境的事实配置为依据，记录资源关系、操作条件与决策背景，并随部署变更持续更新。维护规则包括：
-
明确依据与适用范围：记录配置来源、脚本适用条件和验收要求，未确认的信息标明待核对，避免将旧操作直接用于当前环境。
-
同步变更与文档：完成部署和验收后，更新版本、拓扑、配置差异及操作规范，保持文档与环境一致。
-
集中维护公共约定：目录职责、授权边界与验证要求由
AGENTS.md统一说明，具体环境信息放入对应领域文档。
环境文档按领域组织，职责划分如下：
| 领域 | 目录 | 维护职责 |
|---|---|---|
网络 |
|
设备职责、网络拓扑、网段规划与连接关系 |
虚拟化 |
|
宿主机、虚拟机归属、资源分配与生命周期 |
存储 |
|
存储集群、磁盘、数据承载与挂载关系 |
Kubernetes |
|
集群构成、组件依赖、维护流程与排障依据 |
云端资源 |
|
云主机、托管服务、域名与访问关系 |
文档保留配置之外的维护依据，例如个性化调整的原因、手工维护范围和恢复条件。
Kubernetes 声明式治理
对于需要自己编排服务的 Kubernetes 环境，我通常习惯使用 Kustomize 管理，尽可能保留配置的灵活性与自由度。目录按职责分组组织服务，单组件保持扁平，多组件按需拆分。通用结构如下：
.
├── apps/
│ └── <职责分组>/
│ └── app.<服务>.yml # Application 指向对应服务入口
└── kubernetes/
└── <职责分组>/
├── <单组件服务>/
│ ├── kustomization.yml # 资源清单、命名空间与镜像配置
│ ├── deploy.yml # 工作负载
│ ├── service.yml # 服务访问
│ └── config/ # ConfigMap generator 的配置文件
└── <多组件服务>/
├── kustomization.yml # 聚合子组件，统一命名空间与公共标签
├── <组件一>/
│ ├── kustomization.yml
│ ├── deploy.yml
│ └── service.yml
└── <组件二>/
├── kustomization.yml
├── statefulset.yml
└── pvc.yml-
分组对应：
apps/与kubernetes/使用一致的职责分组，Application 的source.path指向服务的kustomization.yml所在目录。 -
默认扁平：单组件服务的资源文件直接放在服务目录，按需增加路由、证书、存储或权限声明，不为目录整齐而增加嵌套。
-
按组件拆分：服务包含多个可独立描述的组件时，再增加子目录。父级负责聚合与公共配置，子级维护各自的资源清单。
-
声明与配置隔离：资源文件描述部署结构，
config/独立维护配置内容，通过 Kustomize 的configMapGenerator生成 ConfigMap，再由工作负载引用。
明确的入口与层级，让 Agent 能够定位变更范围、检查渲染结果，并沿用既有结构维护声明，减少配置散落和重复定义。
通过工具接入运维环境
对于存在潜在风险的操作，我采用的原则是：仅通过成熟、规则明确且可审计的工具执行，不让 AI 临时编写代码直接操作环境。工具负责约束访问入口与操作范围、保留执行记录，Agent 在明确授权下调用这些能力。
只有仓库访问能力时，Agent 可以读配置、写补丁和整理计划。要参与实际维护，还需要看到运行状态，并在授权范围内操作节点。
我通过 XPipe 集中管理物理节点和虚拟机的 SSH 连接，并通过 MCP 向 Agent 提供远程操作入口。前期用于读取配置、整理上下文的连接，也用于后续经授权的维护操作，Agent 可以通过工具核对配置、执行命令并收集结果。
权限边界与敏感密钥隔离
密钥集中管理：敏感 SSH 密钥由 XPipe 管理，AI 不直接接触私钥，也无需将私钥放进工程目录或对话上下文。
通过工具授权操作：Agent 使用经过授权的连接访问环境。配置读取与变更执行分别授权，能够连接节点不代表可以任意修改其资源。
关键操作由人确认：涉及持久数据、节点销毁等不可逆操作时，需要先明确目标、影响和恢复安排，再授权执行。
工具接通以后，维护流程逐渐变成：先读取资料和现场状态，列出计划与影响，确认后按阶段执行，再收集验收结果。发现原先假设不成立时，应修订计划，而不是为了完成最初的命令列表继续推进。
历史事实配置补全
之前没有写详细的环境文档，主要还是懒。毕竟是自己的 Homelab，系统复杂度相对有限，不同网段和 VLAN 的用途、路由与访问边界，以及服务的部署位置、入口和存储依赖，大多自己心里有数，也就一直没有认真整理。
让 AI 参与以后，我给它开放必要的配置读取权限，由工具读取虚拟机和物理机的实际配置。路由器、交换机则直接导出配置备份，交给 AI 梳理网络划分、路由与访问规则，再结合声明式仓库整理服务入口、部署关系和存储依赖，我再核对结果、补充背景。
借助 AI 整理环境文档，比预想中轻松很多。尤其是路由器和交换机，配置备份直接甩给 AI，就能把分散在接口、VLAN、路由和访问规则中的信息关联起来。服务编排也类似，结合工作负载、Service、入口与存储声明，就能整理出服务的访问路径和依赖关系。对于我来说，最直观的感受是：补文档终于不再是一件需要专门攒精力去做的事。
网络拓扑中没有直接体现在配置里的设计思路，我也通过文字输入补充给 AI，例如网络划分的考虑、访问边界的设计依据，以及个性化调整的原因。结合配置事实和人工补充的背景，整理出的文档才能同时说明环境如何运行，以及为什么这样设计。凭据不进入通用上下文。
淘汰资料的归档与清理
历史资料仅用于追溯与参考，不能直接作为当前环境的操作依据。
退役设备、失效配置和旧维护流程应独立归档，避免混入现状文档、污染 Agent 上下文，导致错误的环境判断或操作。引用历史内容时，应先核对其适用条件与当前配置。
已被现行资料完全取代、且不再具有追溯或参考价值的内容，可以彻底移除，避免冗余信息持续干扰上下文。
AI Ops 应用实践
上下文治理初步完成后，我开始将几个例行维护任务交给 Agent，观察它在实际环境中能够承担多少调研、执行和排障工作。实践涵盖 Kubernetes 跨版本升级、Grafana 声明式治理，以及 GitLab、Argo CD 等组件的升级适配。下文重点介绍前两个案例，并简要补充虚拟机与公共脚本的治理，其余任务不再逐项展开。
Kubernetes 跨版本升级
集群之前已经将近两年没有做系统性的升级维护。Kubernetes 这几年的迭代比较快，而 kubeadm 部署环境的维护仍然相对繁琐，需要逐项调研版本变化、调整配套组件，再完成节点升级和验证。因此，我准备尝试让 AI 承担本次升级操作。
本次升级从 1.32 逐级推进到 1.36，期间还包含了节点操作系统换代。
我先让 Agent 读取环境文档、维护脚本与集群状态，整理升级方案。重点是让 AI 串联调研、兼容性判断、风险识别与实际操作，我负责审查方案和确认关键决策。
具体配合过程分为几个环节：
-
盘点环境与调研版本变化：Agent 核对当前 Kubernetes、容器运行时及网络、存储等配套组件版本，查阅目标版本的升级说明，整理破坏性变更和必要调整。
-
检查兼容性并规划路线：结合现有配置判断配套组件是否需要先行升级，安排控制面、工作节点与操作系统换代的顺序。升级按次版本逐级推进，路线依据 kubeadm 官方升级文档确认。
-
识别风险并由我确认方案：Agent 汇总可能的服务中断、配置差异和恢复安排，我结合 Homelab 的使用情况决定维护窗口、可接受的影响，以及需要保留的恢复点。
-
通过授权工具分步执行：方案确认后，Agent 按路线完成配套组件适配和节点升级，收集执行结果。遇到与预期不一致的情况，先结合配置与日志排查，再调整后续步骤。
-
验证结果并继续推进：每轮升级后检查节点和实际工作负载，验证新 Pod 的网络与存储挂载，操作系统换代后补做重启验证。通过后再进入下一版本，并将配置变化和处理结论写回工程。
操作系统换代中的 AI 协作
在启动新系统之前，我已经让 AI 参考历史部署与维护脚本，准备好适配新系统的整套维护脚本。已有操作经验得以复用，同时也需要重新检查新系统下的依赖和配置差异。
随后，我通过虚拟机模板启动空白系统，将新虚拟机的 SSH 访问也完全通过 XPipe 授权给 Agent，由它接手后续配置与节点部署。人工准备系统入口，Agent 结合已整理的上下文和配套脚本推进初始化、依赖安装及节点接入，敏感密钥仍保留在工具侧。
我的 Homelab 可以接受维护窗口内的短暂中断，因此部分安排以个人环境的维护成本为取舍依据。涉及是否中断服务、如何处理异常等决定时，我仍然参与判断。
最明显的体验变化，是不必持续守着终端推动每一步。Agent 能够把调研结论落实到操作，再根据执行结果继续检查和排障，我主要参与方案审查与关键节点确认。按当时记录，主要升级过程大约用了一天，前期的资料整理另计。
可观测性的声明式治理
第二个案例是可观测性治理，先从 Grafana 开始。之前使用的版本较老，看板主要在界面里编辑，元数据保存在数据库中，没有纳入工程上下文。日常需要时打开看板、补几个面板，很少系统整理指标为什么这样选、看板如何分层，以及还有哪些值得继续完善。
升级后，我尝试使用 Git Sync，将已有看板纳入声明式管理。
Git Sync：连接 Grafana 与 Git 的看板管理
Git Sync 将仪表盘与文件夹同步到 Git，既可以在界面编辑，也可以维护仓库中的 JSON 文件。原先留在数据库里的看板配置，由此成为 Agent 可以直接阅读、比较和修改的声明文件，设计说明也能随配置一起维护。采集配置和告警规则仍在对应的声明式编排中管理。
有了这层基础，我让 AI 结合实际环境重新梳理看板：哪些内容继续跟随上游，哪些已经做过本地适配，网络、主机、存储和服务分别需要关注什么。它负责查找配置、对比内容和整理调整，我补充使用习惯与设计考虑，再一起确认哪些信息应该保留、哪些监控盲区值得补上。
治理范围也从看板延伸到了监控采集和告警规则。我把 Homelab 场景下观测与告警规则的统一整理、编写和后续维护，也交给 AI 参与接管。例如结合设备和服务的职责检查采集覆盖，整理主机、存储、证书与服务可用性相关规则，并统一告警分级和通知文案。
看板通过 Git Sync 管理，采集和告警规则则在对应的声明式编排中维护。Agent 可以沿着采集目标、指标、面板和告警的关系检查配置，提出改进建议并准备修改。我主要确认告警是否值得关注、触发条件是否符合实际使用场景，以及部署后的结果。
比起单纯批量修改 JSON，更有价值的是终于能够系统地整理整套观测设计。以前缺少精力处理的配置关联、设计说明和改进事项，都有了可以持续维护的位置。后续新增服务或调整网络时，也更容易让 AI 沿用这些上下文，一并补上相应的观测和告警。
虚拟机治理与公共脚本工程化
传统上，我们在工程内建立 scripts/ 目录，集中管理部署与维护脚本。操作系统初始化、网络配置、磁盘扩容、运行时安装和监控接入等重复工作，都逐渐积累了可复用的操作步骤，作为后续维护的基础。
脚本纳入工程管理后，主要带来以下价值：
-
可追溯、可审查：通过 Git 保留变更记录与调整原因，执行前可以检查脚本差异，确认修改范围和影响。
-
可复用：让 Agent 对照已有脚本与实际配置，抽取公共步骤，将地址、网卡、磁盘等节点差异作为明确参数维护。
-
可迭代：系统版本或部署方式变化时，在现有脚本上适配，并把排障结论和验证结果补回工程，逐渐积累维护经验。
AI 可以协助比较、抽取和更新脚本，我负责审查关键修改，再通过授权工具执行。一次维护留下的脚本与说明，也成为下一次任务能够直接使用的上下文。
总结与感悟
对我来说，AI 更像是成了人的手，接管了传统上需要手动处理的许多繁琐事务。从资料查找、配置对比，到重复操作和排障推进，维护不再需要持续占用一整段精力，我主要参与设计讨论、方案确认与结果验收。执行时间未必更短，但不必一直守着终端，对个人维护 Homelab 已经很有价值。
经过实践，我更看重以下几点：
-
减少持续盯守的投入，将精力集中到设计与关键判断。
-
工程化和上下文治理是接管的基础，配置、文档与脚本需要同步维护。
-
维护经验能够持续积累，配置变化和处理结论回写工程，供后续任务复用。
关键取舍仍然由我负责，包括是否允许中断、选择什么升级路线，以及出现偏差后是否继续。我也能把精力和时间留给更加值得折腾的新方向。
最后修改于 2026-10-15
