Paperless-ngx: 종이 문서를 검색 가능한 지식 자산으로 바꾸는 오픈소스 DMS

종이 문서를 스캔해서 폴더에 쌓아두는 방식은, 디지털화가 아니라 단순한 “파일 덤프”에 가깝습니다. 진짜 필요한 건 PDF를 저장하는 도구가 아니라, 문서 안의 텍스트를 읽고, 분류하고, 다시 찾아낼 수 있게 만드는 시스템입니다. Paperless-ngx는 바로 그 지점을 겨냥한 프로젝트입니다. 스캔한 영수증, 계약서, 고지서, 세금 문서를 그냥 보관하는 수준을 넘어서, OCR·인덱싱·자동 분류·검색까지 하나의 파이프라인으로 묶어줍니다. (GitHub)

이 프로젝트가 흥미로운 이유는 “문서 보관함”처럼 보이지만, 실제로는 꽤 잘 설계된 비동기 문서 처리 플랫폼에 가깝기 때문입니다. Docker Compose로 비교적 쉽게 올릴 수 있고, 백엔드는 Django 기반, 작업 처리는 Celery와 Redis, 프런트엔드는 Angular로 구성되어 있습니다. 최근 코드 기준으로는 Python 3.11 이상과 Django 5.2 계열, Angular 21 계열을 사용하고 있습니다. (docs.paperless-ngx.com)

 

GitHub - paperless-ngx/paperless-ngx: A community-supported supercharged document management system: scan, index and archive all

 

프로젝트 소개

Paperless-ngx는 물리 문서를 스캔하거나 이메일 첨부파일, 업로드 파일 형태로 받아서 검색 가능한 온라인 아카이브로 바꿔주는 오픈소스 문서 관리 시스템입니다. 원래의 Paperless와 Paperless-ng를 잇는 공식 후속 프로젝트이며, 커뮤니티 중심으로 발전하는 구조를 지향합니다. 문서는 태그, 발신처, 문서 타입 같은 메타데이터로 정리할 수 있고, OCR을 통해 이미지 기반 문서도 텍스트 검색이 가능해집니다. 또한 원본 파일을 보존하면서 장기 보관용 PDF/A 아카이브도 함께 생성합니다. (GitHub)

개발 환경 관점에서 보면 이 프로젝트는 “셀프호스팅 문서 인프라”에 가깝습니다. 가장 쉬운 배포 경로는 Docker Compose이며, 신규 설치에는 PostgreSQL 사용이 권장됩니다. 주기 작업과 비동기 처리를 위해 Redis가 필요하고, Office 문서 처리를 확장하려면 Gotenberg와 Tika 기반 구성을 추가할 수 있습니다. REST API도 기본 제공하므로 개인용 아카이브를 넘어서 내부 업무 자동화 시스템의 한 축으로 붙이기 좋습니다. (docs.paperless-ngx.com)

왜 이 프로젝트가 등장했을까

많은 팀과 개인이 문서를 디지털화한다고 말하지만, 실제 운영은 보통 두 가지 문제에 막힙니다.

첫째, “저장”과 “검색”은 다른 문제입니다. 폴더 구조만으로는 몇 년 뒤 특정 계약서나 특정 거래처의 인보이스를 빠르게 찾기 어렵습니다. 문서 안의 내용을 읽고 인덱싱해야 비로소 아카이브가 됩니다. Paperless-ngx는 이 지점에서 OCR과 인덱싱을 기본 흐름으로 두고 있습니다. (docs.paperless-ngx.com)

둘째, 문서 유입 경로가 너무 제각각입니다. 스캐너에서 오는 PDF, 휴대폰으로 찍은 이미지, 이메일 첨부파일, 수동 업로드 파일이 뒤섞이는데, 사람이 일일이 이름을 바꾸고 폴더를 나누는 방식은 금방 한계에 도달합니다. Paperless-ngx는 소비 디렉터리, 웹 업로드, 이메일 소비 기능을 제공하고, 처리 전에 OCR과 자동 매칭을 수행해 이 문제를 파이프라인으로 흡수합니다. (docs.paperless-ngx.com)

셋째, 기존 셀프호스팅 문서 관리 도구는 설치가 어렵거나 자동화 확장성이 약한 경우가 많았습니다. Paperless-ngx는 설치 스크립트와 Docker Compose 중심의 배포 경로를 제공하고, API·백업 exporter·자동 분류·워크플로 같은 기능을 계속 확장해 왔습니다. 최근 변경 내역에도 워크플로, UI에서의 백엔드 설정, 메일 처리 개선 같은 기능이 포함되어 있습니다. (docs.paperless-ngx.com)

핵심 기능

1) OCR 기반 검색 가능한 아카이브

이 프로젝트의 핵심은 문서를 “파일”이 아니라 “검색 가능한 데이터”로 다룬다는 점입니다. 이미지 기반 스캔 문서에도 OCR을 적용해 선택 가능한 텍스트를 추가하고, 100개 이상의 언어를 지원하는 Tesseract를 활용합니다. 결과적으로 사용자는 파일명을 기억하지 못해도 본문 키워드로 문서를 찾을 수 있습니다. (docs.paperless-ngx.com)

2) 원본 보존 + PDF/A 아카이브 생성

문서 관리 시스템에서 자주 놓치는 부분이 원본 보존입니다. Paperless-ngx는 소비한 원본 문서를 덮어쓰지 않고 보관하며, 별도로 장기 보관에 적합한 PDF/A 버전을 생성할 수 있습니다. 즉 “법적/감사적 원본 보존”과 “검색·뷰잉 최적화”를 분리하는 설계입니다. (docs.paperless-ngx.com)

3) 자동 분류와 자동 매칭

태그, 발신처, 문서 타입, 보관 경로에 대해 여러 매칭 알고리즘을 지원합니다. Exact, Any, All, 정규식, Fuzzy match는 물론, 기존 문서 학습 결과를 바탕으로 분류하는 Auto 매칭도 제공합니다. 문서가 충분히 쌓이면 “이건 통신요금 청구서”, “이건 특정 카드사 명세서” 같은 분류를 사람이 일일이 하지 않아도 됩니다. (docs.paperless-ngx.com)

4) 다양한 입력 채널

문서는 소비 디렉터리에 파일을 떨어뜨리는 방식으로 가장 쉽게 넣을 수 있고, 이메일 계정을 연결해 첨부파일을 자동 수집할 수도 있습니다. 메일 규칙을 기반으로 필터링, 읽음 처리, 이동 같은 후속 액션도 설정 가능합니다. 운영 관점에서는 스캐너-공유폴더-소비 디렉터리 조합이나, 이메일 인보이스 자동 수집이 특히 실용적입니다. (docs.paperless-ngx.com)

5) API와 자동화 친화성

REST API가 기본 제공되고, 브라우저에서 API 스키마를 탐색할 수 있습니다. 인증도 Basic, Session, Token 등 여러 방식을 지원합니다. 그래서 별도 업로더, 회계 시스템 연동, 사내 챗봇 연계 같은 자동화 시나리오에 붙이기 쉽습니다. (docs.paperless-ngx.com)

6) 백업/마이그레이션 고려

문서 관리 시스템은 넣는 것보다 빼는 것이 더 중요합니다. Paperless-ngx는 document exporter를 통해 문서, 썸네일, 메타데이터, DB 내용을 내보낼 수 있고, 증분 백업에도 활용할 수 있습니다. 셀프호스팅에서 자주 걱정되는 벤더 종속성 문제를 어느 정도 완화하는 지점입니다. (docs.paperless-ngx.com)

프로젝트 아키텍처 분석

이 프로젝트를 개발자 시각으로 보면, “문서 수집 → 비동기 처리 → OCR/변환 → 메타데이터 추출/자동 분류 → 저장/인덱싱 → 검색/관리”로 이어지는 파이프라인입니다. Docker 배포 시 Redis는 스케줄링과 비동기 작업 전달에 쓰이고, 작업 프로세서는 Celery 워커로 동작합니다. 백엔드는 Django 애플리케이션이고, 프런트엔드는 Angular SPA입니다. 선택적으로 Gotenberg/Tika를 붙여 Office 문서 변환과 텍스트 추출 범위를 넓힐 수 있습니다. (docs.paperless-ngx.com)

조금 더 현실적으로 풀어보면 이렇습니다.

문서가 들어오면 Paperless-ngx는 먼저 이 파일이 텍스트를 이미 포함하는지, 이미지 스캔인지 판단합니다. 텍스트가 없다면 OCR을 수행하고, 이후 PDF/A 아카이브를 생성합니다. 그 다음 문서 본문과 파일명, 설정된 규칙을 바탕으로 태그/발신처/문서 타입을 자동 매칭하고 DB와 검색 인덱스에 저장합니다. 사용자는 Angular UI에서 결과를 검토하고 수정하거나, API를 통해 후속 시스템과 연결합니다. (docs.paperless-ngx.com)

내부 구조를 코드/저장소 관점에서 보면

저장소 루트에는 src와 src-ui가 분리되어 있습니다. src 아래에는 documents, paperless, paperless_mail, paperless_tesseract, paperless_tika, paperless_text, paperless_remote, paperless_ai 같은 모듈이 보입니다. 이 구조만 봐도 문서 도메인, 메일 수집, OCR, 텍스트 추출, 원격 입력, AI 확장 기능을 비교적 명확하게 분리하려는 의도가 드러납니다. 반면 src-ui는 Angular 기반 프런트엔드 앱으로 관리됩니다. (GitHub)

특히 흥미로운 부분은 최근 의존성 목록입니다. 단순한 OCR 보관 도구를 넘어, Celery·channels·DRF·Whoosh 계열 검색·OCRMyPDF·Tika·Gotenberg뿐 아니라 FAISS, sentence-transformers, llama-index, OpenAI, Ollama 관련 패키지까지 포함되어 있습니다. 즉 Paperless-ngx는 전통적인 DMS 위에 AI 검색/임베딩 확장 가능성을 올려놓는 방향으로도 진화하고 있다고 볼 수 있습니다. 다만 이 영역은 기능 범위가 넓어지는 만큼 운영 복잡도도 함께 올라갑니다. (GitHub)

언제 쓰면 좋은가

잘 맞는 경우

개인 아카이브 용도로는 세금 문서, 보험 서류, 병원 영수증, 계약서, 매뉴얼 같은 문서를 장기 보관하고 싶을 때 매우 잘 맞습니다. 로컬 서버에 저장되고 외부 전송 없이 관리된다는 점도 매력입니다. (docs.paperless-ngx.com)

소규모 팀이라면 회계/법무/운영 문서를 중앙에서 관리하는 용도로 적합합니다. 특히 이메일 첨부 인보이스 수집, 스캐너 기반 입고 문서 처리, API 연동 자동화가 필요한 팀에게 유용합니다. 워크플로 기능과 API는 이런 운영 자동화와 잘 맞습니다. (docs.paperless-ngx.com)

덜 맞는 경우

반대로 강한 엔터프라이즈 보안 요구사항, 문서 자체 암호화, 복잡한 승인 워크플로, 대규모 ECM 수준의 거버넌스가 필요하다면 보완 설계가 필요합니다. 프로젝트 README도 민감 문서가 평문으로 저장되므로 신뢰할 수 없는 호스트에 두지 말라고 명시하고 있습니다. 즉 보안 모델은 “인터넷 서비스”보다 “신뢰 가능한 내부 셀프호스팅”에 더 가깝습니다. (GitHub)

빠르게 시작하는 예시

가장 일반적인 진입점은 Docker Compose입니다. 공식 문서는 설치 스크립트와 Compose 파일 기반 설치를 안내하고, 신규 설치에는 PostgreSQL을 권장합니다. (docs.paperless-ngx.com)

bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

조금 더 운영 친화적으로 보자면, 핵심은 “consume 디렉터리”를 잘 연결하는 것입니다.

services:
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    depends_on:
      - redis
      - db
    ports:
      - "8000:8000"
    volumes:
      - ./consume:/usr/src/paperless/consume
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
    env_file:
      - docker-compose.env

  redis:
    image: redis:7

  db:
    image: postgres:16

이 구성을 이해하는 핵심 포인트는 세 가지입니다.

consume은 입력 버퍼입니다. 스캐너가 여기로 파일을 넣거나, 다른 시스템이 복사해 넣습니다.
media는 실제 보관소입니다. 원본과 아카이브된 문서가 이쪽으로 관리됩니다.
export는 백업/마이그레이션 출구입니다. (docs.paperless-ngx.com)

API 활용 예시

업무 자동화 측면에서는 문서 업로드 API를 붙이는 순간 활용도가 커집니다. 공식 API 문서는 토큰 인증을 지원합니다. (docs.paperless-ngx.com)

curl -X POST "http://localhost:8000/api/token/" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'

토큰을 발급받았다면, 사내 시스템에서 PDF 생성 후 업로드하는 흐름을 구성할 수 있습니다.

import requests

BASE_URL = "http://localhost:8000"
TOKEN = "YOUR_TOKEN"

with open("invoice.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/api/documents/post_document/",
        headers={"Authorization": f"Token {TOKEN}"},
        files={"document": f},
        data={
            "title": "2026-03 Hosting Invoice",
        },
        timeout=60,
    )

print(response.status_code, response.text)

이런 방식은 ERP, 회계 시스템, 이메일 파서, 슬랙 봇과 연결할 때 특히 유용합니다. Paperless-ngx를 단순 저장소가 아니라 “문서 ingestion API”로 바라보면 활용 범위가 훨씬 넓어집니다. (docs.paperless-ngx.com)

실전 운영 시나리오

가장 전형적인 시나리오는 이렇습니다.

1. 복합기 스캐너가 SMB/FTP 공유 폴더에 PDF를 저장합니다.
2. 그 폴더를 consume 디렉터리에 연결합니다.
3. Paperless-ngx가 문서를 감지해 OCR과 PDF/A 생성을 수행합니다.
4. 문서 본문에 들어 있는 거래처명, 계좌번호, 문서 패턴을 기준으로 자동 매칭합니다.
5. 사용자는 UI에서 몇 번만 교정해 주고, 이후부터는 Auto 매칭이 점점 더 잘 동작합니다. (docs.paperless-ngx.com)

이메일 기반 시나리오도 강력합니다. 카드 명세서, 전자세금계산서, SaaS 청구서처럼 원래 이메일 첨부로 오는 문서는 메일 계정과 규칙만 잘 정의하면 거의 무인으로 축적할 수 있습니다. 사람 손이 개입하는 시점은 예외 처리와 분류 규칙 보정뿐입니다. (docs.paperless-ngx.com)

개발자 관점에서 인상적인 점

제가 이 프로젝트를 높게 보는 이유는 “기능이 많다”가 아니라, 기능이 파이프라인으로 연결되어 있다는 점입니다. OCR 엔진, 비동기 큐, 메타데이터 모델, 검색, UI, API, 백업이 따로 노는 것이 아니라 문서 수명주기 전체를 하나의 시스템으로 묶고 있습니다. 셀프호스팅 프로젝트 중에서 이 정도로 운영 흐름이 자연스럽게 이어지는 경우는 드뭅니다. (docs.paperless-ngx.com)

또 하나는 확장성입니다. 입력 채널을 늘리거나, API 소비자를 붙이거나, 후처리 스크립트를 걸거나, 선택적 서비스로 변환 범위를 넓히는 식의 확장이 가능합니다. 최근에는 워크플로와 AI 관련 의존성까지 포함되면서 단순 DMS를 넘어 문서 중심 자동화 플랫폼으로 가는 방향도 보입니다. (docs.paperless-ngx.com)

아쉬운 점도 분명하다

이 프로젝트는 문서 관리에 매우 강하지만, “아무 생각 없이 SaaS처럼 열어두는 서비스”는 아닙니다. README가 직접 경고하듯 민감 문서는 평문 저장 기준으로 다뤄지고, 신뢰할 수 없는 호스트에 올리는 것은 권장되지 않습니다. 즉 보안, 백업, 스토리지 마운트, 프록시, 인증 구성을 운영자가 이해해야 합니다. 이런 성격은 오히려 개발자에게는 장점이지만, 비개발자에게는 초기 허들이 될 수 있습니다. (GitHub)

또 Auto 매칭은 만능이 아닙니다. 문서와 메타데이터 사이에 상관관계가 있어야 하고, 충분한 학습 데이터가 있어야 하며, 즉시 반영되는 방식도 아닙니다. AI 기능이라기보다는 “문서 분류 보조 시스템”으로 이해하는 편이 정확합니다. (docs.paperless-ngx.com)

마무리

Paperless-ngx는 “스캔 문서를 저장하는 앱”이 아닙니다. 더 정확히 말하면, 문서를 받아서 텍스트화하고, 분류하고, 검색하고, 보존하고, 자동화 가능한 형태로 바꾸는 문서 처리 플랫폼입니다. Docker Compose로 시작할 수 있을 만큼 접근성은 좋고, Django·Celery·Redis·Angular 기반이라 구조도 익숙합니다. 그러면서도 OCR, 이메일 수집, 자동 분류, API, 백업, 워크플로까지 갖추고 있어 실제 운영 가치가 높습니다. (docs.paperless-ngx.com)

문서가 자산인 팀이라면, Paperless-ngx는 단순한 생산성 도구가 아니라 꽤 괜찮은 “문서 인프라의 시작점”이 될 수 있습니다. 특히 셀프호스팅과 자동화를 좋아하는 개발자라면, 이 프로젝트를 단순 사용자가 아니라 운영자이자 확장자로 바라보게 될 가능성이 큽니다. (GitHub)