Initial commit: 国土空间规划课程智能体 v1.0
单容器 Docker 架构的国土空间规划课程智能问答系统，集成 FastAPI 后端与 Next.js 前端。 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,291 @@
|
||||
# 国土空间规划课程智能体 - Docker单容器版本
|
||||
|
||||
一个基于大模型的智能问答系统，专门为国土空间规划课程设计。本版本将所有服务整合到单个Docker容器中，简化部署和管理。
|
||||
|
||||
## 🎯 项目特色
|
||||
|
||||
- **单容器架构**: 前端和后端服务整合在一个容器中，使用supervisor管理进程
|
||||
- **AI驱动**: 集成硅基流动大模型和LangGraph工作流
|
||||
- **RAG增强**: 基于Chroma向量数据库的智能检索
|
||||
- **响应式设计**: 完美适配手机、平板、桌面设备
|
||||
- **现代化技术栈**: Next.js 15 + React 19 + FastAPI + Python 3.12
|
||||
|
||||
## 🏗️ 技术架构
|
||||
|
||||
### 单容器架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Docker Container │
|
||||
│ ┌─────────────┐ ┌──────────────┐ │
|
||||
│ │ Backend │ │ Frontend │ │
|
||||
│ │ FastAPI │ │ Next.js │ │
|
||||
│ │ :8000 │ │ :8001 │ │
|
||||
│ └─────────────┘ └──────────────┘ │
|
||||
│ │ │ │
|
||||
│ └──────┬─────────┘ │
|
||||
│ Supervisor │
|
||||
└─────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ PostgreSQL │
|
||||
│ Database │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
### 技术栈
|
||||
|
||||
**后端**:
|
||||
- FastAPI + Uvicorn
|
||||
- LangChain + LangGraph
|
||||
- 硅基流动API (Qwen3-30B)
|
||||
- Chroma向量数据库
|
||||
- PostgreSQL
|
||||
|
||||
**前端**:
|
||||
- Next.js 15 (App Router)
|
||||
- React 19
|
||||
- TypeScript
|
||||
- TailwindCSS + shadcn/ui
|
||||
|
||||
## 📁 项目结构
|
||||
|
||||
```
|
||||
course_Agent/
|
||||
├── backend/ # Python后端代码
|
||||
│ ├── src/ # 源代码
|
||||
│ ├── main.py # 应用入口
|
||||
│ ├── pyproject.toml # 依赖配置
|
||||
│ └── migrations/ # 数据库迁移
|
||||
├── web/ # Next.js前端代码
|
||||
│ ├── src/ # 源代码
|
||||
│ ├── public/ # 静态资源
|
||||
│ └── package.json # 依赖配置
|
||||
├── docker/ # Docker相关文件
|
||||
│ ├── supervisord.conf # Supervisor配置
|
||||
│ └── start.sh # 启动脚本
|
||||
├── data/ # 数据目录（挂载卷）
|
||||
├── vector_store/ # 向量数据库（挂载卷）
|
||||
├── uploads/ # 上传文件（挂载卷）
|
||||
├── logs/ # 日志文件（挂载卷）
|
||||
├── generated_images/ # 生成的图像（挂载卷）
|
||||
├── Dockerfile # Docker构建文件
|
||||
├── docker-compose.yml # Docker Compose配置
|
||||
└── README.md # 本文件
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 前置要求
|
||||
|
||||
- Docker 20.10+
|
||||
- Docker Compose 2.0+
|
||||
|
||||
### 1. 克隆项目
|
||||
|
||||
```bash
|
||||
cd course_Agent
|
||||
```
|
||||
|
||||
### 2. 配置环境变量
|
||||
|
||||
复制环境变量模板：
|
||||
|
||||
```bash
|
||||
cp env.example .env
|
||||
```
|
||||
|
||||
编辑 `.env` 文件，配置必要的参数（API密钥、数据库密码等）。
|
||||
|
||||
### 3. 启动服务
|
||||
|
||||
```bash
|
||||
# 构建并启动所有服务
|
||||
docker-compose up -d
|
||||
|
||||
# 查看日志
|
||||
docker-compose logs -f
|
||||
|
||||
# 查看服务状态
|
||||
docker-compose ps
|
||||
```
|
||||
|
||||
### 4. 访问应用
|
||||
|
||||
- **前端应用**: http://localhost:8001
|
||||
- **后端API**: http://localhost:8000
|
||||
- **API文档**: http://localhost:8000/docs
|
||||
|
||||
### 5. 停止服务
|
||||
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
## 🔧 服务管理
|
||||
|
||||
### 查看日志
|
||||
|
||||
```bash
|
||||
# 查看所有服务日志
|
||||
docker-compose logs -f
|
||||
|
||||
# 查看特定服务日志
|
||||
docker-compose logs -f app
|
||||
docker-compose logs -f db
|
||||
```
|
||||
|
||||
### 重启服务
|
||||
|
||||
```bash
|
||||
# 重启所有服务
|
||||
docker-compose restart
|
||||
|
||||
# 重启特定服务
|
||||
docker-compose restart app
|
||||
```
|
||||
|
||||
### 进入容器
|
||||
|
||||
```bash
|
||||
# 进入应用容器
|
||||
docker-compose exec app bash
|
||||
|
||||
# 在容器内查看进程状态
|
||||
supervisorctl status
|
||||
```
|
||||
|
||||
### 数据库操作
|
||||
|
||||
```bash
|
||||
# 进入数据库容器
|
||||
docker-compose exec db psql -U user -d course_agent_db
|
||||
|
||||
# 备份数据库
|
||||
docker-compose exec db pg_dump -U user course_agent_db > backup.sql
|
||||
|
||||
# 恢复数据库
|
||||
docker-compose exec -T db psql -U user course_agent_db < backup.sql
|
||||
```
|
||||
|
||||
## 📊 数据持久化
|
||||
|
||||
以下目录通过Docker volumes挂载，数据会持久化到宿主机：
|
||||
|
||||
- `./data` → `/app/data` - 知识库数据
|
||||
- `./vector_store` → `/app/vector_store` - 向量数据库
|
||||
- `./uploads` → `/app/uploads` - 用户上传文件
|
||||
- `./logs` → `/app/logs` - 日志文件
|
||||
- `./generated_images` → `/app/generated_images` - 生成的图像
|
||||
|
||||
## 🔍 故障排除
|
||||
|
||||
### 服务无法启动
|
||||
|
||||
1. 检查端口是否被占用：
|
||||
```bash
|
||||
netstat -ano | findstr :8000
|
||||
netstat -ano | findstr :8001
|
||||
```
|
||||
|
||||
2. 查看容器日志：
|
||||
```bash
|
||||
docker-compose logs app
|
||||
```
|
||||
|
||||
3. 检查环境变量配置：
|
||||
```bash
|
||||
docker-compose exec app env | grep DATABASE_URL
|
||||
```
|
||||
|
||||
### 数据库连接失败
|
||||
|
||||
1. 确保数据库服务已启动：
|
||||
```bash
|
||||
docker-compose ps db
|
||||
```
|
||||
|
||||
2. 检查数据库连接字符串：
|
||||
```bash
|
||||
docker-compose exec app env | grep DATABASE_URL
|
||||
```
|
||||
|
||||
### 前端无法访问后端
|
||||
|
||||
1. 检查后端服务是否运行：
|
||||
```bash
|
||||
curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
2. 检查CORS配置：
|
||||
```bash
|
||||
docker-compose exec app env | grep ALLOWED_ORIGINS
|
||||
```
|
||||
|
||||
## 🛠️ 开发指南
|
||||
|
||||
### 本地开发
|
||||
|
||||
如果需要本地开发（不使用Docker）：
|
||||
|
||||
1. **启动后端**:
|
||||
```bash
|
||||
cd backend
|
||||
uv sync
|
||||
uv run main.py
|
||||
```
|
||||
|
||||
2. **启动前端** (新终端):
|
||||
```bash
|
||||
cd web
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### 修改代码后重建镜像
|
||||
|
||||
```bash
|
||||
# 重新构建镜像
|
||||
docker-compose build app
|
||||
|
||||
# 重启服务
|
||||
docker-compose up -d app
|
||||
```
|
||||
|
||||
## 📝 环境变量说明
|
||||
|
||||
主要环境变量（完整列表见 `env.example`）：
|
||||
|
||||
- `DATABASE_URL`: 数据库连接字符串
|
||||
- `SILICONFLOW_API_KEY`: 硅基流动API密钥
|
||||
- `SECRET_KEY`: JWT密钥
|
||||
- `VECTOR_STORE_PATH`: 向量数据库路径
|
||||
- `KNOWLEDGE_BASE_DIR`: 知识库目录
|
||||
|
||||
## 🔐 安全建议
|
||||
|
||||
1. **生产环境**:
|
||||
- 修改所有默认密码和密钥
|
||||
- 使用强密码
|
||||
- 配置HTTPS（通过Nginx反向代理）
|
||||
- 限制数据库访问
|
||||
|
||||
2. **数据备份**:
|
||||
- 定期备份PostgreSQL数据库
|
||||
- 备份向量数据库和知识库文件
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
MIT License
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
如有问题或建议，请联系开发团队。
|
||||
|
||||
---
|
||||
|
||||
**版本**: v1.0.0 (单容器版本)
|
||||
**最后更新**: 2025年1月
|
||||
|
||||
|
||||
Reference in New Issue
Block a user