mirror of
https://github.com/lobehub/lobehub
synced 2026-04-21 17:47:27 +00:00
338df4baf9
* update e2e test * 📝 docs: Update src directory structure to be more comprehensive - Add missing directories: business, const, envs, helpers, tools - Add missing root files: auth.ts, instrumentation.ts, instrumentation.node.ts, proxy.ts - Update descriptions to be more accurate - Sync changes across English and Chinese documentation Fixes #9521
113 lines
5.2 KiB
Text
113 lines
5.2 KiB
Text
---
|
||
title: 目录架构
|
||
description: 深入了解 LobeHub 的文件夹目录架构及其功能模块。
|
||
tags:
|
||
- LobeHub
|
||
- 目录架构
|
||
- Next.js
|
||
- API路由
|
||
- 前端开发
|
||
---
|
||
|
||
# 目录架构
|
||
|
||
LobeHub 的文件夹目录架构如下：
|
||
|
||
```bash
|
||
src
|
||
├── app # Next.js App Router 实现，包含路由组和 API 路由
|
||
├── business # 业务逻辑模块（客户端和服务端）
|
||
├── components # 可复用的 UI 组件
|
||
├── config # 应用的配置文件，包含客户端环境变量与服务端环境变量
|
||
├── const # 应用常量和枚举
|
||
├── envs # 环境变量定义和校验（分析、认证、LLM 等）
|
||
├── features # 与业务功能相关的功能模块，如 Agent 设置、插件开发弹窗等
|
||
├── helpers # 工具辅助函数，用于工具工程、占位符解析等
|
||
├── hooks # 全应用复用自定义的工具 Hooks
|
||
├── layout # 应用的布局组件，如导航栏、侧边栏等
|
||
├── libs # 第三方集成（分析、OIDC 等）
|
||
├── locales # 国际化的语言文件
|
||
├── server # 服务端模块和服务
|
||
├── services # 封装的后端服务接口，如 HTTP 请求
|
||
├── store # 用于状态管理的 zustand store
|
||
├── styles # 全局样式和 CSS-in-JS 配置
|
||
├── tools # 内置工具（artifacts、inspectors、interventions 等）
|
||
├── types # TypeScript 的类型定义文件
|
||
├── utils # 通用的工具函数
|
||
├── auth.ts # 认证配置（Better Auth）
|
||
├── instrumentation.ts # 应用监控和遥测设置
|
||
├── instrumentation.node.ts # Node.js 专用的 instrumentation
|
||
└── proxy.ts # Next.js 中间件代理配置
|
||
```
|
||
|
||
## app
|
||
|
||
`app` 目录遵循 Next.js 13+ App Router 约定，采用复杂的架构，使用 [路由组](https://nextjs.org/docs/app/building-your-application/routing/route-groups) 来组织后端服务、平台变体和应用路由：
|
||
|
||
```bash
|
||
app
|
||
├── (backend)/ # 后端 API 路由和服务
|
||
│ ├── api/ # REST API 端点
|
||
│ │ ├── auth/ # 身份验证路由
|
||
│ │ └── webhooks/ # Webhook 处理器
|
||
│ ├── middleware/ # 请求中间件
|
||
│ ├── oidc/ # OpenID Connect 路由
|
||
│ ├── trpc/ # tRPC API 端点
|
||
│ │ ├── async/ # 异步 tRPC 路由
|
||
│ │ ├── desktop/ # 桌面端专用 tRPC 路由
|
||
│ │ ├── edge/ # Edge 运行时 tRPC 路由
|
||
│ │ ├── lambda/ # Lambda tRPC 路由
|
||
│ │ └── tools/ # 工具 tRPC 路由
|
||
│ └── webapi/ # Web API 端点
|
||
│ ├── chat/ # 聊天相关 API
|
||
│ ├── models/ # 模型管理 API
|
||
│ ├── tts/ # 文本转语音 API
|
||
│ └── ...
|
||
├── [variants]/ # 平台和设备变体
|
||
│ ├── (auth)/ # 身份验证页面
|
||
│ │ ├── login/
|
||
│ │ └── signup/
|
||
│ ├── (main)/ # 主应用路由
|
||
│ │ ├── (mobile)/ # 移动端专用路由
|
||
│ │ │ └── me/ # 移动端个人资料页面
|
||
│ │ ├── _layout/ # 布局组件
|
||
│ │ ├── chat/ # 聊天界面
|
||
│ │ ├── discover/ # 发现页面
|
||
│ │ ├── files/ # 文件管理
|
||
│ │ ├── image/ # 图像生成
|
||
│ │ ├── profile/ # 用户资料
|
||
│ │ ├── repos/ # 仓库管理
|
||
│ │ └── settings/ # 应用设置
|
||
│ └── @modal/ # 并行模态框路由
|
||
│ ├── (.)changelog/
|
||
│ └── _layout/
|
||
├── desktop/ # 桌面端专用路由
|
||
│ └── devtools/
|
||
├── manifest.ts # PWA 清单
|
||
├── robots.tsx # Robots.txt 生成
|
||
├── sitemap.tsx # 站点地图生成
|
||
└── sw.ts # Service Worker
|
||
```
|
||
|
||
### 架构说明
|
||
|
||
**路由组：**
|
||
|
||
- `(backend)` - 包含所有服务端 API 路由、中间件和后端服务
|
||
- `[variants]` - 处理不同平台变体和主应用页面的动态路由组
|
||
- `@modal` - 使用 Next.js 并行路由的模态框对话框并行路由
|
||
|
||
**平台组织：**
|
||
|
||
- 架构通过路由组织支持多个平台（Web、桌面端、移动端）
|
||
- 桌面端专用路由位于 `desktop/` 目录中
|
||
- 移动端专用路由组织在 `(main)/(mobile)/` 下
|
||
- 共享布局和组件位于 `_layout/` 目录中
|
||
|
||
**API 架构：**
|
||
|
||
- `(backend)/api/` 和 `(backend)/webapi/` 中的 REST API
|
||
- 按运行时环境组织的 tRPC 端点（edge、lambda、async、desktop）
|
||
- 专用路由组中的身份验证和 OIDC 处理
|
||
|
||
这种架构在保持不同部署目标和运行时环境灵活性的同时，提供了清晰的关注点分离。
|