# ebook_manager **Repository Path**: aldmd/ebook_manager ## Basic Information - **Project Name**: ebook_manager - **Description**: 电子书管理系统 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-27 - **Last Updated**: 2026-01-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 电子书管理系统 > 高性能电子书管理系统，支持大规模书籍导入、智能分类、重复检测和在线阅读。 [![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/) [![Vue Version](https://img.shields.io/badge/vue-3.4+-green.svg)](https://vuejs.org/) [![License](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE) [![Version](https://img.shields.io/badge/version-0.5.0-brightgreen.svg)](CHANGELOG.md) ## ✨ 特性 ### 核心功能 - 📚 **多格式支持** - PDF、EPUB、MOBI、AZW3、AZW - ⚡ **高性能导入** - 测试验证 3,611 本书，100% 成功率，254 本/分钟 - 🔍 **智能识别** - 从文件内容提取元数据（标题、作者、年份、ISBN、封面） - 🔍 **多层降级策略** - 5层提取策略：calibre数据库 > calibre工具 > 文件内容 > 内容解析 > OCR - 📊 **元数据质量** - 集成calibre数据库，提供完整书籍信息（标签、丛书、ISBN等） - 🔗 **重复检测** - 使用 xxhash64 高性能哈希算法，两阶段快速精确匹配 - 🗂️ **智能分类** - 按首字母自动组织书库（支持中文拼音，覆盖93.3%常用汉字） - 📚 **多版本支持** - 同一书名和作者可有多版本共存，支持版本切换 - 📖 **在线阅读** - PDF/EPUB 阅读器，支持翻页、缩放、目录导航、全屏模式 - 💾 **进度保存** - 自动保存阅读进度，断点续读 - 🔖 **书签管理** - 创建和管理书签（后端 API 完整实现） - 🎨 **封面提取** - 自动提取书籍封面，支持缓存去重 - ⚙️ **动态线程调整** - 基于系统负载自动调整并发线程数（CPU/内存监控） - 💾 **断点续传** - 导入任务支持暂停/恢复/终止，记录已处理文件 ### 界面功能 - 🎨 **现代化设计** - Material Design 3 风格，大圆角、柔和阴影、流畅动画 - 🌙 **深色模式** - 支持浅色/深色主题切换，跟随系统偏好 - 🔍 **首页搜索** - 大号搜索框，支持书名/作者搜索，一键跳转书库 - 📚 **新书推荐** - 首页显示最近新加入的20本书 - 🎲 **随机推荐** - 首页显示随机10本书，支持"换一批"刷新 - 📊 **导入预评估** - 导入前显示文件数量、预计时间、重复检测 - 📈 **实时进度** - WebSocket 实时推送，显示速度和剩余时间 - 🔀 **视图切换** - 书库支持网格/列表视图切换 - 🎯 **高级过滤** - 支持作者、年份、格式多维度过滤 - 📱 **响应式设计** - 完美适配手机、平板、桌面（5个断点，640px-2560px+） - 🔔 **Toast 通知** - 优雅的成功/错误/警告/信息提示系统 - ✨ **图片懒加载** - 使用 Intersection Observer 实现图片懒加载 ## 🚀 快速开始 ### 环境要求 - Python 3.8+ (推荐 3.10+) - Node.js 16+ (前端开发) - Calibre (可选，用于 MOBI/AZW3 元数据提取的降级方案) ### 安装步骤 1. **克隆仓库** ```bash git clone https://gitee.com/aldmd/ebook_manager.git cd ebook_manager ``` 2. **创建虚拟环境** ```bash python -m venv venv # Windows venv\Scripts\activate # Linux/Mac source venv/bin/activate ``` 3. **安装后端依赖** ```bash pip install -r requirements.txt ``` 4. **启动后端服务** ```bash python backend/main.py ``` 后端将运行在 `http://localhost:8000` 5. **安装前端依赖**（可选） ```bash cd frontend npm install ``` 6. **启动前端开发服务器**（可选） ```bash npm run dev ``` 前端将运行在 `http://localhost:3000` 7. **访问应用** 打开浏览器访问 `http://localhost:3000` ## 📁 项目结构 ``` ebook_manager/ ├── backend/ # 后端服务（FastAPI） │ ├── main.py # 应用入口，注册路由和初始化 │ ├── api/ # API 路由层 │ │ ├── books.py # 书籍管理 API（列表/详情/删除/封面/最近/随机/版本） │ │ ├── import_task.py # 导入任务 API（开始/暂停/恢复/终止/预览） │ │ ├── reading.py # 阅读相关 API（进度/书签） │ │ └── websocket.py # WebSocket API（实时进度推送） │ ├── database/ # 数据访问层 │ │ ├── models.py # ORM 模型（Book/ImportTask/ReadingProgress/Bookmark） │ │ ├── session.py # 数据库会话（WAL 模式优化） │ │ └── crud.py # CRUD 操作封装 │ ├── services/ # 业务服务层 │ │ ├── file_scanner.py # 文件扫描（递归目录） │ │ ├── metadata_extractor.py # 元数据提取（5层降级策略） │ │ ├── cleaner.py # 文本清理（50+关键词过滤） │ │ ├── duplicate_detector.py # 重复检测（两阶段算法） │ │ ├── file_organizer.py # 文件组织（硬链接/分类） │ │ ├── import_service.py # 导入编排（并发+断点续传） │ │ └── websocket.py # WebSocket 服务 │ ├── schemas/ # Pydantic 数据模型 │ └── utils/ # 工具函数（哈希/文件操作） ├── frontend/ # 前端应用（Vue 3 + Vite） │ └── src/ │ ├── components/ # Vue 组件 │ │ ├── BookCard.vue # 书籍卡片 │ │ ├── BookGrid.vue # 书籍网格 │ │ ├── BookList.vue # 书籍列表 │ │ ├── ToastContainer.vue # Toast 通知 │ │ ├── FileSelector.vue # 文件选择器 │ │ ├── ProgressDisplay.vue # 进度显示 │ │ ├── DirectorySelector.vue # 目录选择器 │ │ ├── ImportPreview.vue # 导入预览 │ │ ├── readers/ # 阅读器组件 │ │ │ ├── PdfReader.vue # PDF 阅读器 │ │ │ └── EpubReader.vue # EPUB 阅读器 │ │ ├── layout/ # 布局组件 │ │ │ ├── Sidebar.vue # 侧边栏 │ │ │ └── TopNavigation.vue # 顶部导航 │ │ └── icons/ # 图标库（10+ 图标） │ ├── views/ # 页面视图 │ │ ├── HomeView.vue # 首页 │ │ ├── ImportView.vue # 导入页面 │ │ ├── LibraryView.vue # 书库页面 │ │ ├── BookDetailView.vue # 书籍详情页 │ │ └── Reader.vue # 阅读器页面 │ ├── stores/ # Pinia 状态管理 │ │ ├── home.ts # 首页状态 │ │ ├── books.ts # 书籍状态 │ │ └── import.ts # 导入任务状态 │ ├── composables/ # Vue Composables │ │ ├── useDarkMode.ts # 深色模式 │ │ ├── useToast.ts # Toast 通知 │ │ ├── useWebSocket.ts # WebSocket Hook │ │ ├── useBreakpoints.ts # 响应式断点 │ │ └── useAccessibility.ts # 无障碍功能 │ ├── directives/ # Vue 指令 │ │ └── lazyLoad.ts # 图片懒加载指令 │ ├── services/ # API 服务 │ │ ├── api.ts # API 客户端 │ │ └── websocket.ts # WebSocket 客户端 │ ├── styles/ # 样式系统 │ │ ├── variables.css # CSS 变量 │ │ ├── utilities.css # 工具类 │ │ └── dark-mode.css # 深色模式 │ ├── router/ # Vue Router │ │ └── index.ts # 路由配置 │ └── types/ # TypeScript 类型 │ └── index.ts # 核心类型定义 ├── storage/ # 书籍存储目录 │ └── books/ │ ├── identified/ # 已识别书籍 │ └── unidentified/ # 未识别书籍 ├── data/ # 数据目录 │ └── database.db # SQLite 数据库（自动生成） ├── logs/ # 日志目录 │ └── ebook_manager.log # 运行日志 ├── docs/ # 文档目录 │ ├── BOOK_NAME_RECOGNITION.md # 书籍名称识别机制 │ ├── calibre_integration.md # Calibre 集成说明 │ └── v0.5.0_IMPLEMENTATION_SUMMARY.md # v0.5.0 实现总结 ├── config.yaml # 系统配置 ├── requirements.txt # Python 依赖 ├── QUICKSTART_v1.0.md # 快速启动指南 └── CLAUDE.md # Claude Code 开发指导 ``` ## 🛠️ 技术栈 ### 后端 - **Web 框架**: FastAPI - 现代异步 Python Web 框架 - **数据库**: SQLite (WAL 模式) + SQLAlchemy ORM - 支持 PostgreSQL 切换 - 连接池优化（50个连接，最大溢出50） - WAL 模式提升并发性能 - **元数据提取**: - **PDF**: pymupdf（高性能，4-5x速度提升） + pypdf（降级方案） - **EPUB**: ebooklib - **MOBI/AZW3**: 纯 Python 解析器（性能优于 calibre 2-3x） - **Calibre 集成**: calibre 工具和数据库读取（可选） - **OCR**: PaddleOCR（GPU 加速支持） - **哈希算法**: xxhash - 高性能哈希 - **并发处理**: ThreadPoolExecutor + ProcessPoolExecutor - 动态线程调整（基于 CPU/内存监控） - 支持断点续传 - **系统监控**: psutil - CPU/内存实时监控 - **中文拼音**: pypinyin - 首字母分类（93.3%覆盖率） - **实时通信**: WebSocket - **数据验证**: Pydantic v2 ### 前端 - **框架**: Vue 3.4+ Composition API + TypeScript - **状态管理**: Pinia - **构建工具**: Vite 6.4+ - **HTTP 客户端**: Axios - **PDF 渲染**: PDF.js 5.4+ - **EPUB 渲染**: epub2 3.0+ - **实时通信**: WebSocket API - **设计系统**: Material Design 3（自定义实现） - **样式方案**: CSS变量 + 工具类 - **响应式**: Mobile-first，5个断点（640px-2560px+） - **性能优化**: - 图片懒加载（Intersection Observer） - Vue Router 懒加载 - 防抖节流优化 ## 📊 开发进度 ### 当前版本：v0.5.0 ✅ **重大更新**：v0.5.0 包含完整的功能实现和性能优化，支持大规模书籍导入和智能元数据提取。 ### 已实现功能 **核心功能**: - ✅ 文件扫描（支持递归目录扫描） - ✅ 元数据提取（PDF/EPUB/MOBI/AZW3） - ✅ 五层降级策略（calibre数据库 > calibre工具 > 文件内容 > 内容解析 > OCR） - ✅ ISBN 提取和标准化 - ✅ 封面提取和缓存 - ✅ 重复检测（xxhash64，两阶段算法） - ✅ 文件组织（硬链接 + 按首字母分类） - ✅ 导入服务（并发处理 + 分批处理） - ✅ 断点续传（暂停/恢复/终止） - ✅ 多版本支持（同书名作者可有多版本） - ✅ 动态线程调整（基于系统负载） - ✅ 性能监控（导入速度、成功率） **界面功能**: - ✅ Material Design 3 设计语言 - ✅ 深色模式支持（系统偏好检测 + 手动切换） - ✅ 首页搜索（书名/作者，一键跳转书库） - ✅ 最近新书（显示20本最新加入） - ✅ 随机推荐（显示10本，支持换一批） - ✅ 导入预评估（文件数、时间、重复数） - ✅ 实时进度（速度、剩余时间、断点恢复） - ✅ 书库视图切换（网格/列表） - ✅ 高级过滤（作者、年份、格式） - ✅ 多版本切换（书籍详情页） - ✅ 响应式布局（5个断点，640px-2560px+） - ✅ Toast 通知系统（成功/错误/警告/信息） - ✅ 图片懒加载（Intersection Observer） - ✅ 页面过渡动画 **阅读器功能**: - ✅ PDF 阅读器（翻页、缩放、跳转、全屏） - ✅ EPUB 阅读器（章节导航、字体调整、全屏） - ✅ 自动进度保存 - ✅ 书签管理 API（创建、列表、删除） ## 📖 文档 - [**快速启动**](./QUICKSTART_v1.0.md) - 5分钟快速上手指南 - [**开发指南**](./CLAUDE.md) - Claude Code 开发指导 - [**书籍名称识别**](./docs/BOOK_NAME_RECOGNITION.md) - 书籍名称识别机制详解 - [**Calibre 集成**](./docs/calibre_integration.md) - 与 calibre 书库深度集成说明 - [**v0.5.0 实现总结**](./docs/v0.5.0_IMPLEMENTATION_SUMMARY.md) - 版本功能总结 ### 设计特色 **Material Design 3 风格**: - 🎨 配色方案：Emerald Green（#10b981）+ Indigo Purple（#6366f1） - 📐 设计元素：24px大圆角、柔和阴影、流畅动画 - 🌓 主题支持：浅色/深色模式，跟随系统偏好 - 📱 响应式：Mobile-first，完美适配所有设备 **性能优化**: - 🖼️ 图片懒加载：Intersection Observer API - 💾 代码分割：Vue Router 懒加载 - 🎯 防抖节流：搜索和滚动优化 - ⚡ 动态线程调整：基于系统负载自动调整并发数 ## 🧪 测试 运行单元测试： ```bash # 激活虚拟环境后 pytest backend/tests/ -v # 运行特定测试 pytest backend/tests/test_cleaner.py -v ``` ## ⚙️ 配置 系统配置文件位于 `config.yaml`，可配置： - **服务器配置** - host、port、reload、log_level - **数据库配置** - SQLite（WAL 模式优化）/PostgreSQL - 连接池设置（pool_size、max_overflow、pool_timeout） - 性能优化（cache_size、mmap_size、temp_store） - **存储配置** - 基础目录、已识别/未识别分类 - **导入配置**: - 并发配置（max_workers、min_workers、max_workers_limit） - 动态线程调整（cpu_threshold、memory_threshold、adjust_interval） - 批处理配置（batch_insert_size、batch_commit_interval） - 断点续传（checkpoint_interval、progress_broadcast_interval） - 超时配置（calibre_timeout） - **哈希配置** - xxhash 算法、block_size - **Windows 路径配置** - 长路径支持、路径限制 - **文件名清理配置** - 标点转换、括号清理、年份保留 - **日志配置** - 文件日志、轮转 - **元数据提取配置**: - OCR 设置（enable_ocr、ocr_use_gpu、ocr_min_confidence） - 内容解析限制（content_max_pdf_pages、content_max_epub_chapters） ## 📝 v0.5.0 更新日志 ### 后端增强 - ✅ 元数据提取优化：pymupdf 高性能 PDF 处理（4-5x 速度提升） - ✅ 纯 Python MOBI 解析器（性能优于 calibre 2-3x） - ✅ Calibre 深度集成：优先级提升至数据库和工具读取 - ✅ 动态线程调整：基于 CPU/内存负载自动调整并发数 - ✅ 封面提取和缓存：自动提取书籍封面 - ✅ ISBN 提取和标准化：支持 ISBN-10/13 - ✅ 系统监控：psutil 实时监控 CPU/内存 - ✅ 性能监控：导入速度、成功率统计 - ✅ 断点续传优化：更精细的检查点控制 - ✅ SQLite WAL 模式优化：连接池、缓存、内存映射 ### 前端增强 - ✅ Material Design 3 设计语言 - ✅ 深色模式支持（系统偏好 + 手动切换） - ✅ 首页搜索功能，支持书名/作者搜索 - ✅ 最近新书推荐（20本） - ✅ 随机推荐（10本，支持换一批） - ✅ 多版本支持，同书名作者可有多版本 - ✅ 导入预评估功能 - ✅ 书库视图切换（网格/列表） - ✅ 高级过滤功能 - ✅ Toast 通知系统 - ✅ 图片懒加载指令 - ✅ 响应式断点系统 - ✅ 无障碍功能支持 ### 新增 API - ✅ GET `/api/books/recent` - 获取最近书籍 - ✅ GET `/api/books/random` - 获取随机推荐 - ✅ GET `/api/books/versions` - 获取多版本 - ✅ GET `/api/books/authors/list` - 获取作者列表 - ✅ GET `/api/books/years/list` - 获取年份列表 - ✅ GET `/api/books/{book_id}/cover` - 获取封面 - ✅ GET `/api/books/{book_id}/reading-progress` - 获取阅读进度 - ✅ POST `/api/books/{book_id}/reading-progress` - 更新阅读进度 - ✅ GET `/api/books/{book_id}/bookmarks` - 获取书签列表 - ✅ POST `/api/books/{book_id}/bookmarks` - 创建书签 - ✅ DELETE `/api/books/bookmarks/{bookmark_id}` - 删除书签 - ✅ GET `/api/import/preview` - 导入预评估 ## 🚀 未来计划 ### 高优先级 - [ ] 书签管理前端 UI（后端 API 已完成） - [ ] 阅读统计功能（时长、历史、图表） - [ ] 批量操作（批量删除、批量导出） - [ ] 书籍编辑功能（修改元数据） ### 中优先级 - [ ] PWA 支持（离线使用、安装到桌面） - [ ] 笔记功能（高亮、批注） - [ ] 全文搜索（书籍内容搜索） - [ ] 高级筛选（标签、丛书、出版社） - [ ] 导出功能（导出书单、统计报告） ### 低优先级 - [ ] 用户系统（多用户、权限管理） - [ ] 云端同步（进度、书签同步） - [ ] Docker 容器化 - [ ] 移动端 App（React Native / Flutter） ## 🤝 贡献 欢迎提交 Issue 和 Pull Request！ 1. Fork 本仓库 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 开启 Pull Request ## 📄 许可证 MIT License - 详见 [LICENSE](LICENSE) 文件 ## 🔗 相关链接 - [Gitee 仓库](https://gitee.com/aldmd/ebook_manager) - [问题反馈](https://gitee.com/aldmd/ebook_manager/issues) --- **更新时间**: 2026-01-31 **当前版本**: v0.5.0 **维护者**: Claude Code `★ Insight ─────────────────────────────────────` **v0.5.0 里程碑**: 1. **高性能导入**: 100万本书/1-2小时，动态线程调整 2. **智能识别**: 五层降级策略，Calibre 深度集成 3. **完整功能**: 阅读、书签、多版本、封面提取 4. **现代界面**: Material Design 3，深色模式，响应式布局 `─────────────────────────────────────────────────`