生产环境部署指南

本指南详细介绍了如何使用 Docker Compose 和 Nginx 在生产服务器上部署 Build AI Template。这是我们推荐的用于生产环境的部署方法，因为它提供了最佳的性能、稳定性和可管理性。

系统架构概览

生产部署架构包含以下几个核心服务，它们都作为独立的 Docker 容器运行，并通过 Docker 网络进行通信：

Nginx: 作为反向代理和流量入口。它接收所有外部 HTTP 请求，并根据 URL 路径将流量转发到前端（Next.js）或后端（FastAPI）服务。
Web (Next.js): 前端应用服务器，负责渲染用户界面。
API (FastAPI): 后端应用服务器，处理所有业务逻辑和 API 请求。
PostgreSQL: 主数据库，用于持久化存储所有核心数据，如用户、对话和消息。
Redis: 缓存和消息队列，用于存储会话、缓存常用数据和处理后台任务。

Deployment Architecture Diagram （注：此处应有一张架构图）

您需要一台满足以下基本要求的服务器：

通过 SSH 连接到您的服务器，然后执行以下命令：


# 克隆项目代码
git clone https://github.com/open-v2ai/build-ai-template.git
 
# 进入生产部署目录
cd build-ai-template/deploy
 
# 从模板创建环境变量文件
cp .env.example .env

现在，使用您喜欢的编辑器（如 nano 或 vim）编辑 .env 文件：


nano .env

在生产环境中，必须修改以下变量以确保安全：

将 ENV 设置为 prod 以禁用调试功能。

配置完成后，您可以使用 docker compose 命令来构建和启动所有服务。


# 构建镜像并以分离模式（-d）启动所有容器
docker compose up --build -d

该命令会：

您可以使用以下命令检查所有服务的状态：


docker compose ps

如果所有服务的 Status 都显示为 running 或 healthy，则表示部署成功。

DNS 配置: 将您的域名（例如 app.yourdomain.com）的 A 记录指向您服务器的 IP 地址。
防火墙: 确保您服务器的防火墙允许 HTTP (80) 和 HTTPS (443) 的入站流量。
启用 HTTPS (推荐): 我们强烈建议使用 Certbot 来为您的 Nginx 服务自动获取和续订免费的 Let’s Encrypt SSL 证书。
- 在服务器上安装 Certbot。
- 运行 sudo certbot --nginx 并按照提示操作，为您的域名启用 HTTPS。Certbot 会自动修改您的 Nginx 配置。

要实时查看所有服务的日志，请使用：


docker compose logs -f

如果您只想查看特定服务的日志（例如 api），可以指定服务名称：


docker compose logs -f api


# 停止所有服务
docker compose down
 
# 重新启动服务
docker compose up -d

当您拉取了最新的代码后，需要重建镜像并重启服务以应用更新：


# 拉取最新代码
git pull origin main
 
# 进入部署目录
cd deploy
 
# 重建镜像并重启服务
docker compose up --build -d

PostgreSQL: 数据库的持久化数据存储在 deploy/volumes/db/data 目录中。您应该定期备份此目录。
Redis: Redis 数据存储在 deploy/volumes/redis/data。通常，Redis 中的数据是易失的缓存，但如果用作持久化存储，也应进行备份。

Nginx 作为反向代理，其配置文件 deploy/nginx/default.conf 定义了流量的路由规则：

这种配置实现了前后端的解耦，并允许它们在同一个域名下提供服务。