国土空间规划课程智能体 - 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. 克隆项目

cd course_Agent

2. 配置环境变量

复制环境变量模板：

cp env.example .env

编辑 .env 文件，配置必要的参数（API密钥、数据库密码等）。

3. 启动服务

# 构建并启动所有服务
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. 停止服务

docker-compose down

🔧 服务管理

查看日志

# 查看所有服务日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f app
docker-compose logs -f db

重启服务

# 重启所有服务
docker-compose restart

# 重启特定服务
docker-compose restart app

进入容器

# 进入应用容器
docker-compose exec app bash

# 在容器内查看进程状态
supervisorctl status

数据库操作

# 进入数据库容器
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. 检查端口是否被占用：

netstat -ano | findstr :8000
netstat -ano | findstr :8001

2. 查看容器日志：

docker-compose logs app

3. 检查环境变量配置：

docker-compose exec app env | grep DATABASE_URL

数据库连接失败

1. 确保数据库服务已启动：

docker-compose ps db

2. 检查数据库连接字符串：

docker-compose exec app env | grep DATABASE_URL

前端无法访问后端

1. 检查后端服务是否运行：

curl http://localhost:8000/health

2. 检查CORS配置：

docker-compose exec app env | grep ALLOWED_ORIGINS

🛠️ 开发指南

本地开发

如果需要本地开发（不使用Docker）：

1. 启动后端:

cd backend
uv sync
uv run main.py

2. 启动前端 (新终端):

cd web
pnpm install
pnpm dev

修改代码后重建镜像

# 重新构建镜像
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月