docs: 更新/重写项目文档（README / 部署手册 / 前端说明）
- README.md：补充原生分页 / 连续选取 / 摘录高亮说明；阅读位置改为 服务端跨设备同步（不再是「当前浏览器保存」）；补「第二大脑」助手 与模型管理入口；验证命令改为 venv 内 python - deploy/README.md：修正 git clone 后的实际目录结构；新增第 8 节 「历史遗留数据清理」（clean_orphans 脚本 + 启动迁移自动清理）， 并在常见问题里补跨设备位置 / 删书不彻底 / 脚本 ModuleNotFound 等 - frontend/README.md：整体重写，去掉 create-next-app 模板残留 （Vercel / Geist），改为项目真实结构 / 模块说明 / 本地开发 / 构建 - 删除 backend/AGENTS.md：Next.js 自动生成的残留块，backend 目录为 FastAPI 项目、无 node_modules/next，删除避免误导（frontend 那份保留） Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
Claude Code
@@ -1,10 +1,10 @@
|
||||
# BookMate
|
||||
|
||||
基于 FastAPI 和 Next.js 的 AI 读书助手。支持 EPUB 导入、围绕书籍内容对话、原文引用和完整 EPUB 网页阅读。
|
||||
基于 FastAPI 和 Next.js 的 AI 读书助手。支持 EPUB 导入、围绕书籍内容对话、原文引用、完整 EPUB 网页阅读（原生分页）、摘录与高亮，以及跨书籍跨对话的全局「第二大脑」AI 助手。
|
||||
|
||||
## 本地启动
|
||||
|
||||
后端（Python 3.12）：
|
||||
后端（Python 3.12，Windows PowerShell）：
|
||||
|
||||
```powershell
|
||||
cd backend
|
||||
@@ -14,7 +14,9 @@ Copy-Item .env.example .env
|
||||
.venv/Scripts/python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
||||
```
|
||||
|
||||
在 `.env` 配置模型 API，或启动后在网页的模型管理中添加模型。数据库和上传目录会自动创建。未配置向量服务时使用关键词检索。
|
||||
macOS / Linux 同理，把 `.venv/Scripts/python.exe` 换成 `.venv/bin/python`。
|
||||
|
||||
在 `.env` 配置模型 API，或启动后在网页的「管理模型」中添加模型。数据库和上传目录会自动创建。未配置向量服务时自动降级为关键词检索。
|
||||
|
||||
另开终端启动前端（Node.js 20.9+）：
|
||||
|
||||
@@ -28,7 +30,15 @@ npm run dev
|
||||
|
||||
## 阅读与对话
|
||||
|
||||
导入 EPUB 后，在书架或聊天页面点击「阅读全书」。阅读器支持目录、翻页、字号调整，以及在当前浏览器保存阅读位置。选中文字后可将原文带入 AI 聊天输入框。
|
||||
导入 EPUB 后，在书架或聊天页面点击「阅读全书」。阅读器支持：
|
||||
|
||||
- 目录跳转、原生分页翻页、字号调整（14–28）
|
||||
- **阅读位置跨设备同步**：`relocated` 驱动的 CFI 位置存在服务端（`reading_progress` 表），换浏览器 / 换设备继续读；loses localStorage 仅作离线兜底
|
||||
- **连续选取**：切换为 scrolled 流以便跨页选中文字，选完自动回到分页
|
||||
- 选中文字后「保存摘录 / 添加高亮」，或直接「交给 AI 解读」把原文带入 AI 聊天
|
||||
- 摘录与笔记侧栏支持导出 Markdown
|
||||
|
||||
顶部导航的「AI 助手」进入全局「第二大脑」模式：不绑定单本书，可跨书籍跨对话使用内置 `bm_*` 工具检索你的书库。
|
||||
|
||||
## MCP 外部工具
|
||||
|
||||
@@ -47,3 +57,7 @@ npm run build
|
||||
```
|
||||
|
||||
本地 `.env`、模型凭据、数据库、上传书籍和构建产物不纳入版本控制。
|
||||
|
||||
## 云服务器部署
|
||||
|
||||
见 `deploy/README.md`（Docker + nginx-proxy-manager，含数据迁移、`.env` 配置、NPM 反代、日常运维与历史数据清理）。
|
||||
@@ -1,9 +0,0 @@
|
||||
<!-- BEGIN:nextjs-agent-rules -->
|
||||
|
||||
## This is NOT the Next.js you know
|
||||
|
||||
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
|
||||
|
||||
This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
|
||||
|
||||
<!-- END:nextjs-agent-rules -->
|
||||
+33
-3
@@ -10,11 +10,13 @@
|
||||
|
||||
```bash
|
||||
# A. git 克隆（推荐，后续更新方便）
|
||||
# 注意：git clone 会在目标目录下再建一层仓库名子目录，
|
||||
# 下文统一用「仓库根目录」指代实际目录（/opt/bookmate/my_bookmate）
|
||||
git clone https://code.aifunny.ltd/gavindiaz/my_bookmate.git /opt/bookmate
|
||||
cd /opt/bookmate
|
||||
cd /opt/bookmate/my_bookmate
|
||||
|
||||
# B. 或从本机拷贝（不含 .git 也行）
|
||||
# scp -r ./bookmate user@server:/opt/
|
||||
# scp -r ./bookmate user@server:/opt/bookmate/
|
||||
```
|
||||
|
||||
## 1. 迁移现有数据（保留书库 / 对话 / 向量）
|
||||
@@ -88,7 +90,7 @@ SSE 流式与文件上传都是普通 HTTP，NPM 无需 websocket 特殊配置
|
||||
|
||||
```bash
|
||||
# 更新到最新代码并重建
|
||||
cd /opt/bookmate
|
||||
cd /opt/bookmate/my_bookmate
|
||||
git pull
|
||||
docker compose up -d --build
|
||||
|
||||
@@ -100,6 +102,26 @@ docker compose logs -f frontend
|
||||
tar czf bookmate-data-backup.tgz deploy/data deploy/uploads
|
||||
```
|
||||
|
||||
如果 `git pull` 后容器里没看到新代码，说明改动可能只进过数据库迁移/脚本目录——
|
||||
`docker compose up -d --build` 会重新构建镜像，把新文件烧进去。
|
||||
|
||||
## 8. 历史遗留数据清理（孤儿 DB 行 / uploads 文件）
|
||||
|
||||
早期版本删书时因 `file_path` 存的是 Windows 相对路径 + SQLite 外键未强制开启，
|
||||
可能残留无主的数据库行（segments / chapters / reading_notes / reading_progress /
|
||||
conversations / messages）和 `deploy/uploads` 下无书籍记录的 `.epub` 文件。
|
||||
清理脚本只删「无主」数据，现存的书籍、笔记、对话、模型、MCP 一律不动，可反复执行：
|
||||
|
||||
```bash
|
||||
cd /opt/bookmate/my_bookmate
|
||||
docker compose up -d --build # 先把脚本打镜像（首次必须）
|
||||
docker compose exec backend python -m app.scripts.clean_orphans
|
||||
```
|
||||
|
||||
输出会列出各表删除的行数与被删的 epub 文件名；无残留时全部为 0。
|
||||
后端启动迁移每次也会自动清孤儿 DB 行（缺新表时自动跳过），因此 `docker compose restart backend`
|
||||
同样能清理 DB 残留；uploads 文件残留仍需上面的脚本。
|
||||
|
||||
## 大陆网络
|
||||
|
||||
Dockerfile 已把国内源烘焙成默认值（可在构建时用 `--build-arg` 覆盖为官方源）：
|
||||
@@ -118,3 +140,11 @@ Dockerfile 已把国内源烘焙成默认值（可在构建时用 `--build-arg`
|
||||
- **页面能开但接口 404**：`/api` 的 Custom Location 没加，或 `NEXT_PUBLIC_API_BASE` 端口/域名
|
||||
与 NPM 配置不一致（它内联在构建产物里，改了要重新 build）。
|
||||
- **向量没生效**：确认 `EMBEDDING_API_KEY` / `RERANK_API_KEY` 已填；上传新书后后台会自动生成向量。
|
||||
- **换设备阅读位置不续上**：位置存在服务端（`reading_notes` 之外的 `reading_progress` 表），
|
||||
同一本书两端应一致；若不一致，确认前端已更新到含 `GET/PUT /books/{id}/progress` 的版本并重新 build。
|
||||
- **删书后文件还在 / DB 不缩水**：跑一遍上面的清理脚本（第 8 节）；SQLite 的 DELETE 不缩文件，
|
||||
脚本结尾的 VACUUM 会真正压缩 db。
|
||||
- **`python -m app.scripts.clean_orphans` 报 ModuleNotFoundError**：镜像太旧，
|
||||
重新 `docker compose build backend && docker compose up -d`。
|
||||
- **模型 / MCP 配置消失**：清理脚本不涉及 `ai_models` / `mcp_servers` 表，不会删除它们；
|
||||
若丢失先检查是否误清了数据卷或迁移了旧库。
|
||||
|
||||
+38
-23
@@ -1,36 +1,51 @@
|
||||
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
|
||||
# BookMate 前端（Next.js）
|
||||
|
||||
## Getting Started
|
||||
BookMate 的 Web 界面：书架、EPUB 阅读器、书库对话、全局「第二大脑」AI 助手、模型管理、MCP 服务配置。
|
||||
|
||||
First, run the development server:
|
||||
## 技术栈
|
||||
|
||||
- Next.js（App Router，React 19），Tailwind CSS v4
|
||||
- epubjs 0.3（阅读器：原生分页 + 必要时的 scrolled-doc 切换）
|
||||
- lucide-react 图标；`@/lib/api` 统一的带鉴权 fetch 封装
|
||||
|
||||
## 主要模块
|
||||
|
||||
| 路径 | 作用 |
|
||||
|---|---|
|
||||
| `src/app/page.tsx` | 书架 + 会话主界面；顶部导航在「书库」与「AI 助手（第二大脑）」间切换 |
|
||||
| `src/components/EpubReader.tsx` | 全屏 EPUB 阅读器：原生分页、目录、字号、摘录/高亮、跨设备阅读位置同步、连续选取开关 |
|
||||
| `src/components/ChatPanel.tsx` | 流式对话（引用、工具调用、复制/导出） |
|
||||
| `src/components/ModelManagerDialog.tsx` | 网页内管理 AI 模型（OpenAI 兼容 / Anthropic） |
|
||||
| `src/components/McpManagerDialog.tsx` | 配置远程 MCP 服务器（Streamable HTTP / SSE） |
|
||||
| `src/lib/api.ts` | 后端 API 客户端（含 `authHeaders()`） |
|
||||
| `src/lib/auth.ts` | `SITE_PASSWORD` 登录与令牌存取 |
|
||||
|
||||
## 本地开发
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run dev
|
||||
# or
|
||||
yarn dev
|
||||
# or
|
||||
pnpm dev
|
||||
# or
|
||||
bun dev
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
|
||||
打开 http://localhost:3000。后端地址默认 `http://localhost:8000/api`，可用环境变量覆盖：
|
||||
|
||||
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
|
||||
```bash
|
||||
# Windows PowerShell
|
||||
$env:NEXT_PUBLIC_API_BASE="http://localhost:8000/api"
|
||||
npm run dev
|
||||
```
|
||||
|
||||
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
|
||||
## 构建
|
||||
|
||||
## Learn More
|
||||
```bash
|
||||
npm run build
|
||||
# 生产运行
|
||||
npm run start
|
||||
```
|
||||
|
||||
To learn more about Next.js, take a look at the following resources:
|
||||
生产部署（Docker 镜像、NPM 反代、NEXT_PUBLIC_API_BASE）见仓库根目录 `deploy/README.md`。
|
||||
|
||||
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
|
||||
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
|
||||
## 注意
|
||||
|
||||
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
|
||||
|
||||
## Deploy on Vercel
|
||||
|
||||
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
|
||||
|
||||
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
|
||||
- 本项目是书库前端，**不面向 Vercel 部署**；`NEXT_PUBLIC_API_BASE` 在构建期内联，改后端地址需重新 build。
|
||||
- 阅读器位置优先读服务端 `GET /books/{id}/progress`（跨设备），localStorage 仅作离线兜底。
|
||||
Reference in New Issue
Block a user