Skip to Content
👋 欢迎使用 Build AI Template！ 了解详情

⚡ 快速开始

本指南将帮助您在 5 分钟内运行 Build AI Template，体验完整的 AI 应用功能


🚀 方式一：Docker 一键部署（推荐）

这是最简单快速的部署方式，适合快速体验和生产环境使用。

前置要求

  • Docker >= 26.0
  • Docker Compose >= 2.25

部署步骤

  1. 克隆项目
git clone https://github.com/open-v2ai/build-ai-template.git
cd build-ai-template/deploy/
  1. 配置环境变量
# 复制环境变量模板
cp .env.example .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
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_FROM=your-email@gmail.com
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
 
# 方式二：使用 Resend
# MAIL_SEND_METHOD=RESEND
# RESEND_API_KEY=re_your-resend-api-key
# RESEND_MAIL_FROM=your-email@your-domain.com
 
# Stripe 配置（必填，用于支付模块）
STRIPE_PUBLIC_KEY=pk-test-***
STRIPE_PRIVATE_KEY=sk-test-***
STRIPE_WEBHOOK_SECRET=whsec-***
 
# 安全配置（建议修改）
AUTH_SECRET_KEY=your-super-secret-key-here

  1. 打包镜像
make build-all
  1. 启动服务
# 一键启动所有服务
docker compose up -d
 
# 查看服务状态
docker compose ps
 
# 查看日志（可选）
docker compose logs -f
  1. 访问应用

🛠️ 方式二：开发环境运行

适合开发者进行功能开发和定制。

前置要求

  • 后端：Python >= 3.12，uv >= 0.6
  • 前端：Node.js >= 18.19，pnpm >= 10.11
  1. 准备数据库
# 克隆项目
git clone https://github.com/open-v2ai/build-ai-template.git
cd build-ai-template
 
# 启动 PostgreSQL（使用 Docker）
bash api/scripts/run_postgres.sh
 
# 启动 Redis（使用 Docker）
bash api/scripts/run_redis.sh
  1. 配置并运行后端
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
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_FROM=your-email@gmail.com
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
 
# 方式二：使用 Resend
# MAIL_SEND_METHOD=RESEND
# RESEND_API_KEY=re_your-resend-api-key
# RESEND_MAIL_FROM=your-email@your-domain.com
 
# Stripe 配置（必填，用于支付模块）
STRIPE_PUBLIC_KEY=pk-test-***
STRIPE_PRIVATE_KEY=sk-test-***
STRIPE_WEBHOOK_SECRET=whsec-***
 
# 运行数据库迁移（可选）
alembic upgrade head
 
# 启动开发服务器（端口 8000）
python -m app.main
  1. 配置支付模块
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
  1. 配置并运行应用前端
# 新开终端窗口
cd web/
 
# 安装依赖
pnpm install
 
# 配置环境变量
cp .env.example .env
vim .env
NEXT_PUBLIC_API_URL=http://localhost:8000

然后，启动开发服务器：

# 启动开发服务器（端口 3000）
pnpm dev
  1. 配置并运行文档前端
# 新开终端窗口
cd docs/
 
# 安装依赖
pnpm install
 
# 启动开发服务器（端口 4000）
pnpm dev
  1. 访问应用

🔧 环境变量配置详解

后端环境变量 (api/.env)


🤖 AI & Agent

大模型与 Agent 服务配置

AGENT_API_KEY - (必填) OpenAI 或兼容 API 的密钥
AGENT_BASE_URL - API 地址
AGENT_MODEL_NAME - 默认使用的模型名称

📧 邮件服务

用于发送登录/注册验证码

MAIL_SEND_METHOD - 邮件发送方式 (SMTP 或 RESEND)
SMTP 配置:
MAIL_USERNAME - SMTP 邮箱用户名
MAIL_PASSWORD - SMTP 邮箱密码或应用专用密码
MAIL_FROM - 发件人邮箱地址
MAIL_SERVER - SMTP 服务器地址
MAIL_PORT - SMTP 服务器端口
Resend 配置:
RESEND_API_KEY - Resend API Key
RESEND_MAIL_FROM - Resend 发件人邮箱

🗄️ 数据库

PostgreSQL 和 Redis 连接配置

PostgreSQL:
POSTGRES_HOST - 数据库主机
POSTGRES_PORT - 数据库端口
POSTGRES_USER - 数据库用户
POSTGRES_PASSWORD - 数据库密码
POSTGRES_DB - 数据库名称
Redis:
REDIS_HOST - Redis 主机
REDIS_PORT - Redis 端口
REDIS_USER - Redis 用户
REDIS_PASSWORD - Redis 密码
REDIS_DB - Redis 数据库

🔒 认证与安全

JWT 令牌和调试模式

AUTH_SECRET_KEY - (必填) 用于签发 JWT 的密钥，请务必修改
AUTH_ALGORITHM - 用于签发 JWT 的算法
AUTH_ACCESS_TOKEN_EXPIRE_MINUTES - Access Token 过期时间（分钟）
AUTH_REFRESH_TOKEN_EXPIRE_DAYS - Refresh Token 过期时间（天）
AUTH_IS_DEBUG - 是否开启认证调试模式
AUTH_DEBUG_CODE - 调试模式下的万能验证码

💳 支付与会员

Stripe 支付和会员等级配置

STRIPE_PRIVATE_KEY - Stripe 私钥
STRIPE_PUBLIC_KEY - Stripe 公钥
STRIPE_WEBHOOK_SECRET - Stripe Webhook 密钥
免费会员
MEMBERSHIP_FREE_NAME - 名称
MEMBERSHIP_FREE_DAILY_MESSAGE_LIMIT - 每日消息上限
MEMBERSHIP_FREE_DAILY_TOKEN_LIMIT - 每日 Token 上限
MEMBERSHIP_FREE_CONVERSATION_TURN_LIMIT - 对话轮次上限
MEMBERSHIP_FREE_PRICE - 价格
MEMBERSHIP_FREE_CURRENCY - 货币
MEMBERSHIP_FREE_DURATION_DAYS - 有效期(天)
MEMBERSHIP_FREE_DESCRIPTION - 描述
月度会员
MEMBERSHIP_MONTHLY_NAME - 名称
MEMBERSHIP_MONTHLY_DAILY_MESSAGE_LIMIT - 每日消息上限
MEMBERSHIP_MONTHLY_DAILY_TOKEN_LIMIT - 每日 Token 上限
MEMBERSHIP_MONTHLY_CONVERSATION_TURN_LIMIT - 对话轮次上限
MEMBERSHIP_MONTHLY_PRICE - 价格
MEMBERSHIP_MONTHLY_CURRENCY - 货币
MEMBERSHIP_MONTHLY_DURATION_DAYS - 有效期(天)
MEMBERSHIP_MONTHLY_DESCRIPTION - 描述
年度会员
MEMBERSHIP_YEARLY_NAME - 名称
MEMBERSHIP_YEARLY_DAILY_MESSAGE_LIMIT - 每日消息上限
MEMBERSHIP_YEARLY_DAILY_TOKEN_LIMIT - 每日 Token 上限
MEMBERSHIP_YEARLY_CONVERSATION_TURN_LIMIT - 对话轮次上限
MEMBERSHIP_YEARLY_PRICE - 价格
MEMBERSHIP_YEARLY_CURRENCY - 货币
MEMBERSHIP_YEARLY_DURATION_DAYS - 有效期(天)
MEMBERSHIP_YEARLY_DESCRIPTION - 描述

⚙️ 应用服务

API 服务本身的基础配置

ENV - 运行环境 (dev/test/prod)
API 配置:
API_HOST - 主机
API_PORT - 端口
API_NAME - 名称
API_VERSION - 版本
API_RELOAD - 是否自动重新加载

前端环境变量 (web/.env)

🖥️ 前端配置

前端开发所需的基本环境变量。

NEXT_PUBLIC_API_URL - 后端 API 的访问地址，用于前端请求数据。
NEXT_PUBLIC_APP_URL - (可选) 当前前端应用的主机名 URL。
NEXT_PUBLIC_DOCS_URL - (可选) 文档站点的访问地址。

✅ 验证部署

1. 检查服务状态

# Docker 部署
docker compose ps
 
# 开发环境
curl http://localhost:8000/health  # 后端健康检查
curl http://localhost:3000         # 前端访问

2. 测试核心功能

  1. 用户注册登录

    • 访问应用首页
    • 点击登录，输入邮箱
    • 检查邮箱验证码（或使用调试码 888888）

  2. AI 对话测试

    • 登录后创建新对话
    • 发送测试消息
    • 验证 AI 响应和流式显示

  3. 管理后台访问

    • 访问 /admin 路径
    • 查看用户管理、对话统计等功能

🚨 常见问题





🎯 下一步

恭喜！您已经成功部署了 Build AI Template。接下来您可以：

  1. 了解系统架构 - 深入理解项目的技术架构
  2. 用户使用指南 - 学习如何使用各项功能
  3. 管理员指南 - 掌握管理后台的使用方法
  4. 开发指南 - 开始定制和扩展功能
  5. 部署指南 - 了解生产环境部署最佳实践

如果遇到问题，请查看我们的 故障排除指南 或在 GitHub 上提交 Issue。