我的家庭实验室 AI 开发平台：一种基于 GitOps 的安全工作流

背景

作者近期对其家庭实验室（Homelab）的基础设施管理进行了重大升级。此前，作者管理着大约十几个基于 docker compose 的服务栈，这些服务最初部署在 TrueNAS 上。为了提升管理的规范性和可追溯性，作者将这些服务迁移到了 Arcane 平台，从而实现了基于 GitOps 的部署模式。

在确立了 Git 作为基础设施即代码（IaC）的核心存储后，作者认为下一步的自然演进是引入 AI 工具来辅助维护这些服务。传统的容器更新流程极其耗时：需要手动查阅每个服务的发布说明（Release Notes），检查破坏性变更，执行更新，并逐一验证服务状态，整个过程往往需要数小时。作者希望利用 AI 技术来简化这一过程，提高版本升级的安全性和效率。

核心内容

工具选型与架构设计

在评估了多种 AI 编码工具后，作者主要考虑了 Claude Code，但鉴于近期 AI 提供商通过令牌限制（Token Limits）压缩用户价值，作者决定寻找一个厂商中立且支持主流插件的替代方案。最终，作者选择了 OpenCode。

作者青睐 OpenCode 的原因包括：

1. 厂商中立性：不绑定单一的大模型提供商。
2. Web UI 与持久化会话：OpenCode 内置 Web 服务器，支持跨设备的持久化编码会话同步。
3. 移动端体验：其移动端 Web UI 中的问答弹窗交互体验优于其他竞品。
4. 开发环境集成：OpenCode 自带终端、文件浏览器、Git Diff 查看器以及支持多会话管理的 Git worktree 功能。

基础设施部署

作者在一个位于 TrueNAS 主机上的简单虚拟机（VM）上搭建了开发环境，并将 OpenCode Web 服务器配置为 systemd 单元。该 VM 的配置遵循最小权限原则：

• 网络隔离：VM 拥有互联网访问权限和 Git 服务器的访问权限，但无法直接访问作者的实际生产服务。
• 权限控制：OpenCode 在 Git 服务器上拥有独立的用户账户和专用的 SSH 密钥。它可以克隆项目并推送分支，但被禁止直接推送到部署分支（Deploy Branch）。
• Root 权限：出于构建工具和测试依赖安装的需要，作者允许 OpenCode 在 VM 上拥有 Root 权限。由于隔离措施到位，爆炸半径（Blast Radius）很小，因此风险可控。

核心工作流：AI 作为 PR 审查前的代码生成者

作者建立了一套严格的工作流，确保 AI 生成的代码必须经过人工审查才能部署：

1. 规划与实现：在 OpenCode 中规划功能或改进项，包括编写规范、实施计划以及自我审查。
2. 初步验证：作者尽可能对更改进行测试或验证。
3. 迭代优化：作者对不满意的部分与 OpenCode 进行迭代交互。
4. 推送分支：OpenCode 将更改推送到特性分支（Feature Branch）。
5. 创建 PR：作者为该分支创建拉取请求（Pull Request, PR）。
6. 人工合并：作者审查 PR 后，手动合并代码。
7. GitOps 部署：合并后，GitOps 工具接管部署工作。具体包括：
   • 使用 Arcane 处理 Docker 服务变更。
   • 使用 GitOps 插件处理 Home Assistant 配置变更。
   • 使用 Cloudflare Pages Worker 处理博客变更。

实际应用场景与收益

• 容器更新辅助：AI 可以在几分钟内总结发布说明，帮助作者快速识别破坏性变更，将原本需要数小时的工作缩短至几分钟。
• 健康检查增强：作者利用 AI 为大多数容器添加了健康检查（Healthchecks），从而能更快地发现潜在问题。
• 网络管理简化：迁移到 Git 驱动的配置后，作者可以通过手机使用 OpenCode 一次性更新所有容器的网络配置。以前需要数小时梳理的网络连通性追踪工作，现在只需向 AI 指定目标，审查 PR 并合并即可。

当前局限与未来展望

作者指出当前设置的主要缺失环节是 CI（持续集成）反馈。在 GitHub 上，作者喜欢将编码代理指向 Actions 日志，以便诊断失败的测试、Linter 错误、堆栈跟踪和 IaC 计划变更，从而保持快速的反馈循环。

然而，由于作者使用的是 Forgejo，其 Actions 并未通过公共 API 暴露作业日志。虽然存在未文档化的 API，但作者不愿依赖此类不稳定接口。

尽管存在这一局限，作者认为这种架构足以满足个人需求，且组件精简。作者也设想将此模式扩展为生产级开发者平台，提供预装工具的临时容器、访问护栏和审计日志，但对于个人 Homelab 而言，当前的方案已足够高效。

关键要点

• GitOps 为核心：所有基础设施变更必须通过 Git 仓库进行版本控制，利用 Git 作为单一事实来源。
• AI 角色定位：AI（OpenCode）仅作为代码生成器和辅助分析工具，不具备直接部署或修改生产环境的权限。
• 安全隔离机制：
  • AI 运行的 VM 无法访问实际的服务网络。
  • AI 的 Git 账户被限制只能推送特性分支，禁止直接推送至主部署分支。
  • 所有变更必须经过人工审查（PR Review）并手动合并。
• 跨设备协同：利用 OpenCode 的 Web UI 和持久化会话特性，实现从电脑发起变更、在手机上审查 PR 的灵活工作流。
• 效率提升显著：将容器更新、网络配置梳理等耗时任务从“数小时”缩短至“几分钟”，并通过 AI 辅助添加健康检查提升系统可观测性。
• 技术栈组合：TrueNAS (Host) + Arcane (GitOps for Docker) + OpenCode (AI Coding Agent) + Forgejo (Git Server) + Home Assistant/Cloudflare (Specific Services)。

意义与影响

这篇文章为个人开发者和技术爱好者提供了一个极具参考价值的 AI 辅助基础设施管理范式。它解决了在引入 AI 自动化时普遍存在的两个核心痛点：安全性与可控性。

1. 重新定义 AI 在 DevOps 中的边界：作者没有盲目追求全自动化，而是确立了“AI 生成，人类决策，GitOps 执行”的混合模式。这种模式既利用了 AI 在代码生成、日志分析和配置编写上的效率优势，又通过 Git 的工作流机制保留了人类对生产环境的最终控制权，有效规避了 AI 幻觉或错误指令导致的生产事故风险。
2. Homelab 现代化的最佳实践：对于管理复杂 Docker 堆栈的用户来说，从传统的直接操作迁移到基于 Git 的版本控制是必然趋势。本文展示了如何将 AI 工具无缝集成到这一流程中，特别是利用 AI 处理繁琐的配置变更（如网络拓扑、依赖版本），极大地降低了维护复杂家庭实验室的技术门槛和时间成本。
3. 对工具选型的启示：作者对 OpenCode 的选择及其对厂商中立、Web UI 体验和移动端支持的重视，反映了当前开发者对 AI 编码工具的新需求——不仅仅是代码补全，更是需要能够融入现有 Git 工作流、支持持久化上下文且跨平台可用的完整开发环境。
4. 可扩展性的潜力：虽然作者目前仅用于个人 Homelab，但其提出的架构（隔离的 AI 环境、严格的权限控制、审计日志）具备向小型团队或生产环境扩展的潜力。这为构建内部开发者平台（IDP）提供了一种轻量级的思路，即通过 Git 作为中间层，安全地引入 AI 生产力工具。