FastAPI-GenAI 项目 Docker Compose 部署指南

项目概述

FastAPI-GenAI 是一个基于 FastAPI 框架构建的生成式 AI 应用开发模板，提供了完整的开发环境和生产部署方案。本文将详细介绍如何使用 Docker Compose 快速部署该项目的完整服务。

Docker Compose 核心优势

Docker Compose 是管理多容器应用的最佳工具之一，特别适合开发环境搭建和微服务架构部署。在 FastAPI-GenAI 项目中，它提供了以下优势：

1. 一键式环境搭建：无需手动配置各个服务
2. 服务隔离：每个组件运行在独立容器中
3. 版本控制：确保开发、测试和生产环境一致性
4. 资源管理：可轻松调整各服务资源分配

部署准备

在开始前，请确保系统已安装：

• Docker Engine 20.10.0+
• Docker Compose 2.0.0+

快速启动

执行以下命令构建并启动所有服务：

docker-compose up --build

如需后台运行，添加 -d 参数：

docker-compose up --build -d

服务架构详解

1. 核心应用服务

• FastAPI 应用：项目主服务，提供 RESTful API 接口
• Celery Worker：处理后台异步任务
• Redis：作为缓存和 Celery 任务队列的存储后端

2. 监控与可视化套件

• RedisInsight：Redis 图形化管理界面
• Prometheus：指标收集系统
• Grafana：数据可视化平台
• Loki + Promtail：日志聚合系统

服务访问信息

服务名称	访问地址	端口	说明
FastAPI	http://localhost:8002	8002	主应用 API 文档界面
RedisInsight	http://localhost:8001	8001	Redis 管理界面
Prometheus	http://localhost:9091	9091	指标监控系统
Grafana	http://localhost:3000	3000	数据可视化仪表盘
Loki	http://localhost:3100	3100	日志查询系统

默认 Grafana 登录凭证：

• 用户名：admin
• 密码：supersecurepassword

建议在生产环境中修改这些默认凭证，可通过修改 .env 文件或 Grafana 的配置实现。

进阶配置技巧

服务扩展

如需扩展 Celery Worker 数量，可执行：

docker-compose up --build -d --scale worker=3

环境变量定制

所有服务配置均可通过修改 .env 文件进行调整，包括：

• 服务端口映射
• 资源限制（CPU/内存）
• 认证凭证
• 日志级别

健康检查

项目已内置服务健康检查机制，可通过以下命令查看各容器状态：

docker-compose ps

常见问题排查

1. 端口冲突：检查本地 8001-8002、3000、9091、3100 端口是否被占用
2. 构建失败：确保网络通畅，Docker 有足够资源（建议至少 4GB 内存）
3. 服务启动顺序：Compose 文件中已配置依赖关系，无需手动干预

最佳实践建议

1. 开发环境：直接使用完整套件，便于调试和监控
2. 生产环境：根据实际需求裁剪不需要的服务，调整资源限制
3. 版本控制：将 docker-compose.yml 和 .env 文件纳入版本管理
4. 安全加固：务必修改所有默认密码和密钥

总结

通过 Docker Compose，FastAPI-GenAI 项目实现了开箱即用的开发体验和灵活的生产部署方案。这套编排配置不仅提供了完整的应用运行时环境，还集成了业界标准的监控工具链，为生成式 AI 应用的开发和运维提供了坚实基础。