mirror of
https://github.com/lobehub/lobehub.git
synced 2026-09-20 04:56:13 +08:00
YuTengjing
191f3fe776
* 📝 docs: fix outdated content across the docs site Audited docs/ against the current codebase and fixed stale content that drifted after major refactors (Clerk/NextAuth → Better Auth, src/server → apps/server, src/{config,envs,locales} → packages/*, model-bank updates). - self-hosting/auth: mark removed NextAuth/Clerk pages with deprecation warnings; fix microsoft/zitadel alias claims and the Logto callback path - environment-variables & advanced: correct wrong defaults (S3_SET_ACL, AI_IMAGE_DEFAULT_IMAGE_NUM, index/proxy URLs), drop non-existent env vars and fictional feature flags, fix OIDC config guidance - development: update refactored paths, Better Auth, .mjs configs, remove the MSW section (msw is not a dependency) - providers & model examples: replace retired model ids with in-bank ones; fix comfyui frontmatter corruption - usage: rename Moderator→Orchestrator, GTD→Task, correct shortcut keys, channel capability tables, Feishu/Lark WebSocket mode - platform/migration: fix dead links, docker service name, npx/npm → bun EN and zh-CN pairs updated together. * 📝 docs: fix Logto callback path and AUTH_SECRET deprecation guidance - Revert Logto/Sealos callback URLs to /api/auth/callback/logto to match the runtime SSO redirectURI override - Narrow legacy auth Callout: AUTH_SECRET remains required for Better Auth; mark NEXT_AUTH_SECRET as deprecated in zh-CN * 📝 docs: refresh agent skills for locales, env, auth, and agentRun paths Align OSS agent guidance with post-refactor layout: - packages/locales/src/default + bun run i18n - packages/env/src for env schemas (@/envs alias) - spa-auth shell + src/routes/auth segments - chat agentRun/transports/hetero instead of aiChat * 📝 docs: document APP_URL as required for Better Auth base URL Self-hosted auth uses appEnv.APP_URL as baseURL, not request-header auto-detection. NEXT_PUBLIC_AUTH_URL remains deprecated. * 📝 docs: note self-host search provider setup for web search Built-in lobe-web-browsing needs no client plugin, but self-hosted servers still require SEARCH_PROVIDERS / SEARXNG_URL (default SearXNG). * 📝 docs: point feature guide welcome UI at AgentHome Opening message/questions on the agent chat page live in src/features/AgentHome, not Onboarding WelcomeMessage.
147 lines
6.7 KiB
Plaintext
147 lines
6.7 KiB
Plaintext
---
|
||
title: 架构设计
|
||
description: 深入了解 LobeHub 的架构设计，包括前端、后端、运行时和数据存储。
|
||
tags:
|
||
- LobeHub
|
||
- 架构设计
|
||
- Agent 平台
|
||
- Next.js
|
||
---
|
||
|
||
# 架构设计
|
||
|
||
LobeHub 是一个基于 Next.js 构建的开源 AI Agent 平台，使用户能够与 AI 进行自然语言交互、使用工具、管理知识库等。以下是 LobeHub 的架构设计概览。
|
||
|
||
## 应用架构概览
|
||
|
||
LobeHub 的整体架构由以下核心层组成：
|
||
|
||
```plaintext
|
||
+---------------------+--------------------------------------------------+
|
||
| Layer | Description |
|
||
+---------------------+--------------------------------------------------+
|
||
| Frontend | Next.js RSC + React Router DOM 混合路由 SPA |
|
||
| Backend API | RESTful WebAPI + tRPC Routers |
|
||
| Runtime | Model Runtime + Agent Runtime |
|
||
| Auth | Better Auth（邮箱密码 + SSO） |
|
||
| Data Storage | PostgreSQL + Redis + S3 |
|
||
| Marketplace | Agent 市场 + MCP 工具市场 |
|
||
+---------------------+--------------------------------------------------+
|
||
```
|
||
|
||
## 前端架构
|
||
|
||
前端采用 Next.js 框架，使用 **Next.js RSC + React Router DOM 混合路由**方案：Next.js App Router 处理服务端渲染页面（如认证页），React Router DOM 承载主应用 SPA。
|
||
|
||
| 路由方式 | 使用场景 | 位置 |
|
||
| ---------------------- | ---------------- | -------------------------- |
|
||
| **Next.js App Router** | 认证页、SSR、静态路由 | `src/app/(backend)/` |
|
||
| **React Router DOM** | 主聊天 SPA、Agent 界面 | `src/spa/` + `src/routes/` |
|
||
|
||
**为什么使用混合路由？** SSR 为认证页提供安全性、SEO 和静态页性能；SPA 为交互式聊天和 Agent 界面提供即时导航和响应式状态管理 —— 两者各取所长。
|
||
|
||
主要技术栈：
|
||
|
||
- **UI 组件**：`@lobehub/ui`、antd
|
||
- **CSS-in-JS**：antd-style
|
||
- **状态管理**：zustand（slice 模式）
|
||
- **数据请求**：SWR + tRPC
|
||
- **国际化**：react-i18next
|
||
|
||
**组件使用优先级**：项目组件（`src/components/`）→ `@lobehub/ui` → Ant Design（`antd`）。始终优先使用项目级组件以保持一致性。
|
||
|
||
前端代码按职责分层在 `src/` 目录下，详见 [目录架构](/zh/docs/development/basic/folder-structure)。
|
||
|
||
## 后端 API
|
||
|
||
后端提供两种 API 形式：
|
||
|
||
- **RESTful WebAPI**（`src/app/(backend)/webapi/`）：处理 chat 流式响应、TTS、文件服务等需要特殊处理的端点
|
||
- **tRPC Routers**（`apps/server/src/routers/`）：类型安全的主要业务路由，按运行时分组：
|
||
- `lambda/` — 主业务（agent、session、message、topic、file、knowledge、settings 等）
|
||
- `async/` — 耗时异步操作（文件处理、图像生成、RAG 评估）
|
||
- `tools/` — 工具调用（search、MCP、market）
|
||
- `mobile/` — 移动端专用
|
||
|
||
## Runtime
|
||
|
||
### Model Runtime
|
||
|
||
`@lobechat/model-runtime`（`packages/model-runtime/`）是 LLM API 适配层，抹平了 30+ 不同 AI Provider 之间的 API 差异（OpenAI、Anthropic、Google、Bedrock、Ollama 等），提供统一的调用接口。每个 Provider 有独立的适配器实现。它是无状态的，每次调用独立。
|
||
|
||
### Agent Runtime
|
||
|
||
`@lobechat/agent-runtime`（`packages/agent-runtime/`）是 Agent 编排引擎，位于 Model Runtime 之上，负责驱动多步 AI Agent 行为的完整生命周期：
|
||
|
||
- **Plan-Execute 循环**：核心状态机，循环执行 LLM 调用 → 工具执行 → 结果处理
|
||
- **工具调用与批量执行**：支持单工具和批量工具调用
|
||
- **Human-in-the-Loop**：安全检查、人工审批流程
|
||
- **上下文压缩**：管理上下文窗口
|
||
- **用量与成本追踪**：累计 token 用量和费用
|
||
- **多 Agent 协作**：`GroupOrchestrationRuntime` 支持 Supervisor + Executor 模式的多 Agent 编排
|
||
|
||
简言之：Model Runtime 解决 "如何与 LLM Provider 通信"，Agent Runtime 解决 "如何运行一个使用 LLM、工具、人工审批的完整 Agent"。
|
||
|
||
**Agent 执行流程：**
|
||
|
||
1. 解析用户输入
|
||
2. LLM 决策：直接回复还是调用工具
|
||
3. 执行工具（单工具或批量）
|
||
4. Human-in-the-Loop 人工审批（如需要）
|
||
5. 将执行结果反馈给 LLM
|
||
6. 循环直至生成最终回复
|
||
|
||
## 认证鉴权
|
||
|
||
LobeHub 使用 [Better Auth](https://www.better-auth.com/) 作为认证框架，支持：
|
||
|
||
- 邮箱 + 密码注册登录
|
||
- SSO 单点登录（GitHub、Google 等多种 OAuth Provider）
|
||
|
||
认证配置位于 `src/auth.ts`，相关路由在 `src/app/(backend)/api/` 下。
|
||
|
||
## 数据存储
|
||
|
||
```plaintext
|
||
+---------------+----------------------------------------------+
|
||
| Storage | Usage |
|
||
+---------------+----------------------------------------------+
|
||
| PostgreSQL | 主数据库，存储用户、会话、消息、Agent 配置等 |
|
||
| Redis | 缓存、会话状态、速率限制 |
|
||
| S3 | 文件存储（用户上传、图片、知识库文件等） |
|
||
+---------------+----------------------------------------------+
|
||
```
|
||
|
||
数据库使用 Drizzle ORM 操作，schema 定义在 `packages/database/src/schemas/`。
|
||
|
||
## 市场
|
||
|
||
- **Agent 市场**：提供各种场景的 AI Agent，用户可以发现、使用和分享 Agent
|
||
- **MCP 工具市场**：发现和集成 MCP 工具，扩展 Agent 的能力
|
||
|
||
## 性能优化
|
||
|
||
- **代码拆分**：基于路由的按需分块，保持初始包体积小
|
||
- **懒加载**：重型组件和路由按需加载
|
||
- **SWR 缓存**：客户端数据缓存并在后台自动重新验证
|
||
- **边缘缓存**：静态和可缓存响应分发至 CDN 边缘节点
|
||
- **流式响应**：聊天回复通过 SSE 增量流式传输，提升感知速度
|
||
- **虚拟滚动**：长消息列表和 Agent 列表使用虚拟滚动优化渲染
|
||
|
||
## 安全措施
|
||
|
||
- **CSRF 防护**：SameSite Cookie 和 Token 验证
|
||
- **XSS 防护**：Content Security Policy 请求头和输出内容净化
|
||
- **速率限制**：API 请求限流在边缘层执行
|
||
- **SSRF 防护**：插件和 MCP 调用的出站请求白名单
|
||
- **SQL 注入防护**：通过 Drizzle ORM 使用参数化查询
|
||
- **密钥管理**：API Key 和凭据以环境变量方式存储，绝不写入代码或客户端包
|
||
|
||
## 开发和部署
|
||
|
||
- **版本控制**：Git + GitHub，gitmoji commit 规范
|
||
- **代码质量**：ESLint、Stylelint、TypeScript 类型检查、循环依赖检测 (dpdm)、死代码检测 (knip)
|
||
- **测试**：Vitest 单元测试 + Cucumber/Playwright E2E 测试
|
||
- **CI/CD**：GitHub Actions 自动化测试、构建和发布
|
||
- **部署**：支持 Vercel、Docker、各大云平台自托管
|