linuxrebel/DocuBrowser 源码: https://github.com/linuxrebel/DocuBrowser # DocuBrowse v0.9.0 打包为 Linux (RPM, DEB, tarball)、Windows (zip) 和 macOS (dmg)。接口稳定；尽可能避免破坏性变更。 DocuBrowse 能将杂乱无章的文件堆变成真正可搜索的资料库。 将你的文件指向它 —— PDF、电子书、Word 文档、笔记等等 —— 它会构建一个智能索引，不仅能理解关键词，还能理解语义。搜索“那份关于续租的合同“，即使从未出现这些确切的词也能找到。点击任一结果即可在打开文件前获得即时 AI 摘要。支持 PII 识别，可处理多个文档目录。DocuBrowse 完全在你的本地机器上运行，使用本地 AI 模型 —— 无需互联网连接、无需账户、无需 API 密钥，也无需按查询付费消耗 token 预算。你的数据。你的 AI。 底层技术：SQLite FTS5 关键词搜索 + AI 驱动的语义相似度和概要生成（Ollama + nomic-embed-text + dolphin3）。支持多种文档和源代码类型。 — ## 导航 | | | | |—|—|—| | 特性 | 截图 | 快速开始 | | CLI 参考 | 配置 | 架构 | | API 端点 | 搜索算法 | 安全 | | 文件结构 | 故障排除 | 已知限制 | | 近期变更 | | | | 路线图 | AI 辅助开发 | 许可证 | — ## 特性 ↑ 回到顶部 ### 🔍 双重搜索模式 - 关键词搜索 — 通过 SQLite FTS5 进行快速全文搜索（标题、作者、主题、标签、片段） - 语义搜索 — 通过 Ollama 嵌入（nomic-embed-text:latest）进行 AI 驱动的相似度搜索 - 混合模式（默认）— 70% 语义 + 30% 关键词，合并并重新排序 ### 📖 AI 概要 - 点击任意文档标题即可获取类似 Kindle 封底的文档概要，按需通过 Ollama（dolphin3:latest）生成，首次生成后缓存到数据库中。语义搜索嵌入由另一个本地模型（nomic-embed-text:latest）生成 ### 📚 文档索引 - 格式: PDF, DOCX, PPTX, XLSX, EPUB, MOBI, AZW3, AZW, HTML, TXT, Markdown - PDF 智能处理: pdfplumber（首选）配合 pypdf 作为臃肿对象文件的后备；layout=False 重试复杂布局；检测扫描（纯图片）PDF 并将其路由到 ocr_list_pdfs.txt - Word 文档: python-docx 提取段落、表格和核心属性（标题、作者、主题） - 演示文稿: python-pptx 提取幻灯片文本、备注和核心属性 - 电子表格: openpyxl 提取单元格值和工作表名称 - 电子书: 使用 ebooklib 处理 EPUB；使用 mobi 包 + Calibre 后备处理 MOBI/AZW3；DRM 加密的 AZW 文件仅索引元数据（标题/作者可见，正文不可搜索） - 元数据: 从文档元数字段提取标题、作者、主题；根据目录结构和内容关键词自动生成标签 - PII 保护: 摄入后扫描器检测 SSN、信用卡、银行路由/账号、出生日期、病历号、驾照、护照模式；移除匹配的文档并永久将其加入黑名单 ### 🎨 用户界面 - 深色/浅色主题切换 - 分页结果（每页 50 篇文档）带有上/下一页控制 - 字母索引条（A–Z, 0–9）用于快速导航，页面加载后保持状态；首页按钮重置 - 标签云用于按主题过滤 - 每个结果上显示相关度评分徽章（0–100%） - 每个结果卡上的打开按钮 — 通过 xdg-open 在默认应用中打开文件 - 点击文档标题获取 AI 概要；📋 复制路径到剪贴板；🗑 从磁盘和索引中删除文件（需确认） - 已移动/删除的文档：点击一个文件已不存在的文档，如果其文件系统已挂载，则显示可关闭的模态框（关闭时从索引中移除）；如果无法验证文件系统（如已卸载的驱动器），则显示 toast 通知（不修改索引） ### ⚙️ 设置 (/settings) - 通用面板：文档目录（带实时目录浏览器）、任意数量的附加扫描目录（在同一面板下添加/移除 —— 自动包含在 scan/rescan 中，无需额外命令）、工作目录和端口 - 忽略目录面板：浏览添加目录到 ignore_dirs.txt，在清除已索引的文档之前有确认提示，移除条目时也有确认 ### ⚡ 性能 - 搜索延迟：通常 <150ms - 使用 ProcessPoolExecutor 进行并行 PDF 提取（基于物理核心自动确定工作进程数） - 内存安全：内核强制的 RLIMIT_AS（每个工作进程 6 GB）+ 根据空闲 RAM 阈值暂停/恢复 — ## 截图 ↑ 回到顶部 点击缩略图查看完整大小。 | 深色模式 | 浅色模式 | |—|—| | 深色模式 | 浅色模式 | | 设置 | AI 概要 | |—|—| | 设置页面 | 概要模态框 | > 设置是一个独立页面，位于 /settings（通过齿轮图标在新标签页打开）。通用面板涵盖文档目录（带实时目录浏览器，以及任意数量的附加扫描目录）、工作目录和端口；忽略目录面板管理扫描排除项，每个都有目录浏览器、添加/清除控件和移除前的确认。 — ## 快速开始 ↑ 回到顶部 ### 前提条件 - Python 3.9+ - pdfplumber, pypdf — PDF 提取 - python-docx — Word 文档 - python-pptx — PowerPoint 演示文稿 - openpyxl — Excel 电子表格 - ebooklib, beautifulsoup4, mobi — 电子书 - psutil — 跨平台进程和硬件检测 - Calibre — 电子书元数据和转换（需要用于 MOBI/AZW3/AZW 索引）：sudo dnf install calibre 或 sudo apt install calibre - Ollama — 由 docubrowser start 自动安装（如果缺失） - 现代浏览器（Chrome, Firefox, Safari, Edge） 完整的分步指南请参见 INSTALL.md。 ### 安装（推荐） DocuBrowse 提供 RPM、DEB、tarball、Windows zip 和 macOS dmg 包。从 Releases (https://github.com/linuxrebel/DocuBrowser/releases) 页面下载合适的包。 bash # Fedora / RHEL sudo dnf install ./docubrowser-foss-0.9.0-7.noarch.rpm # Debian / Ubuntu / Mint sudo apt install ./docubrowser-foss_0.9.0-7_all.deb # 任何 Linux (tarball) tar xzf docubrowser-foss-0.9.0-7.tar.gz cd docubrowser-foss-0.9.0-7 sudo ./install.sh Windows: 解压 zip，然后双击 Install.bat。需要预装 Python 3.9+ 和 Ollama。安装到 %USERPROFILE%\DocuBrowse 并创建开始菜单快捷方式 —— 无需管理员权限。可能需要注销后重新登录才能看到快捷方式。 macOS: 打开 dmg，然后双击 Install.command（首次使用请右键 → 打开 —— 脚本未经签名）。需要 Python 3.9+。安装到 ~/Applications/DocuBrowse/，包含 Python 虚拟环境、位于 /usr/local/bin/docubrowser 和 /usr/local/bin/docuback 的 CLI 包装器（如果拒绝则回退到 ~/bin/），以及一个 DocuBrowse.app 启动器，用于启动服务器并在终端中打开 Web UI。 所有 Linux 方法都安装到 /opt/docubrowser/，包含 Python 虚拟环境、位于 /usr/bin/docubrowser 和 /usr/bin/docuback 的 CLI 包装器、Office 类别下的桌面菜单项，以及来自 requirements.txt 的所有 Python 依赖。 安装后，CLI 命令是 docubrowser —— 从下方的所有示例中省略 ./ 和 .py。例如 docubrowser start 和 docubrowser rescan。本 README 其余部分中显示的 ./docubrowser.py <command> 形式是开发/克隆仓库的路径（直接从检出目录运行）。 要卸载：sudo dnf remove docubrowser-foss (RPM), sudo apt remove docubrowser-foss (DEB), sudo ./uninstall.sh (tarball), 双击 Uninstall.bat (Windows), 或双击 Uninstall.command (macOS — 在 dmg 上或 ~/Applications/DocuBrowse/ 中)。 ### 首次运行（开发/克隆仓库） bash cd /path/to/DocuBrowse # 扫描并索引你的文档 ./docubrowser.py rescan # 启动服务器 ./docubrowser.py start # 打开 UI ./docubrowser.py open > 在已安装的系统上，请改用 docubrowser 命令，例如 > docubrowser rescan / docubrowser start / docubrowser open。 docubrowser.py start 会自动检查 Ollama 是否已安装、正在运行，并且拥有两个必需的模型 —— nomic-embed-text:latest（嵌入）和 dolphin3:latest（概要生成）—— 根据需要安装/启动/拉取。 — ## CLI 参考 ↑ 回到顶部 用法: docubrowser.py [选项] ### 命令 | 命令 | 描述 | |———|———––| | start | 启动搜索服务器（先运行 Ollama 检查） | | stop | 停止服务器 | | restart | 停止然后启动 | | status | 显示服务器状态、文档计数、嵌入计数、标签计数 | | scan [TYPE ...] | 扫描并索引文档（不生成嵌入） | | rescan [TYPE ...] | 扫描 + 生成嵌入 | | scan-file --file PATH | 提取并索引单个文件，然后对其嵌入 | | embed | 为未嵌入的文档生成/刷新嵌入 | | open | 在默认浏览器中打开 DocuBrowse UI | | purge | 扫描索引中的 PII 并移除匹配的文档 | | ignore add\|remove\|list DIR | 管理排除扫描的目录（添加时自动清除已索引的文档） | | report | 遍历文档目录并显示文件类型分布（不修改数据库） | | scan-missing [--db PATH] [--dry-run] | 可选清理：将每个已索引路径分类为存在/缺失/未挂载，删除 missing 行（级联），保留 unmounted 行不变 | | stopall | 停止所有正在运行的扫描、嵌入和服务器 | | duplist | 列出重复文档（精确 SHA256 + 可选近似重复） | | dupclean | 交互式 TUI 用于审查和移除重复文档 | ### 全局选项 --db PATH SQLite 数据库路径（覆盖配置） --port PORT 服务器端口（覆盖配置） --config FILE 配置文件路径 ### 命令示例 bash # 服务器管理 ./docubrowser.py start ./docubrowser.py start --port 9000 ./docubrowser.py status ./docubrowser.py stop ./docubrowser.py stopall # 扫描 ./docubrowser.py scan # 扫描所有支持的类型 ./docubrowser.py scan pdf # 仅 PDF ./docubrowser.py scan pdf txt # PDF 和纯文本 ./docubrowser.py scan --limit 100 # 仅前 100 个未索引文件 ./docubrowser.py rescan # 扫描 + 嵌入所有类型 ./docubrowser.py rescan pdf --workers 4 # 仅 PDF，4 个工作进程 ./docubrowser.py rescan --no-embed # 扫描但不进行嵌入步骤 ./docubrowser.py rescan --doc-dir /data/docs # 单一文件索引（用于重试被列入黑名单的文件） ./docubrowser.py scan-file --file /path/to/document.pdf ./docubrowser.py scan-file --file /path/with spaces/doc.pdf # 无需引号 ./docubrowser.py scan-file --file /path/to/doc.pdf --no-embed # 报告和维护 ./docubrowser.py report # 文件类型分布，不修改数据库 ./docubrowser.py embed # 嵌入任何未嵌入的文档 ./docubrowser.py purge --dry-run # 预览 PII 匹配（安全） ./docubrowser.py purge # 移除 PII 文档（会提示） # 从扫描中排除目录 ./docubrowser.py ignore add /mnt/data/Documents/myWorkDocs # 排除并清除其下已索引的文档 ./docubrowser.py ignore list # 显示被忽略的目录 ./docubrowser.py ignore remove /mnt/data/Documents/myWorkDocs # 重新允许（重新扫描以重新索引） # 重复检测和清理 ./docubrowser.py duplist # 查找精确 SHA256 重复项 ./docubrowser.py duplist --near-dups # 同时查找近似重复项（余弦相似度 ≥97%） ./docubrowser.py duplist --near-dups --threshold 0.95 ./docubrowser.py dupclean # 交互式 Keep A/Keep B/Keep Both TUI ./docubrowser.py dupclean --near-dups # 在清理中包含近似重复项 # 清理已移动/删除的文档（可选，不会自动运行） ./docubrowser.py scan-missing --dry-run # 仅报告计数，不修改数据库 ./docubrowser.py scan-missing # 删除真正缺失文件的对应行 ### scan / rescan 类型过滤器 类型: pdf txt md html (默认: 全部四种) 示例: rescan pdf 仅 PDF rescan pdf txt PDF 和纯文本 rescan 所有支持的类型 (无过滤时会提示) ### scan-file 详情 scan-file 专为重试单个有问题的文件而设计： - 如果文件在 scan_blacklist.txt 中，则将其移除（显式重试） - 拒绝 pii_blacklist.txt 中的文件（永久 PII 阻止） - 检测扫描（纯图片）PDF → 添加到 ocr_list_pdfs.txt - 带空格的路径无需引号：--file 接受多个 token 并重新连接 — ## 配置 ↑ 回到顶部 DocuBrowse 读取找到的第一个配置文件： 1. /etc/docubrowse.config（系统级） 2. ./docubrowse.config（位于 docubrowser.py 旁边） 如果都不存在，则应用内置默认值 —— 但 doc_dir 除外，它没有默认值。在通过 Web UI 的设置齿轮图标配置文档目录（或通过在 docubrowse.config 中设置 doc_dir）之前，Web UI 会显示一条横幅提示您配置一个目录，而需要文档目录的 CLI 命令（rescan、report、scan）会退出并显示错误，说明如何设置。 ### 配置文件格式 ini # docubrowse.config doc_dir = /mnt/data/Documents db_path = /home/user/DocuBrowse/du-docs.db port = 8643 work_dir = /home/user/DocuBrowse ### 默认值 | 键 | 默认值 | |—–|———| | doc_dir | （无 — 必须通过设置或 docubrowse.config 配置） | | db_path | /du-docs.db | | port | 8643 | | work_dir | <脚本目录> | — ## 架构 ↑ 回到顶部 ┌─────────────────────────────────────┐ │ docubrowser.py (CLI 入口点) │ │ ensure_ollama.py (前提条件检查) │ └──────────┬──────────────────────────┘ │ 子进程 / 直接调用 ↓ ┌──────────────────────┐ ┌─────────────────────────────────┐ │ scan_docs.py │ │ doc_search.py (HTTP :8643) │ │ ProcessPoolExecutor │ │ GET / /api/search │ │ pdf_extractor.py │ │ GET /api/stats /api/tags │ │ embed_docs.py │ │ GET /api/open /api/config │ │ │ GET /api/delete /api/synopsis │ └──────────┬───────────┘ └──────────────┬──────────────────┘ │ │ └──────────┬───────────────────┘ ↓ ┌──────────────────────────────────────────────────┐ │ du-docs.db (SQLite FTS5) │ │ Ollama (nomic-embed-text + dolphin3) │ └──────────────────────────────────────────────────┘ ### 关键脚本 | 脚本 | 角色 | |––––|——| | docubrowser.py | CLI 启动器 —— 所有命令 | | ensure_ollama.py | 检查/安装 Ollama 二进制文件、服务和所需模型 | | doc_search.py | HTTP 服务器；搜索 API 和 UI | | docubrowse_db.py | SQLite 模式和数据迁移 | | platform_paths.py | 跨平台路径解析和进程管理 | | scan_docs.py | 文档发现、提取和数据库写入 | | pdf_extractor.py | PDF 特定提取，使用 pdfplumber/pypdf | | docx_extractor.py | Word 文档提取 (python-docx) | | ebook_extractor.py | EPUB/MOBI/AZW3/AZW 提取 (ebooklib + Calibre) | | hardware_utils.py | CPU/GPU/RAM 检测，工作进程数量公式 | | embed_docs.py | 将文本发送到 Ollama；存储 768 维向量 | | purge_pii.py | 扫描索引中的 PII；移除并加入黑名单 | | dup_detect.py | 精确 (SHA256) 和近似 (余弦相似度) 重复检测 | ### 黑名单文件 | 文件 | 用途 | 永久？ | |——|———|———–| | scan_blacklist.txt | 提取失败的文件 | 否 —— 删除行以重试 | | pii_blacklist.txt | 因包含 PII 而被移除的文件 | 是 —— 永不重新摄入 | | ocr_list_pdfs.txt | 需要 OCR 的纯图片 PDF | 不适用 —— 仅供信息参考 | | ignore_dirs.txt | 排除扫描的目录（通过 ignore 命令管理） | 否 —— ignore remove + rescan | — ## API