참조

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`	파일 형식 분석, DB 변경 없음
`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 체크섬으로 검증.

사용자 로그인은 없습니다. 오직 당신만, 자신의 컴퓨터에서만 서버에 도달할 수 있기 때문입니다.