README-local.md

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         # 两容器编排

部署方式

方式一：本地开发

适合开发调试，前后端分离运行。

# 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）

方式二：云端容器部署（生产环境）

两个容器，一个端口。

# 在项目根目录（包含 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 反向代理：

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