Build AI Template 是一个面向开发者的开源 AI 应用模板，采用 FastAPI + Next.js 技术栈，集成主流 AI 平台，内置 用户管理、智能对话、会员支付 与 可视化管理后台，助力高效搭建现代化 AI 产品。
Important
🚀 快速开始：点击页面右上角的 Use this template 按钮创建您的新项目！
- 🚀 开箱即用：完整的 AI 应用解决方案，无需从零开始
- 🔧 高度可定制：模块化设计，轻松扩展和定制功能
- 🌍 多平台支持：集成 OpenAI、Dify、FastGPT、Coze 等主流 AI 平台
- 📱 现代化界面：基于 Shadcn UI 的美观响应式设计
- 🔒 企业级安全：完善的用户认证和权限管理
- 📊 数据洞察：详细的使用统计和管理后台
- 多平台支持：集成 OpenAI、Dify 等主流 AI 平台
- Agent 管理：可视化创建、编辑和管理多个 AI 助手
- 流式响应：支持打字机效果的实时流式对话
- 邮箱验证码登录：无需密码，安全便捷的邮箱验证登录
- 会员体系：支持免费版、月费版、年费版等多级会员
- 权限管理：用户和管理员角色分离
- 实时对话：流式响应展示 AI 思考过程
- 对话历史：完整的对话记录和管理
- 多轮对话：支持上下文连续对话
- 数据统计：用户、对话、消息等核心数据可视化
- 用户管理：用户查看、编辑、删除和权限管理
- Agent 管理：AI 助手的创建、配置和状态监控
- 多语言支持：完整的中英文国际化
- 响应式设计：完美适配桌面端和移动端
- 深色模式：支持明暗主题切换
- Docker 部署：完整的容器化部署方案
- 数据库迁移：Alembic 自动化数据库版本管理
- 反向代理：Nginx 负载均衡和静态文件服务
- 框架：FastAPI + Python 3.12
- 数据库：PostgreSQL + SQLModel + Alembic + Redis
- AI 集成：OpenAI API + 多平台 Agent 支持
- 认证：JWT + 邮箱验证码
- 包管理：uv
- 框架：Next.js 15.3 + React 19 + TypeScript
- UI 组件：Shadcn UI + Tailwind CSS
- 国际化：next-intl
- 状态管理：React Hooks
- 包管理：pnpm
- 容器化：Docker + Docker Compose
- 反向代理：Nginx
- 数据持久化：PostgreSQL + Redis 数据卷
Warning
最低系统要求：
- CPU：2 核
- 内存：4 GB
- 存储：20 GB
这是最简单快速的部署方式，适合快速体验和生产环境使用。
前置要求:
- Docker >= 26.0
- Docker Compose >= 2.25
部署步骤:
-
克隆项目
git clone https://github.com/open-v2ai/build-ai-template.git cd build-ai-template/deploy/ -
配置环境变量
# 复制环境变量模板 cp .env.example .env # 编辑 .env 文件，配置必需的环境变量 vim .env
必需配置项：
# AI 配置（必填） AGENT_API_KEY=sk-proj-*** AGENT_BASE_URL=https://api.openai.ai/v1/chat/completions AGENT_MODEL_NAME=gpt-4.1-mini # 邮件配置（必填，用于登录验证码） # 方式一：使用 SMTP MAIL_SEND_METHOD=SMTP [email protected] MAIL_PASSWORD=your-app-password [email protected] MAIL_SERVER=smtp.gmail.com MAIL_PORT=587 # 方式二：使用 Resend # MAIL_SEND_METHOD=RESEND # RESEND_API_KEY=re_your-resend-api-key # [email protected] # Stripe 配置（必填，用于支付模块） STRIPE_PUBLIC_KEY=pk-test-*** STRIPE_PRIVATE_KEY=sk-test-*** STRIPE_WEBHOOK_SECRET=whsec-*** # 安全配置（建议修改） AUTH_SECRET_KEY=your-super-secret-key-here
-
打包镜像
make build-all
-
启动服务
# 一键启动所有服务 docker compose up -d # 查看服务状态 docker compose ps # 查看日志（可选） docker compose logs -f
-
访问应用
- 用户界面: http://localhost:8081
- 管理后台: http://localhost:8081/admin
- API 文档: http://localhost:8081/v1/api/docs
- 项目文档: http://localhost:8082
适合开发者进行功能开发和定制。
前置要求:
- 后端：Python >= 3.12，uv >= 0.6
- 前端：Node.js >= 18.19，pnpm >= 10.11
运行步骤:
-
克隆仓库
git clone https://github.com/open-v2ai/build-ai-template.git cd build-ai-template -
运行数据库服务
# 运行 PostgreSQL bash api/scripts/run_postgres.sh # 运行 Redis bash api/scripts/run_redis.sh
-
配置并运行后端
依赖要求：Python >= 3.12，uv >= 0.6
cd api/ # 安装依赖 uv sync # 激活虚拟环境 source venv/bin/activate # Linux/macOS # 或 venv\Scripts\activate # Windows # 配置环境变量 cp .env.example .env # 编辑 .env 文件 vim .env # AI 配置（必填） AGENT_API_KEY=sk-proj-*** AGENT_BASE_URL=https://api.openai.ai/v1/chat/completions AGENT_MODEL_NAME=gpt-4.1-mini # 邮件配置（必填，用于登录验证码） # 方式一：使用 SMTP MAIL_SEND_METHOD=SMTP [email protected] MAIL_PASSWORD=your-app-password [email protected] MAIL_SERVER=smtp.gmail.com MAIL_PORT=587 # 方式二：使用 Resend # MAIL_SEND_METHOD=RESEND # RESEND_API_KEY=re_your-resend-api-key # [email protected] # Stripe 配置（必填，用于支付模块） STRIPE_PUBLIC_KEY=pk-test-*** STRIPE_PRIVATE_KEY=sk-test-*** STRIPE_WEBHOOK_SECRET=whsec-*** # 运行数据库迁移（可选） alembic upgrade head # 启动开发服务器（端口 8000） python -m app.main
-
配置支付模块
# 新开终端 cd api/ source venv/bin/activate # 登录 Stripe stripe login stripe listen --forward-to localhost:8000/api/v1/orders/stripe/webhook # 复制生成的 webhook 密钥到 .env 文件中 STRIPE_WEBHOOK_SECRET=whsec_cexxx
-
配置并运行前端
依赖要求：Node.js >= 18.19，pnpm >= 10.11
# 新开终端 cd web/ # 安装依赖 pnpm install # 配置环境变量 cp .env.example .env vim .env # 加入 API 地址 NEXT_PUBLIC_API_URL=http://localhost:8000 # 启动开发服务器（端口 3000） pnpm dev
-
访问应用
- 用户界面: http://localhost:3000
- 管理后台: http://localhost:3000/admin
- API 文档: http://localhost:3000/v1/api/docs
- 项目文档: http://localhost:4000
Note
- 测试环境邮件配置：可以设置
AUTH_IS_DEBUG=True和AUTH_DEBUG_CODE=888888，实现跳过邮件验证码直接登录或注册，便于本地开发和测试。 - 自动管理员设置：第一个通过邮箱验证注册的用户将自动成为管理员！
- 服务启动失败:
- 检查端口占用：Docker 部署确保 8081、8082 端口未被占用，开发环境执行确保 8000、3000、4000 端口未被占用。
- 检查 Docker：确保 Docker 服务正在运行。
- 查看日志：使用
docker compose logs -f查看错误信息。
- AGENT 响应失败:
- 检查 API Key：确保 AGENT API Key 有效且有余额。
- 检查网络：确保服务器可以访问 AGENT API。
- 检查模型：确认模型名称正确（如
gpt-4.1-mini）。
- 邮件发送失败:
- 云厂商封禁：大多数云厂商可能会封禁 SMTP 服务，可以使用 Resend 代替。
- 测试环境：可以设置
AUTH_IS_DEBUG=True和AUTH_DEBUG_CODE=888888，实现跳过邮件验证码直接登录，便于本地开发和测试。
- 支付模块配置失败:
- 检查 Stripe：确保 Stripe 服务正在运行。
- 检查 webhook 密钥：确保 webhook 密钥正确。
- 检查 Stripe 账户：确保 Stripe 账户正确。
graph TD
subgraph "用户层 (User Layer)"
U1["Web 用户界面<br>(Next.js)"]
U2["移动端适配<br>(Responsive)"]
U3["管理后台界面<br>(Admin Panel)"]
end
subgraph "网关层 (Gateway Layer)"
G["Nginx 反向代理 +<br>负载均衡"]
end
subgraph "应用层 (Application Layer)"
APP_F["前端应用 (Web)<br>Next.js, React, TypeScript"]
APP_B["后端 API (Backend)<br>FastAPI, Python, SQLModel"]
end
subgraph "数据层 (Data Layer)"
D_PG["PostgreSQL<br>主数据库"]
D_RD["Redis<br>缓存/会话"]
D_AGENT["AGENT 平台集成<br>OpenAI, 等."]
end
U1 --> G
U2 --> G
U3 --> G
G --> APP_F
G --> APP_B
APP_B --> D_PG
APP_B --> D_RD
APP_B --> D_AGENT
build-ai-template/
├── api/ # 后端 API 服务
│ ├── app/
│ │ ├── models/ # SQLModel 数据模型
│ │ ├── schemas/ # Pydantic 验证模式
│ │ ├── routers/v1/ # API 路由定义
│ │ ├── crud/ # 数据库 CRUD 操作
│ │ ├── services/ # 业务逻辑服务
│ │ ├── agents/ # AI Agent 集成
│ │ ├── core/ # 核心配置
│ │ └── utils/ # 工具模块
│ ├── alembic/ # 数据库迁移
│ └── pyproject.toml # Python 依赖配置
├── web/ # 前端 Web 应用
│ ├── app/ # Next.js App Router
│ ├── components/ # React 组件
│ │ ├── ui/ # Shadcn UI 基础组件
│ │ └── admin/ # 管理后台组件
│ ├── i18n/ # 国际化配置
│ └── package.json # 前端依赖配置
├── deploy/ # 生产环境部署
└── deploy-test/ # 测试环境部署
- 后端开发：在
api/app/中添加数据模型、API 路由和业务逻辑 - 数据库迁移：使用 Alembic 管理数据库版本
- 前端开发：在
web/components/中创建 React 组件 - 样式开发：使用 Tailwind CSS + Shadcn UI
- 国际化：在
web/app/messages/中添加中英文翻译 - 测试部署：使用
deploy-test/进行测试环境验证
我们欢迎对 Build AI Template 的贡献！更多信息请参阅我们的 CONTRIBUTING.md。
Build AI Template 采用 Apache License 2.0 许可证发布。