参考

v1.5.2 的 CLI、配置与安全细节。在已安装的系统上使用 docubrowser;在克隆的仓库中使用 ./docubrowser.py。

命令行界面

docubrowser <command> [options]

命令	说明
`start` / `stop` / `restart`	控制搜索服务器(`start` 会先进行 Ollama 检查)
`status`	服务器状态,文档、嵌入与标签数量
`scan [TYPE ...]`	扫描、索引并嵌入文档。`--no-embed` 跳过嵌入
`rescan [TYPE ...]`	`scan` 的别名
`scan-file --file PATH`	索引单个文件,然后嵌入
`embed`	为未嵌入的文档生成嵌入
`open`	在默认浏览器中打开 UI
`purge`	扫描索引中的 PII 并移除匹配文档
`ignore add\|remove\|list DIR`	管理排除目录(添加时自动清除)
`report`	文件类型统计,不改动数据库
`scan-missing [--dry-run]`	移除真正缺失文件的记录;保留未挂载的路径
`stopall`	停止所有扫描、嵌入与服务器
`duplist` / `dupclean`	列出重复 / 交互式查看并移除

全局选项

--db PATH      SQLite 数据库路径(覆盖配置)
--port PORT    服务器端口(覆盖配置)
--config FILE  配置文件路径

示例

docubrowser start --port 9000
docubrowser scan pdf txt              # 仅 PDF 和纯文本
docubrowser scan --limit 100          # 未索引的前 100 个文件
docubrowser scan --workers 4          # 4 个提取工作进程
docubrowser scan-file --file /path/to/document.pdf
docubrowser purge --dry-run           # 预览 PII 匹配(安全)
docubrowser ignore add ~/Documents/myWorkDocs
docubrowser duplist --near-dups --threshold 0.95
docubrowser scan-missing --dry-run

scan 的类型过滤器:pdf、txt、md、html;默认是所有支持的类型。

scan-file 用于重试有问题的文件:它会从 scan_blacklist.txt 中移除该文件,拒绝 pii_blacklist.txt 中的文件,并把扫描件 PDF 送入 ocr_list_pdfs.txt。

配置

DocuBrowse 读取它找到的第一个配置文件:/etc/docubrowse.config,然后是 docubrowser.py 旁边的 ./docubrowse.config。

# docubrowse.config
doc_dir      = ~/Documents
db_path      = /home/user/DocuBrowse/du-docs.db
port         = 8643
work_dir     = /home/user/DocuBrowse
lang         = en

键	默认
`doc_dir`	无。必须通过 Settings 或配置文件设置
`db_path`	`<script dir>/du-docs.db`
`port`	`8643`
`work_dir`	`<script dir>`
`lang`	`en`(也可 `ja`、`ko`、`zh`、`zh-hant`)

环境变量

环境变量会覆盖对应的配置键。CLI 标志仍然优先。

变量	说明
`DOCUBROWSE_DOC_DIR`	主要文档目录
`DOCUBROWSE_DB` / `DOCUBROWSE_DB_PATH`	`du-docs.db` 的路径
`DOCUBROWSE_PORT`	HTTP 端口(默认 8643)
`DOCUBROWSE_WORK_DIR`	运行时数据的工作目录
`OLLAMA_HOST`	Ollama 基础 URL(默认 `http://localhost:11434`);也可用 `DOCUBROWSE_OLLAMA_HOST`

架构

docubrowser.py (CLI)  ──►  scan_docs.py (ProcessPoolExecutor, extractors, embed_docs.py)
ensure_ollama.py            doc_search.py (HTTP :8643)
                                   │                   │
                                   └────────┬──────────┘
                                            ▼
                         du-docs.db (SQLite FTS5)  +  Ollama
                         (nomic-embed-text, dolphin3)

关键词评分使用 FTS5 BM25,标题和作者的权重高于正文和标签。语义评分比较查询嵌入与各文档嵌入。混合模式为每份文档取两者中较强的分数。完整算法见 README。

安全

DocuBrowse 绑定到 127.0.0.1,面向单用户本地使用。它经过加固,使你访问的恶意网页无法触及它:

Host 头允许列表可挫败 DNS 重绑定。
对每个更改状态的操作使用 CSRF 令牌,外加回环 Origin/Referer 检查。
无存储数据注入:文档字段经 HTML 转义,卡片操作使用委托监听器而非内联处理程序。
经过验证的 PII 清除:SSN 对照 SSA 分配规则,银行卡按长度、发卡机构前缀与 Luhn,路由号按 ABA 校验和。

没有用户登录,因为只有你,在你自己的机器上,才能触及服务器。