參考

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 檢查碼。

沒有使用者登入,因為只有你,在你自己的機器上,才能觸及伺服器。