course-agent-od/README.md

# 国土空间规划课程智能体 - 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月