学术论文一站式阅读与管理平台的全栈脚手架
基于 FastAPI + Next.js 15 + MinerU 的 End-to-End 智能阅读工作台
浏览项目 »
快速体验
·
报告问题
·
提交建议
InsightReading Platform 面向科研用户提供论文检索、个人文库与智能阅读体验：后端使用 FastAPI + Celery + PostgreSQL + Redis 负责鉴权、任务调度与 MinerU PDF 解析，前端采用 Next.js 15 App Router 构建液态玻璃风格的阅读界面，并通过 React Markdown + KaTeX 完整渲染 MinerU 解析结果（文本、公式、图片、表格）。
核心亮点：
- 支持用户注册登录、个人资料维护、头像上传与密码修改，统一以 JWT 认证（
/api/v1/auth/token）。 - 集成 arXiv 聚合检索与导入流程（
/api/v1/arxiv/search），支持关键词、排序与分页，便于构建论文推荐列表。 - 提供 PDF 上传、导入与批注能力（
/api/v1/papers/upload、/api/v1/papers/uploads/{paper_id}/annotations），可在原文上高亮与记录笔记。 - 基于 MinerU 与 DocLayout-YOLO 实现 PDF 结构化解析，结果存入缓存表
parsed_paper_cache，重复文件只需解析一次（/api/v1/papers/uploads/{paper_id}/parse）。 - 前端聚合仪表盘、上传、推荐与智能阅读场景，使用 Turbopack 加速本地开发，并通过 API Client 与后端协同。
项目结构概览：
.
├── backend/
│ ├── app/
│ │ ├── api/v1/ # FastAPI 路由（上传、解析、标注、arXiv 检索等）
│ │ ├── core/ # 配置、Settings
│ │ ├── db/ # AsyncSession、Repository
│ │ ├── models/ # SQLAlchemy ORM（含 UploadedPaper、ParsedPaperCache 等）
│ │ ├── schemas/ # Pydantic DTO
│ │ ├── services/ # MinerU CLI 包装、批注逻辑等
│ │ └── media/ # 运行期生成（uploads/parsed/runtime_cache），已加入 .gitignore
│ ├── migrations/ # Alembic 迁移
│ ├── sitecustomize.py # PyTorch / DocLayout-YOLO 兼容补丁
│ └── pyproject.toml # 后端依赖（含 mineru、doclayout-yolo 等）
├── frontend/
│ ├── src/app/ # Next.js 页面（Dashboard、Smart Reading 等）
│ ├── src/components/ # PDF Viewer、布局与 UI 组件
│ ├── src/lib/ # fetch 封装、配置、API Client
│ └── package.json # 前端依赖（react-markdown、remark-math、rehype-katex 等）
├── docker-compose.yml # Postgres + Redis + 前端容器（支持 dev / infra profile）
├── scripts/dev.sh # 一键启动脚本（数据库 + 后端 + 前端）
└── README.md # 本文件(回到顶部)
(回到顶部)
推荐使用根目录下的 scripts/dev.sh 一键拉起数据库、后端与前端；也支持通过 Docker Compose / 手动方式拆分运行，便于调试。
- Python 3.11（建议与后端虚拟环境一致）
- Node.js 20+ 与 npm
- Docker 与 Docker Compose（用于 Postgres / Redis 及可选的前端容器）
- 合理的本地磁盘空间用于 MinerU 模型与解析缓存
-
克隆仓库并进入项目根目录：
git clone https://github.com/Dynamite2003/InsightReading.git cd InsightReading -
配置环境变量：
# 后端 cp backend/.env.example backend/.env # 前端 cp frontend/.env.local.example frontend/.env.local
根据需要修改数据库、Redis、MinerU 缓存目录与各类 API Key 等参数。FastAPI 默认读取
backend/.env，Next.js 在开发/生产读取frontend/.env.local。 -
执行数据库迁移（首次运行必需）：
cd backend python3.11 -m venv .venv source .venv/bin/activate # Windows 使用 .venv\\Scripts\\activate pip install -e . alembic upgrade head cd ..
-
一键启动（推荐）：
./scripts/dev.sh
脚本会自动：
- 使用 Docker Compose 启动 Postgres / Redis；
- 创建并激活
backend/.venv，安装依赖并启动uvicorn app.main:app --reload； - 安装前端依赖并执行
npm run dev。
默认访问地址：
- 前端：
http://localhost:3000 - 后端 API：
http://localhost:8000/api/v1
-
停止服务：
- 在运行脚本的终端按
Ctrl + C结束前后端； - 如需停止数据库容器：
docker compose down
- 在运行脚本的终端按
- Postgres & Redis：
docker compose up -d postgres redis
- 后端 FastAPI：
cd backend python3.11 -m venv .venv source .venv/bin/activate pip install -e . alembic upgrade head # 可选：配置 MinerU 缓存目录 export MAGIC_PDF_MODELS_DIR=$HOME/Library/Caches/insightreading/models export HF_HOME=$HOME/Library/Caches/insightreading/hf_cache uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
- 启动 MinerU Celery Worker：
cd backend source .venv/bin/activate export PYTHONPATH=$PWD:$PYTHONPATH celery -A app.workers.celery_app.celery_app worker --loglevel=info --queues default
- 前端 Next.js：
cd frontend npm install npm run dev
如需以 Docker 方式运行前端（并共用容器化数据库），可使用 dev profile：
docker compose --profile dev up --build此时后端仍在本机运行，前端容器通过 BACKEND_INTERNAL_URL 访问后端。
cd backend
python -m pytest -q无需启动 uvicorn（默认走 ASGI in-process）：
cd backend
python scripts/stress_test.py --scenario health --requests 5000 --concurrency 100
python scripts/stress_test.py --scenario me --users 50 --requests 5000 --concurrency 100如需对已启动的服务做压测，可指定 --url：
cd backend
python scripts/stress_test.py --url http://127.0.0.1:8000 --scenario health --requests 10000 --concurrency 200前端可使用：
cd frontend
npm run lint(回到顶部)
- 访问前端仪表盘，可浏览个性化推荐、个人文库与上传入口。
- 通过
/api/v1/auth/token获取访问令牌后，可调用受保护接口（如/api/v1/users/me、/api/v1/papers/upload、/api/v1/papers/uploads）。 - arXiv 检索接口
/api/v1/arxiv/search支持关键词、排序与分页参数，可用于构建论文推荐与搜索功能。 - PDF 上传成功后文件默认保存在
backend/app/media/uploads/，可通过/api/v1/papers/uploads/{paper_id}/parse提交 MinerU 解析任务。 - 解析结果命中缓存时会直接返回，未命中时由 Celery Worker 调用 MinerU 并将 JSON 结果写入
parsed_paper_cache，后续同一文件解析将直接复用。 - 批注接口
/api/v1/papers/uploads/{paper_id}/annotations支持高亮与文本批注，前端 PDF Viewer 会实时展示。 - 后端启动后可访问 API 文档：
http://localhost:8000/docs（Swagger UI）/http://localhost:8000/redoc（ReDoc），OpenAPI Schema：http://localhost:8000/openapi.json。
导出 OpenAPI 文件（生成 openapi.json，便于前端/测试工具对接）：
python backend/export_openapi.py
# 或指定输出路径
python backend/export_openapi.py --output doc/openapi.json前端调用示例可参考 frontend/src/lib/api-client.ts 与 frontend/src/app 中的页面实现。
(回到顶部)
- 用户认证、资料维护与头像上传
- 对话与消息管理仓储
- arXiv 聚合检索与论文保存流程
- PDF 上传、静态托管与 MinerU / PyMuPDF 批注
- Next.js 15 前端界面与液态玻璃设计
-
/api/v1/papers本地索引与检索实现（替换 501 占位实现） - Celery 任务接入外部元数据与 LLM 总结
- 多源数据管道（Semantic Scholar、CrossRef 等）
- AI 推荐与个性化阅读路线
更多任务请查看 开放的 Issues。
(回到顶部)
欢迎任何形式的反馈与贡献：
- Fork 当前仓库
- 基于
main创建特性分支：git checkout -b feature/AmazingFeature - 提交代码并遵循项目 ESLint / pytest / Ruff 检查
- 发起 Pull Request 并描述变更内容
如果只想报告问题，可直接在 Issues 中提交。
(回到顶部)
本项目当前处于内部迭代阶段，尚未正式发布开源许可证。若需引用或商用，请先联系项目维护者。
(回到顶部)
InsightReading 团队 — shizy22@mails.tsinghua.edu.cn / hanxj23@mails.tsinghua.edu.cn / liusa23@mails.tsinghua.edu.cn
项目地址：https://github.com/Dynamite2003/InsightReading
(回到顶部)
(回到顶部)
docker compose up -d postgres redis确保已存在
backend/.env。
cd backend
python -m venv .venv
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
.\.venv\Scripts\Activate.ps1
pip install -e .
uv run alembic upgrade head
# 启动
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload确保已存在
frontend/.env.local。
cd frontend
npm install
npm run dev访问 http://localhost:3000 ，前端默认调用 http://localhost:8000/api/v1。
清除缓存
docker exec -it insightreading-postgres-1 psql -U postgres -d papers -c "DELETE FROM uploaded_papers; DELETE FROM papers; DELETE FROM parsed_paper_cache; DELETE FROM mineru_parse_jobs;"