MathCraft 面向教师与学生,提供题库协作、文档解析与检索、智能出题、组卷发布、学生作答和 AI 批卷。后端使用 FastAPI,前端使用 React 19 + TypeScript + Vite,数据存储采用 SQLite、Redis 与 Chroma。
- 教师:管理题库与学习空间,上传教学资料,出题、组卷、发布试卷和催交。
- 学生:加入学习空间,作答、查看获准公开的解析,收藏题目。
- 管理员:开通与管理账号,维护平台模型、检索配置和索引重建。
文档支持 PDF、DOCX、XLSX、Markdown 和 TXT;扫描件通过 MinerU OCR 解析,检索采用向量与全文混合召回、重排,出题与批卷使用 DeepSeek。
对话提供快速出题、创新命题、知识答疑和数据管理四模式,右侧历史会话支持继续已有对话。出题先命制题干,再独立解题生成答案、选项和解析,审核后按题型缺口尝试补齐;界面通过进度轮询等待结果。题目预览中勾选题目后可导出 Word,设置题型顺序、答案和解析的位置。
试卷支持关闭和恢复作答,删除保留已有作答及成绩;出题任务状态存入 SQL,服务重启后未完成的任务标为中断,用户可重新发起。预览页一键清空只删除题目,保留对话;运行期间暂不可清空,后台取消和最终提交继续校验运行身份。
学习空间可在停止作答后移除尚无作答记录的发布;已有作答保留历史入口。删除未完成的题库与资料在管理页提供继续清理入口。
两类出题入口已接入正式运行台账,运维 V2 提供管理员概览、运行列表和详情查询;前端已对接 V2 概览、运行列表与基本详情。台账不可用时查询返回 503,不回退演示数据。范围、字段和交接见运维查询 V2。
以下列出主要源码、配置与文档入口:
MathCraft/
├── .github/ # CI、发布工作流及发布门禁脚本
├── backend/ # FastAPI 后端
│ ├── app/ # 接口、数据模型与业务服务
│ ├── alembic/ # 数据库迁移
│ ├── scripts/ # 配置初始化与账号管理
│ ├── tests/ # 后端测试与隔离页面联调辅助
│ └── README.md # 后端配置、迁移与排错
├── frontend/ # React + TypeScript 前端
│ ├── src/ # 页面、组件、API 与状态管理
│ └── README.md # 前端开发说明
├── docs/ # API、设计与维护文档
│ ├── api.md # API 索引
│ ├── 测试与持续集成.md # 测试范围与 CI 维护说明
│ ├── design/ # 功能与架构设计
│ ├── requirements/ # 产品需求与待定讨论
│ ├── implementation/ # 实施、交接与历史验收
│ ├── research/ # 调查与评估
│ ├── reference/ # 参考清单
│ ├── operations/ # 运维手册
│ └── archive/ # 已失效方案归档
├── tools/ # 文档生成与维护工具
│ ├── archive/ # 失效脚本历史归档,不用于当前验收
│ └── ops_g0/ # 历史工具及独立测试
├── apps/desktop/ # 桌面客户端预留目录
├── packages/contracts/ # 共享契约预留目录
├── compose.yaml # 本地 Redis 容器
├── compose.phoenix.yaml # 可选 Phoenix 追踪服务
├── pyproject.toml # 仓库级依赖与检查配置
├── openapi.json # 接口契约
├── AGENTS.md # 协作约定
└── STUBS.md # 开发演示与历史替身说明
以下命令以 PowerShell 为例。先在终端进入仓库根目录,即包含 compose.yaml、backend/ 和 frontend/ 的目录;Redis、后端、前端按顺序启动。
安装 Python 3.11 及以上、uv、Node.js 22.13 及以上的 22.x 版本或 Node.js 24 及以上(含 npm),以及 Docker 与 Compose v2。Windows 使用 Docker Desktop 的 Linux 容器引擎,并先启动 Docker Desktop;已有 Redis 7 及以上服务时可直接使用。
python --version
uv --version
node --version
npm --version
docker compose version模型出题、向量检索与 OCR 需要访问相应外部服务,并配置凭据。
在仓库根目录执行:
docker compose config --quiet
docker compose up -d --wait redis
docker compose exec redis redis-cli ping最后一条命令应返回 PONG。默认监听 127.0.0.1:6379,数据保存到 Docker 命名卷。若端口已被现有 Redis 占用,直接使用该服务,并在下一步配置对应的 REDIS_URL。
在同一终端进入 backend/:
cd backend
uv sync
uv run python scripts/init_auth_secrets.py
if (-not (Test-Path app/local_secrets.py)) {
Copy-Item app/local_secrets.example.py app/local_secrets.py
}出题 JSON 修复依赖 json-repair,Word 导出依赖 python-docx、latex2mathml 和 mathml2omml,由上述 uv sync 安装。升级时需重新同步依赖;仓库根环境与后端独立环境分别由各自的 pyproject.toml、uv.lock 管理,使用哪个环境就同步哪个环境。导出在本地生成文档,无需模型调用或安装 Microsoft Word。
OpenAI 兼容客户端使用 openai<3:当前追踪适配基于 httpx,不兼容 OpenAI SDK 3.x 的 httpx2。已有环境更新后执行 uv sync 并重启后端,避免个人模型连接测试在请求发出前报客户端兼容错误。
初始化脚本在缺少 backend/.env 时从 .env.example 创建,生成两项独立的认证密钥;已有合法密钥会保留,且不会打印。随后用编辑器打开 backend/.env,确认以下配置:
| 配置 | 本机开发填写方式 |
|---|---|
APP_ENV |
development |
TURNSTILE_ENABLED |
false,仅实际回环请求可跳过人机验证 |
DATABASE_URL |
默认 sqlite:///./data/mathcraft.db |
REDIS_URL |
默认 redis://127.0.0.1:6379/0,与上一步的服务一致 |
AUTH_JWT_SECRET、AUTH_CODE_SECRET |
由初始化脚本生成,保留生成值 |
DEEPSEEK_API_KEY |
可填部署默认 Key,也可登录后在“设置 → 模型与服务”保存个人 Key |
SMTP_* |
使用邮箱验证码登录、找回密码或绑定邮箱时配置 |
上述复制命令仅在缺少 app/local_secrets.py 时创建占位配置,已有文件保留。首次账号密码登录无需真实模型凭据,使用模型功能前再配置对应服务。
已有 .env 不会被模板覆盖,需手动核对开发开关。后端环境配置以 backend/app/config.py 为准,进程环境变量优先于固定位置的 backend/.env;修改后需重启后端。唯一可复制的后端环境模板为 backend/.env.example,根 .env.example 仅作配置入口指引,当前前后端均不读取根 .env。
MinerU Token 在“设置 → 模型与服务”保存,个人配置优先;部署默认 Token 使用 app/local_secrets.py 的 MINERU_DEFAULT_TOKEN。旧 MINERU_MODE、MINERU_API_BASE_URL、MINERU_API_TOKEN 不生效,已有本机文件不会自动迁移。嵌入和重排模型仍由管理员“模型与检索”维护。
平台生成模型凭据支持管理员接口 /api/admin/llm-settings,使用 cryptography 加密保存。调用优先使用个人 Key,其次为平台凭据,最后为部署默认;个人 Key 被模型服务拒绝时可回退平台配置。加密主密钥位于上传目录父级的 secret.key(默认 backend/data/secret.key),备份数据库时一并备份该文件。
已有数据应先备份并在副本验证;若曾使用旧 V2 同号迁移或来源不明,须先按后端迁移说明核对并制定修复方案。完成核验后继续在 backend/ 执行:
New-Item -ItemType Directory -Path data -Force | Out-Null
uv run alembic upgrade head
uv run python scripts/create_admin.py按提示输入登录账号、显示名称和两次密码。账号可使用英文字母、数字、下划线、点和连字符;密码为 8–64 字符,UTF-8 不超过 72 字节,输入时隐藏。管理员只需首次创建,已有管理员时跳过最后一条命令;脚本不会覆盖已有账号。
已有数据的环境应先备份再迁移。自定义 SQLite 路径时,先创建对应父目录;备份需包含 WAL 已提交数据,可使用 SQLite backup API,具体见 后端说明。
仍在 backend/ 执行,并保持该终端运行:
$mathcraftTemp = (New-Item -ItemType Directory -Path data/tmp -Force).FullName
$env:TEMP = $mathcraftTemp
$env:TMP = $mathcraftTemp
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --workers 1 --no-proxy-headers上述 PowerShell 启动方式为当前终端及后端子进程指定本地临时目录,避免 Windows 默认临时目录不可写时导致 Chroma 初始化或向量写入失败。Chroma 使用进程内本地持久存储,无需另外启动向量数据库服务;临时目录不替代 CHROMA_DIR 中的正式索引。
启动后可访问:
- 健康检查:
http://127.0.0.1:8000/api/health - Swagger 接口文档:
http://127.0.0.1:8000/docs
索引重建使用进程内任务,当前按单进程部署,保留 --workers 1。
新开一个终端,从仓库根目录执行:
cd frontend
npm install
node node_modules/vite/bin/vite.js --host 127.0.0.1 --port 5173 --strictPort打开 http://127.0.0.1:5173,使用刚创建的管理员账号选择“密码登录”。前端将 /api 和 /media 请求代理到后端的 8000 端口;端口占用时退出,不自动换端口。
前端隔离项目环境文件,根 .env 和 frontend/.env 均不会被 Vite 加载;自定义公开 API 地址需在开发启动或构建前通过进程环境变量 VITE_API_BASE_URL 注入。监听地址与端口使用上述命令行参数,开发代理目标由 frontend/vite.config.ts 定义;VITE_* 会进入浏览器代码,不得放入凭据。详见前端配置说明。
教师、学生账号由管理员开通。个人 DeepSeek Key 和 MinerU Token 在“设置 → 模型与服务”配置;平台嵌入、重排模型由管理员在“模型与检索”配置。嵌入模型或服务地址变更后,需重建索引才能应用。
部署默认的硅基流动与 MinerU 凭据配置方式见 模型配置说明,占位格式见 local_secrets.example.py。
首次初始化完成后,只需启动 Redis,并分别在 backend/、frontend/ 运行上述服务命令。依赖变更后重新安装,数据库结构变更后重新执行迁移。
前后端各在对应终端按 Ctrl+C 停止。Redis 在仓库根目录管理:
docker compose stop redis # 暂停
docker compose up -d --wait redis # 恢复
docker compose down # 移除容器,保留数据卷默认运行数据位于 backend/data/,包括 SQLite、上传原件、OCR 结果、头像与 Chroma 索引;Redis 数据另存在 Docker 卷中。日常停止不要给 down 添加 -v,该参数会删除数据卷。
- 登录按钮显示“认证配置不可用”:确认认证密钥已初始化,开发配置为
APP_ENV=development、TURNSTILE_ENABLED=false,按上述回环地址与--no-proxy-headers启动,然后重启后端、刷新页面。检查启动环境变量是否覆盖.env。 - 前端请求失败:确认后端 8000 端口和 Redis 均已启动;邮件、向量、OCR 等依赖的状态可从健康检查查看。
- Chroma 在 Windows 报
code 14:核对启动进程的TEMP/TMP是否可写,处理步骤见 后端说明。 - 删除资料提示
DATABASE_BUSY或DELETION_PENDING:短暂写锁会有限重试;已登记删除的资源进入不可用状态,重试或重启后继续清理,见 删除与恢复边界。 - 删除资料的全文索引清理出现
SQLITE_CANTOPEN / 14:更新后重启后端以应用 SQLite 内存临时存储配置;数据库与 WAL 仍保存在磁盘。该错误与写锁竞争分别处理,见 后端排错说明。
生产部署需设置 APP_ENV=production、TURNSTILE_ENABLED=true 并配置 Cloudflare 站点信息,关闭开发账号能力,配置持久化路径与备份。服务器通过 SSH 连接,部署前按 后端迁移说明 完成备份、迁移与审计。
默认关闭。需要时在 backend/ 执行 uv sync --extra phoenix,在仓库根执行 docker compose -f compose.phoenix.yaml up -d --wait phoenix;设置 PHOENIX_ENABLED=true 并重启后端。使用根环境时也在根目录安装同名 extra。
默认 OTLP 地址为 http://127.0.0.1:6017/v1/traces,查看入口为 http://127.0.0.1:6017。容器固定 Phoenix 21 镜像 digest,数据保存到 phoenix_data 命名卷。此本机部署默认无认证,仅限可信单机;远程访问须独立配置 HTTPS、认证和 API key。
默认配置:PHOENIX_ENABLED=false、PHOENIX_PROJECT=mathcraft、PHOENIX_API_KEY=(SecretStr)、PHOENIX_QUEUE_SIZE=128、PHOENIX_TIMEOUT_SECONDS=0.5。根与后端 extra 均固定 opentelemetry-sdk==1.45.2、opentelemetry-exporter-otlp-proto-http==1.45.2,仅追踪元数据。停用时关闭开关并重启后端;容器可独立 docker compose -f compose.phoenix.yaml stop phoenix,保留数据卷。
详细配置与排错见 Phoenix 可选扩展。
后端在 backend/ 执行;测试使用临时 SQLite、进程内 fakeredis 和外部服务替身,夹具禁止外部网络,不连接或清空本机 Redis:
uv sync --group dev
uv run pytest -q开发依赖包含 pytest-xdist,可使用 pytest -n 4 --dist loadfile 并行执行。当前测试范围与隔离说明见测试与持续集成。
前端在 frontend/ 执行:
npm run typecheck
npm run lint
npm run build- 后端说明、前端说明:开发、配置与排错。
- API 文档、OpenAPI 契约:接口与数据字段。
- 数据一致性与故障恢复设计:关闭与历史作答、任务持久化、删除恢复及缓存完整性。
- 账号与权限、认证与账号安全。
- 模型配置、知识库。
- 四模式对话、出题审核、Word 导出。
- 出题链路优化设计、需求讨论、本地问题核查:已确认范围、检查证据与待实现方案。
- 运维后台、运行手册、台账基础、入口接入、前端 V2和可选追踪。
- 协作约定。
本项目采用 Apache License 2.0 开源。第三方组件的许可证与声明见 THIRD_PARTY_NOTICES.md。