| # TeachAgent - 智能教育助手平台 |
|
|
| AI 驱动的个性化学习平台，支持教师创建 AI Agent、管理知识库，学生通过对话式交互进行学习。 |
|
|
| ## 功能特性 |
|
|
| - **教师端**：创建/管理 AI Agent、知识库管理、学生管理、分发链接、工作流编辑 |
| - **学生端**：与 AI Agent 对话、代码执行、3D 可视化、思维导图 |
| - **RAG 系统**：基于 Elasticsearch 的向量检索 + 重排序 |
| - **流式对话**：SSE 实时流式输出 |
| - **插件系统**：代码执行（CodeMirror）、3D 可视化（Plotly）、思维导图（markmap） |
|
|
| ## 项目结构 |
|
|
| ``` |
| teachagent/ |
| ├── ELASTIC/ # Elasticsearch 容器（独立部署） |
| │ └── Dockerfile |
| ├── teachagent-app/ # 主应用 |
| │ ├── app.py # Flask 入口 |
| │ ├── config.py # 配置 |
| │ ├── requirements.txt # Python 依赖 |
| │ ├── Dockerfile # 应用容器 |
| │ ├── .env # 环境变量 |
| │ ├── modules/ # 后端模块 |
| │ │ ├── auth/ # 认证（JWT + 密码/邮箱/手机登录） |
| │ │ ├── agent_builder/ # Agent 构建 |
| │ │ ├── code_executor/ # Python 代码执行 |
| │ │ ├── knowledge_base/ # RAG 知识库（检索/重排/生成） |
| │ │ └── visualization/ # 3D 可视化 + 思维导图 |
| │ ├── frontend/ # React 源码（开发用） |
| │ │ ├── src/ |
| │ │ ├── package.json |
| │ │ └── vite.config.js |
| │ ├── static/dist/ # React 构建产物（生产环境前端） |
| │ ├── agents/ # Agent JSON 配置存储 |
| │ ├── uploads/ # 用户上传文件 |
| │ └── _archive/ # 旧版 Flask 模板归档 |
| └── docker-compose.yml # 两容器编排 |
| ``` |
|
|
| ## 部署方式 |
|
|
| ### 方式一：本地开发 |
|
|
| 适合开发调试，前后端分离运行。 |
|
|
| ```bash |
| # 1. 启动 Elasticsearch（Docker 或本地安装） |
| docker run -d --name es -p 9200:9200 \ |
| -e discovery.type=single-node \ |
| -e xpack.security.enabled=false \ |
| elasticsearch:9.3.3 |
| |
| # 2. 启动 Flask 后端 |
| cd teachagent-app |
| pip install -r requirements.txt |
| FLASK_ENV=development python app.py |
| # 后端运行在 http://localhost:7860 |
| |
| # 3. 启动 React 前端（开发模式，带热更新） |
| cd frontend |
| npm install |
| npm run dev |
| # 前端运行在 http://localhost:3000，API 请求代理到 7860 |
| ``` |
|
|
| **本地开发特点**： |
| - 前端 `localhost:3000`，后端 `localhost:7860`，通过 Vite 代理转发 API |
| - SSE 流式输出需要直连后端（绕过 Vite 代理） |
| - `FLASK_ENV=development` 开启 debug 模式和热重载 |
| - 修改前端代码即时生效（HMR） |
|
|
| ### 方式二：云端容器部署（生产环境） |
|
|
| 两个容器，一个端口。 |
|
|
| ```bash |
| # 在项目根目录（包含 docker-compose.yml 的目录） |
| docker-compose up -d |
| |
| # 或分别构建 |
| docker-compose build |
| docker-compose up -d |
| ``` |
|
|
| **生产环境特点**： |
| - 单端口 `7860`：Flask 同时托管 API 和 React 静态文件 |
| - 无跨域问题：前端和 API 同源 |
| - SSE 流式直连：不经过代理，实时输出 |
| - gunicorn 多 worker 运行，性能更好 |
| - ES 通过 Docker 网络互通（`http://elasticsearch:9200`） |
|
|
| ### 方式三：HuggingFace Spaces 部署 |
|
|
| 适用于 HuggingFace Spaces 平台。 |
|
|
| 1. 将 `teachagent-app/` 作为 Space 仓库 |
| 2. ES 单独部署为另一个 Space（`ELASTIC/`） |
| 3. `.env` 中配置 `ELASTICSEARCH_URL=https://your-es-space.hf.space` |
|
|
| ## 环境变量说明 |
|
|
| | 变量 | 说明 | 示例 | |
| |------|------|------| |
| | `ELASTICSEARCH_URL` | Elasticsearch 地址 | `http://localhost:9200` 或 `https://xxx.hf.space` | |
| | `API_KEY` | SiliconFlow API Key（Embedding/Rerank） | `sk-xxx` | |
| | `BASE_URL` | SiliconFlow API 地址 | `https://api.siliconflow.cn/v1` | |
| | `STREAM_API_KEY` | DeepSeek API Key（对话生成） | `sk-xxx` | |
| | `STREAM_BASE_URL` | DeepSeek API 地址 | `https://api.deepseek.com/v1` | |
| | `STREAM_MODEL` | 对话模型 | `deepseek-chat` | |
| | `SECRET_KEY` | Flask Session 密钥 | 随机字符串 | |
| | `JWT_SECRET` | JWT 签名密钥 | 随机字符串 | |
| | `FLASK_ENV` | 运行环境 | `development` 或 `production` | |
|
|
| ## 跨域与 HTTPS |
|
|
| ### 生产环境（推荐） |
|
|
| - **无跨域问题**：前端构建产物由 Flask 直接托管，前端和 API 同源（同一个端口 7860） |
| - **HTTPS**：由反向代理（Nginx/Cloudflare/HuggingFace Spaces）统一处理 SSL 终止，Flask 本身只需 HTTP |
| - **SSE 流式**：同源直连，无需代理，数据实时到达 |
|
|
| ### 本地开发 |
|
|
| - **跨域**：Vite 代理 (`localhost:3000` → `localhost:7860`) 处理 API 请求，SSE 直连后端 |
| - **HTTPS**：本地开发无需 HTTPS，全部 HTTP |
| - **注意**：HTML 中不要加 `upgrade-insecure-requests` meta 标签（已移除） |
|
|
| ### 带 HTTPS 反向代理部署 |
|
|
| 如果在自有服务器上通过 Nginx 反向代理： |
|
|
| ```nginx |
| server { |
| listen 443 ssl; |
| server_name your-domain.com; |
| |
| ssl_certificate /path/to/cert.pem; |
| ssl_certificate_key /path/to/key.pem; |
| |
| location / { |
| proxy_pass http://127.0.0.1:7860; |
| proxy_http_version 1.1; |
| proxy_set_header Host $host; |
| proxy_set_header X-Real-IP $remote_addr; |
| |
| # SSE 流式输出必须的配置 |
| proxy_buffering off; |
| proxy_cache off; |
| proxy_set_header Connection ''; |
| chunked_transfer_encoding on; |
| } |
| } |
| ``` |
|
|
| 关键配置：`proxy_buffering off` 确保 SSE 数据不被 Nginx 缓冲。 |
|
|
| ## 演示账号 |
|
|
| | 角色 | 用户名 | 密码 | |
| |------|--------|------| |
| | 教师 | teacher | 123456 | |
| | 学生 | student1 | 123456 | |
|
|
| 也可通过注册页面创建新账号。 |
|
|
| ## 技术栈 |
|
|
| | 层 | 技术 | |
| |----|------| |
| | 前端 | React 19 + Vite + Ant Design 5 + TailwindCSS + Redux Toolkit | |
| | 后端 | Flask + gunicorn | |
| | 数据库 | Elasticsearch 9.x（向量检索） + SQLite（用户管理） | |
| | AI | DeepSeek（对话） + SiliconFlow（Embedding/Rerank） | |
| | 部署 | Docker + docker-compose | |
|
|
