BuildingAI 项目结构文档

版本: 25.1.0
生成日期: 2024-12-10

📋 项目概述

BuildingAI 是一个企业级开源智能代理平台，专为 AI 开发者、AI 创业者和前瞻性组织设计。通过可视化配置界面（DIY），无需编码即可构建原生企业 AI 应用。

核心特性

AI 对话: 基于大语言模型的对话式 AI 和文本生成，支持多模态模型
AI 智能体: 创建具有记忆、目标和工具使用能力的智能体，实现自主任务执行
知识库: 从文档构建知识库，支持向量搜索和 RAG 增强生成
MCP 集成: 通过 SSE 和 Streamable HTTP 协议调用 MCP 工具
模型管理: 在统一 API 规范下集成主流大模型
扩展机制: 通过安装扩展来扩展系统能力和 AI 技能
计费与支付: 内置会员管理、计费和支付功能

🛠️ 技术栈

层级	技术	版本
后端框架	NestJS	11.x
ORM	TypeORM	0.3.x
数据库	PostgreSQL	17.x
缓存	Redis	8.x
前端框架	Vue.js	3.x
SSR/SSG	Nuxt.js	4.x
UI 组件	Nuxt UI	3.x
构建工具	Vite	7.x
Monorepo	Turborepo	2.x
包管理器	pnpm	10.x
语言	TypeScript	5.x
桌面应用	Tauri	-
进程管理	PM2	6.x

📁 目录结构

BuildingAI/
├── 📄 配置文件
│   ├── .env                    # 环境变量配置
│   ├── .env.example            # 环境变量示例
│   ├── package.json            # 根包配置
│   ├── pnpm-workspace.yaml     # pnpm 工作区配置
│   ├── turbo.json              # Turborepo 配置
│   ├── docker-compose.yml      # Docker 编排配置
│   └── ecosystem.config.js     # PM2 配置
│
├── 📦 packages/                # 核心包目录
│   ├── @buildingai/            # 共享库包
│   ├── api/                    # 后端 API 服务
│   ├── cli/                    # 命令行工具
│   ├── core/                   # 核心业务逻辑
│   ├── desktop/                # 桌面应用 (Tauri)
│   └── web/                    # 前端应用
│
├── 🔌 extensions/              # 扩展插件目录
│   └── buildingai-simple-blog/ # 示例博客扩展
│
├── 🐳 docker/                  # Docker 相关文件
│   ├── conf/                   # 配置文件
│   └── data/                   # 数据持久化
│
├── 📜 scripts/                 # 构建脚本
│   ├── copy-extension-build.mjs
│   ├── release.mjs
│   ├── sync-env.mjs
│   └── translate-i18n.mjs
│
├── 🖼️ assets/                  # 静态资源
├── 📂 public/                  # 公共静态文件
├── 📂 storage/                 # 存储目录
├── 📂 templates/               # 模板文件
└── 📂 logs/                    # 日志目录

📦 packages/@buildingai/ - 共享库包

共享库包提供了整个项目的基础设施和通用功能：

包名	说明
`ai-sdk`	AI SDK 封装，提供统一的 AI 模型调用接口
`base`	基础类和抽象层
`cache`	缓存服务封装 (Redis)
`config`	配置管理模块
`constants`	全局常量定义
`db`	数据库实体和仓库层
`decorators`	自定义装饰器
`di`	依赖注入工具
`dict`	字典数据管理
`dto`	数据传输对象定义
`errors`	统一错误处理
`eslint-config`	ESLint 共享配置
`extension-sdk`	扩展开发 SDK
`logger`	日志服务
`pipe`	NestJS 管道
`types`	TypeScript 类型定义
`typescript-config`	TypeScript 共享配置
`upgrade`	版本升级工具
`utils`	通用工具函数
`wechat-sdk`	微信 SDK 封装

🖥️ packages/api/ - 后端 API 服务

基于 NestJS 11.x 构建的后端服务，提供 RESTful API。

目录结构

packages/api/
├── src/
│   ├── main.ts                 # 应用入口
│   ├── assets/                 # 静态资源
│   ├── common/                 # 通用模块
│   ├── core/                   # 核心配置
│   └── modules/                # 业务模块
│       ├── ai/                 # AI 相关模块
│       │   ├── agent/          # 智能体管理
│       │   ├── chat/           # 对话管理
│       │   ├── datasets/       # 数据集/知识库
│       │   ├── mcp/            # MCP 工具集成
│       │   ├── model/          # 模型管理
│       │   ├── provider/       # 模型提供商
│       │   └── secret/         # 密钥管理
│       ├── analyse/            # 数据分析
│       ├── auth/               # 认证授权
│       ├── channel/            # 渠道管理
│       ├── config/             # 系统配置
│       ├── decorate/           # 装修/页面配置
│       ├── extension/          # 扩展管理
│       ├── finance/            # 财务管理
│       ├── health/             # 健康检查
│       ├── membership/         # 会员管理
│       ├── menu/               # 菜单管理
│       ├── pay/                # 支付模块
│       ├── permission/         # 权限管理
│       ├── pm2/                # PM2 管理
│       ├── recharge/           # 充值模块
│       ├── role/               # 角色管理
│       ├── schedule/           # 定时任务
│       ├── system/             # 系统管理
│       ├── tag/                # 标签管理
│       ├── upload/             # 文件上传
│       └── user/               # 用户管理

主要依赖

@nestjs/* - NestJS 核心模块
typeorm - ORM 框架
bullmq - 任务队列
bcryptjs - 密码加密
openai - OpenAI SDK

🌐 packages/web/ - 前端应用

基于 Nuxt 4.x 和 Vue 3.x 构建的前端应用。

目录结构

packages/web/
├── @buildingai/                # 前端共享库
│   ├── designer/               # 可视化设计器
│   ├── hooks/                  # Vue Composables
│   ├── http/                   # HTTP 请求封装
│   ├── i18n-config/            # 国际化配置
│   ├── layouts/                # 布局组件
│   ├── nuxt/                   # Nuxt 模块配置
│   ├── service/                # 业务服务层
│   ├── stores/                 # Pinia 状态管理
│   ├── storybook/              # Storybook 配置
│   ├── ui/                     # UI 组件库
│   └── web-config/             # Web 配置
│
└── buildingai-ui/              # 主前端应用
    ├── app/
    │   ├── components/         # 组件
    │   ├── i18n/               # 国际化文件
    │   ├── layouts/            # 布局
    │   ├── middleware/         # 中间件
    │   ├── pages/              # 页面路由
    │   │   ├── console/        # 管理后台
    │   │   │   ├── ai/         # AI 管理
    │   │   │   ├── dashboard.vue
    │   │   │   ├── decorate/   # 页面装修
    │   │   │   ├── financial/  # 财务管理
    │   │   │   ├── membership/ # 会员管理
    │   │   │   ├── order/      # 订单管理
    │   │   │   ├── plugins/    # 插件管理
    │   │   │   ├── role/       # 角色管理
    │   │   │   ├── system-setting/ # 系统设置
    │   │   │   └── user/       # 用户管理
    │   │   ├── chat/           # 对话页面
    │   │   ├── login/          # 登录页面
    │   │   ├── profile/        # 个人中心
    │   │   ├── install/        # 安装向导
    │   │   └── public/         # 公开页面
    │   ├── stores/             # 状态管理
    │   ├── types/              # 类型定义
    │   └── utils/              # 工具函数
    ├── modules/                # Nuxt 模块
    ├── public/                 # 静态资源
    └── server/                 # 服务端代码

主要依赖

nuxt - SSR/SSG 框架
@nuxt/ui - UI 组件库
pinia - 状态管理
@vueuse/* - Vue 工具集
echarts - 图表库
tiptap - 富文本编辑器

⚙️ packages/core/ - 核心业务逻辑

提供可复用的核心业务模块：

packages/core/src/
├── @nestjs/                    # NestJS 扩展
├── decorators/                 # 装饰器
├── interfaces/                 # 接口定义
├── modules/
│   ├── billing/                # 计费模块
│   ├── extension/              # 扩展模块
│   ├── queue/                  # 队列模块
│   ├── secret/                 # 密钥模块
│   └── upload/                 # 上传模块
└── services/                   # 服务层

🔧 packages/cli/ - 命令行工具

提供项目管理的 CLI 工具：

bash

# 可用命令
pnpm buildingai <command>

# PM2 相关命令
pnpm pm2:start      # 启动服务
pnpm pm2:stop       # 停止服务
pnpm pm2:restart    # 重启服务
pnpm pm2:status     # 查看状态
pnpm pm2:logs       # 查看日志
pnpm pm2:monitor    # 监控面板

# 更新命令
pnpm bd:update      # 更新项目
pnpm bd:update-git  # 从 Git 更新

🖥️ packages/desktop/ - 桌面应用

基于 Tauri 构建的跨平台桌面应用：

packages/desktop/
├── src-tauri/                  # Tauri 源码 (Rust)
├── scripts/                    # 构建脚本
├── README.md                   # 英文文档
└── README.zh-CN.md             # 中文文档

🔌 extensions/ - 扩展系统

扩展系统允许开发者扩展平台功能：

扩展结构示例

extensions/buildingai-simple-blog/
├── manifest.json               # 扩展清单
├── package.json                # 包配置
├── src/
│   ├── api/                    # 后端 API
│   └── web/                    # 前端页面
└── build/                      # 构建输出

扩展开发

扩展可以使用以下共享包：

@buildingai/extension-sdk - 扩展开发 SDK
@buildingai/core - 核心功能
@buildingai/db - 数据库访问
@buildingai/ui - UI 组件

🐳 Docker 部署

服务组成

服务	镜像	端口	说明
`nodejs`	node:22.20.0	4090	主应用服务
`postgres`	postgres:17.6	5432	数据库
`redis`	redis:8.2.2	6379	缓存

快速启动

bash

# 复制环境变量
cp .env.example .env

# 启动服务
docker compose up -d

# 访问安装向导
# http://localhost:4090/install

更新项目

针对使用 Docker Compose 部署的环境（包括宝塔 Docker 方式），更新步骤如下：

进入项目目录 （请根据实际安装路径调整）
bash
```
cd /www/wwwroot/buildingai
```
1

拉取最新代码

bash

git pull
# 如果有本地修改冲突，可尝试重置：git reset --hard

拉取最新镜像
bash
```
docker compose pull
```
1
重启容器服务 此命令会重建容器并启动服务，启动过程会自动执行构建（可能需要几分钟）。
bash
```
docker compose up -d
```
1

处理 Git 更新冲突

如果执行 git pull 时提示冲突（例如 error: Your local changes...），请根据情况选择以下方法：

方法一：强制覆盖（推荐）

这会丢弃服务器上所有未提交的修改，将代码重置为远程仓库的最新状态。

bash

# 1. 重置所有文件到最新状态
git reset --hard  

- 这个命令会将当前分支的HEAD重置到当前分支的最新提交
- 它不会与远程仓库进行任何同步
- 如果您的本地已经落后于远程仓库，这个命令不会获取最新的远程更改
- 它只会丢弃您本地的未提交更改，但不会获取远程的新代码

# git reset --hard origin/master

- 这个命令会将当前分支的HEAD重置到远程仓库(origin)的master分支的最新提交
- 它会强制使您的本地分支与远程master分支完全一致
- 这会丢弃所有本地提交和未提交的更改
- 即使您的本地落后于远程，这个命令也会使您的本地与远程完全同步

# 2. 拉取最新代码
git pull

# 3. 重启容器（会自动重新构建）
docker compose up -d

方法二：保留修改（仅当您修改了源码想保留时）

bash

# 1. 暂存您的修改
git stash

# 2. 拉取最新代码
git pull

# 3. 恢复您的修改（可能会有冲突需要手动解决）
git stash pop

# 4. 重启容器
docker compose up -d

📜 NPM Scripts

开发命令

bash

pnpm dev              # 启动所有开发服务
pnpm dev:api          # 启动后端开发服务
pnpm dev:web          # 启动前端开发服务
pnpm dev:desktop      # 启动桌面应用开发

构建命令

bash

pnpm build            # 构建所有包
pnpm build:api        # 构建后端
pnpm build:web        # 构建前端
pnpm build:desktop    # 构建桌面应用

代码质量

bash

pnpm lint             # 代码检查
pnpm lint:fix         # 自动修复
pnpm format           # 代码格式化
pnpm typecheck        # 类型检查

其他命令

bash

pnpm clean            # 清理构建产物
pnpm sync-env         # 同步环境变量
pnpm start            # 生产环境启动

🔐 环境变量

主要环境变量配置（参考 .env.example）：

变量	说明	默认值
`APP_NAME`	应用名称	BuildingAI
`APP_DOMAIN`	应用域名	localhost
`SERVER_PORT`	服务端口	4090
`JWT_SECRET`	JWT 密钥	-
`DB_HOST`	数据库主机	localhost
`DB_PORT`	数据库端口	5432
`DB_DATABASE`	数据库名	buildingai
`REDIS_HOST`	Redis 主机	localhost
`REDIS_PORT`	Redis 端口	6379

📊 系统要求

最低配置

CPU: ≥ 2 核
内存: ≥ 4 GB RAM
存储: ≥ 5 GB 可用空间
Node.js: 22.20.x (< 23)

🖼️ Logo 资源路径

主要 Logo 文件

路径	说明
`assets/logo.png`	项目主 Logo
`packages/web/buildingai-ui/public/logo.svg`	前端 Logo (SVG)
`packages/web/buildingai-ui/public/logo-full.svg`	前端完整 Logo (SVG)
`public/web/logo.svg`	构建输出 Logo
`public/web/logo-full.svg`	构建输出完整 Logo

Favicon 图标

路径	说明
`packages/web/buildingai-ui/public/favicon.ico`	网站图标
`packages/web/buildingai-ui/public/maskable-icon.png`	PWA 可遮罩图标
`public/web/favicon.ico`	构建输出图标

桌面应用图标 (Tauri)

路径	说明
`packages/desktop/src-tauri/icons/icon.ico`	Windows 图标
`packages/desktop/src-tauri/icons/icon.icns`	macOS 图标
`packages/desktop/src-tauri/icons/32x32.png`	32x32 PNG
`packages/desktop/src-tauri/icons/128x128.png`	128x128 PNG
`packages/desktop/src-tauri/icons/128x128@2x.png`	128x128 @2x PNG

Logo 组件

路径	说明
`packages/web/@buildingai/layouts/src/console/components/site-logo.vue`	后台 Logo 组件
`packages/web/@buildingai/layouts/src/web/components/web-site-logo.vue`	前台 Logo 组件

BuildingAI 项目结构文档 ​

📋 项目概述 ​

核心特性 ​

🛠️ 技术栈 ​

📁 目录结构 ​

📦 packages/@buildingai/ - 共享库包 ​

🖥️ packages/api/ - 后端 API 服务 ​

目录结构 ​

主要依赖 ​

🌐 packages/web/ - 前端应用 ​

目录结构 ​

主要依赖 ​

⚙️ packages/core/ - 核心业务逻辑 ​

🔧 packages/cli/ - 命令行工具 ​

🖥️ packages/desktop/ - 桌面应用 ​

🔌 extensions/ - 扩展系统 ​

扩展结构示例 ​

扩展开发 ​

🐳 Docker 部署 ​

服务组成 ​

快速启动 ​

更新项目 ​

处理 Git 更新冲突 ​

📜 NPM Scripts ​

开发命令 ​

构建命令 ​

代码质量 ​

其他命令 ​

🔐 环境变量 ​

📊 系统要求 ​

最低配置 ​

推荐配置 ​

🖼️ Logo 资源路径 ​

主要 Logo 文件 ​

Favicon 图标 ​

桌面应用图标 (Tauri) ​

Logo 组件 ​

BuildingAI 项目结构文档

📋 项目概述

核心特性

🛠️ 技术栈

📁 目录结构

📦 packages/@buildingai/ - 共享库包

🖥️ packages/api/ - 后端 API 服务

目录结构

主要依赖

🌐 packages/web/ - 前端应用

目录结构

主要依赖

⚙️ packages/core/ - 核心业务逻辑

🔧 packages/cli/ - 命令行工具

🖥️ packages/desktop/ - 桌面应用

🔌 extensions/ - 扩展系统

扩展结构示例

扩展开发

🐳 Docker 部署

服务组成

快速启动

更新项目

处理 Git 更新冲突

📜 NPM Scripts

开发命令

构建命令

代码质量

其他命令

🔐 环境变量

📊 系统要求

最低配置

推荐配置

🖼️ Logo 资源路径

主要 Logo 文件

Favicon 图标

桌面应用图标 (Tauri)

Logo 组件