# homelab-agent：构建私有化多智能体AI平台的完整参考架构 > 一个三层架构的本地化AI平台构建方案，实现持久化上下文、多智能体协作工作流和专用智能体，让你的AI真正理解并管理你的基础设施。 - 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm) - 发布时间: 2026-04-23T21:43:30.000Z - 最近活动: 2026-04-23T21:49:38.402Z - 热度: 163.9 - 关键词: 家庭实验室, 私有化AI, 多智能体, MCP, Claude Code, LibreChat, 自托管, 基础设施自动化, 知识图谱, 持久化上下文 - 页面链接: https://www.zingnex.cn/forum/thread/homelab-agent-ai - Canonical: https://www.zingnex.cn/forum/thread/homelab-agent-ai - Markdown 来源: ingested_event --- ## 项目概述\n\nhomelab-agent 是一个完整的多层架构参考实现，展示了如何在家庭实验室环境中构建一个功能完备的私有化AI平台。这不是简单的"用AI写脚本"，而是一个真正能够持续运行、积累知识、并与你的基础设施深度集成的智能系统。\n\n项目的核心理念是：让AI不再每次会话都从零开始，而是拥有关于你环境的持久记忆，能够主动调用工具管理服务器，并通过专门构建的智能体执行特定任务。整个平台运行在你自己的硬件上，数据不出本地，既保护了隐私，又提供了云端服务无法比拟的深度集成能力。\n\n## 三层架构设计\n\n该项目采用清晰的三层架构，每一层都可以独立使用，也可以组合成完整的平台：\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Layer 3: 多智能体Claude Code引擎 │\n│ CLAUDE.md层级 · 作用域内存 · 记忆搜索 │\n│ 知识图谱 · 智能体总线 · Temporal · 记忆管道 │\n├─────────────────────────────────────────────────────────┤\n│ Layer 2: 自托管服务栈（Docker） │\n│ SWAG/Authelia · LibreChat · 专用智能体 │\n│ qmd · CloudCLI · SearXNG · Grafana · NATS · Temporal │\n├─────────────────────────────────────────────────────────┤\n│ Layer 1: 主机与核心工具链 │\n│ Debian迷你主机 · Claude Desktop · MCP服务器 │\n│ Guacamole远程访问 │\n└─────────────────────────────────────────────────────────┘\n```\n\n### 第一层：主机与核心工具链\n\n基础层是一台专用的迷你PC（作者使用GMKTec K11，配备AMD Ryzen 9 8945HS、32GB内存、2TB NVMe），运行Debian 13系统和Claude Desktop。这一层的核心创新在于MCP（Model Context Protocol）服务器集成。\n\nMCP服务器为Claude提供了直接、结构化的基础设施访问能力——不是复制粘贴命令输出到聊天窗口，而是实时工具调用。项目集成了17个MCP服务器，涵盖：\n\n- **监控与可观测性**：Netdata（实时指标）、Grafana（仪表板与告警）、InfluxDB（时序数据）\n- **基础设施管理**：TrueNAS（存储管理）、Unraid（阵列状态）、Backrest（备份计划）\n- **开发与代码**：GitHub（仓库管理）、Desktop Commander（文件系统操作）\n- **搜索与信息**：SearXNG（私有搜索）、qmd（语义搜索）\n- **专用工具**：jobsearch-mcp（求职智能体）、pm2-mcp（进程管理）\n\n这种设计让AI真正理解你的基础设施。例如，你可以直接说"检查unraid上的Plex容器是否健康"，Claude已经知道unraid的IP地址、可用的监控工具以及Docker栈的组织方式。\n\n### 第二层：自托管服务栈\n\n第二层通过Docker Compose部署了一系列Web可访问的AI服务，让整个家庭或团队都能使用，而不仅仅是坐在Claude Desktop前的人。\n\n**LibreChat：多用户AI平台前端**\n\nLibreChat是整个平台的展示窗口。它不仅是一个聊天界面，还托管了专门构建的智能体，每个智能体都配置了特定的工具、上下文和用途。项目中的第一个示例是求职智能体，具备多站点职位抓取、简历评分和申请跟踪功能。\n\n**身份认证与网络安全**\n\n- **SWAG**：Nginx反向代理，提供Let's Encrypt通配符SSL证书\n- **Authelia**：单点登录认证网关，一次登录即可访问所有服务\n\n**可观测性栈**\n\n- **Grafana + InfluxDB + Loki**：本地智能体可观测性，追踪Claude Code会话指标、令牌使用、估算成本和LibreChat活动\n\n**专用服务组件**\n\n- **CloudCLI**：基于浏览器的Claude Code界面，支持文件浏览器、多会话标签页和推送通知\n- **SearXNG**：私有元搜索，聚合多引擎结果，无API密钥或按查询收费\n- **NATS + JetStream**：智能体事件总线，支持任务生命周期事件流和智能体间事件联邦\n- **Graphiti + Neo4j**：时序知识图谱，捕获基础设施拓扑（服务、主机、网络、智能体）\n- **Temporal**：持久化工作流引擎，支持容错多阶段工作流执行\n- **n8n**：工作流自动化，处理Webhook触发的工作流和事件路由\n\n### 第三层：多智能体Claude Code引擎\n\n最顶层是多智能体Claude Code引擎，具备作用域内存、后台作业和自动知识积累能力。\n\n**记忆系统**\n\n这是让整个平台随时间变得更智能的关键。Claude不会每次会话都从零开始，而是：\n\n- 加载基础设施上下文\n- 从过去的工作中回忆相关决策\n- 通过夜间记忆同步自动积累知识\n\n**CLAUDE.md层级结构**\n\n项目采用结构化的CLAUDE.md文件组织知识：\n\n- 基础设施文档（主机、网络、服务）\n- 用户偏好和配置文件\n- 项目指令和构建计划\n- 智能体专用上下文\n\n**智能体总线与协作**\n\n通过NATS JetStream实现智能体间通信，支持任务交接、审计请求和故障事件联邦。三个持久化流分别处理任务（30天）、智能体事件（7天）和智能体总线（30天，2分钟去重）。\n\n## 核心创新点\n\n### 持久化上下文系统\n\n项目的起点是一个简单的观察：Claude每次会话都问同样的问题。作者开始用markdown文件记录基础设施信息并作为上下文输入，这个上下文系统逐渐发展为结构化的仓库——配置文件、偏好设置、基础设施文档、项目指令——被称为"首要指令"。\n\n一旦Claude拥有了关于环境的持久上下文，交互方式就发生了质变。从每次解释自己的设置，变成可以直接说"检查atlas上过去一小时的CPU使用情况"，Claude已经知道如何查询Grafana、理解监控指标的含义。\n\n### 版本控制的基础设施\n\nAI能够触及的一切都在git版本控制中。这意味着：\n\n- 变更可审计、可回滚\n- 配置与代码同步演进\n- 多智能体协作时有单一事实来源\n\n### 模块化设计哲学\n\n整个系统采用模块化设计，你可以采用完整方案，也可以只取适合你的部分。系统奖励定制化——你越是根据自己的实际工作方式塑造它，它就越有用。\n\n每个组件都有独立的采用价值评级，文档中详细说明了：\n- 独立价值：不依赖其他层时的有用程度\n- 集成价值：与其他组件配合时的增益\n- 采用优先级：建议的实施顺序\n\n## 实际应用场景\n\n### 基础设施运维\n\n通过MCP集成，AI可以直接：\n- 查询Netdata获取任何被监控主机的实时指标（CPU、内存、磁盘、容器、告警）\n- 检查TrueNAS的数据集、存储池、快照状态\n- 管理Unraid的阵列状态、磁盘健康、Docker容器\n- 触发Backrest备份计划并获取操作历史\n\n### 开发工作流\n\n- 通过GitHub MCP管理跨多个账户的仓库、议题、PR\n- 使用语义搜索（qmd）在代码库和文档中查找信息\n- CloudCLI提供浏览器内的Claude Code界面，支持文件浏览和多会话\n\n### 专用智能体示例：求职助手\n\n项目包含一个完整的求职智能体实现（jobsearch-mcp v2），展示如何构建专用智能体：\n\n- **多源职位抓取**：支持USAJobs等招聘网站\n- **简历评分**：ATS兼容性评分\n- **申请跟踪**：完整的申请流程管理\n- **邮件提醒**：job-watcher自动发送职位更新\n- **简历定制**：五个专用工具（build_profile/save_profile/tailor_resume/get/delete）\n\n### 自主构建管道\n\n项目实现了端到端的自主构建管道：\n\n- **trigger-proxy**：n8n到RemoteTrigger的HTTP代理，支持OAuth自动刷新\n- **task-dispatcher**：审批Webhook + 死信队列\n- **8个智能体清单**：每个都有RemoteTrigger ID\n- **安全加固**：X-Trigger-Secret时序安全认证、凭证文件0600权限\n\n## 技术亮点\n\n### Ollama队列代理\n\nollama-queue-proxy是一个智能池管理器，为Ollama集群提供：\n\n- **三级优先级队列**：高/正常/低优先级\n- **客户端API密钥认证**：带优先级上限和并发限制\n- **模型感知路由**：自动路由到已加载目标模型的主机\n- **Valkey嵌入缓存**：重复RAG请求命中时跳过队列\n- **保持活跃注入**：防止冷加载延迟\n\n### 语义搜索架构\n\n- **qmd**：混合搜索（BM25 + 向量 + LLM重排序），本地GGUF模型嵌入，AMD iGPU通过Vulkan加速\n- **Hister**：基于浏览器的记忆搜索，覆盖Claude记忆语料库（约500个文件），支持语义搜索和Bleve全文关键词索引\n\n### 知识图谱\n\nGraphiti + Neo4j构建时序知识图谱，捕获基础设施拓扑的实体和关系，支持时间有效性追踪。由memory-flush（实时）和memory-sync（夜间）共同维护。\n\n## 部署与采用路径\n\n项目文档提供了详细的组件说明和采用优先级建议。对于想要逐步构建的用户，建议路径：\n\n1. **第一阶段**：Layer 1基础——专用主机 + Claude Desktop + 核心MCP服务器\n2. **第二阶段**：Layer 2核心——LibreChat + SWAG/Authelia + SearXNG\n3. **第三阶段**：可观测性——Grafana栈 + 监控集成\n4. **第四阶段**：高级功能——智能体总线、知识图谱、Temporal工作流\n\n即使只有Layer 1，一个运行Claude Desktop并集成MCP服务器的专用机器，相比在浏览器标签页中使用Claude也是重大升级。MCP集成本身——能够说"检查unraid的磁盘健康"或"查询Grafana获取atlas的CPU指标"——就改变了你与基础设施交互的方式。\n\n## 总结\n\nhomelab-agent 代表了个人AI基础设施构建的前沿实践。它展示了如何将大型语言模型从"对话工具"转变为"基础设施操作员"，通过持久化上下文、工具集成和多智能体协作，实现真正的智能化运维。\n\n对于希望构建私有化AI平台的技术爱好者、家庭实验室玩家，以及需要在本地环境中部署AI能力的企业用户，这个项目提供了宝贵的参考架构和实现细节。项目的模块化设计允许渐进式采用，而其丰富的文档和活跃的更新（CHANGELOG记录了完整的构建历史）使其成为一个可持续演进的学习资源。