diff --git a/README.md b/README.md index 4f7b9df..70fe3fb 100644 --- a/README.md +++ b/README.md @@ -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 反代、日常运维与历史数据清理）。 \ No newline at end of file diff --git a/backend/AGENTS.md b/backend/AGENTS.md deleted file mode 100644 index af3b7c8..0000000 --- a/backend/AGENTS.md +++ /dev/null @@ -1,9 +0,0 @@ - - -## 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. - - diff --git a/deploy/README.md b/deploy/README.md index da6b533..993c491 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -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` 表，不会删除它们； + 若丢失先检查是否误清了数据卷或迁移了旧库。 diff --git a/frontend/README.md b/frontend/README.md index e215bc4..86e163f 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -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 仅作离线兜底。 \ No newline at end of file