Paperless-ngx 설치 가이드 – 종이 문서 디지털화·자동 분류 셀프호스팅

봄맞이 정리, 서류 더미부터 시작하세요

계절이 바뀌면서 집과 사무실을 정리하다 보면 서랍 속에 쌓인 종이 문서들을 마주하게 됩니다. 보험 증서, 의료비 영수증, 계약서, 자동차 정비 내역서, 아이 성적표까지. 버리자니 불안하고, 보관하자니 공간을 차지합니다. 클라우드 스캔 앱에 올리자니 개인 정보가 걱정되고요.

이런 고민을 한 번에 해결해 주는 오픈소스 프로젝트가 있습니다. 바로 Paperless-ngx입니다. 스캔한 문서를 자동으로 OCR 처리하고, AI가 태그·문서 유형·날짜를 자동 분류해 줍니다. 무엇보다 내 서버에서 직접 운영하기 때문에 민감한 개인 문서가 외부로 나갈 걱정이 없습니다.

이 글에서는 Docker 한 줄로 Paperless-ngx를 설치하고, 스캐너 없이 스마트폰만으로 문서를 등록하며, 자동 분류 규칙을 설정하는 전 과정을 안내합니다.

Paperless-ngx가 뭔가요?

Paperless-ngx는 종이 문서를 디지털로 변환하고 관리하는 문서 관리 시스템(DMS)입니다. 원래 ‘Paperless’라는 프로젝트에서 출발해 커뮤니티 포크인 ‘Paperless-ng’를 거쳐, 현재 가장 활발하게 유지되는 버전이 Paperless-ngx입니다.

핵심 기능 한눈에 보기

OCR 자동 인식: 스캔 이미지나 사진에서 텍스트를 자동 추출합니다. 한국어·영어·일본어 등 다국어를 동시에 지원합니다.
AI 자동 분류: 머신러닝 기반으로 문서의 태그, 유형(영수증·계약서·청구서 등), 작성자를 자동 할당합니다. 사용할수록 정확도가 높아집니다.
전문 검색: OCR로 추출한 텍스트 전체를 대상으로 키워드 검색이 가능합니다. “2024년 보험” 같은 검색어로 수천 장 중에서 원하는 문서를 즉시 찾을 수 있습니다.
원본 보존: 원본 파일과 OCR 처리된 파일을 모두 보관합니다. 원본 품질이 절대 손상되지 않습니다.
태그·문서 유형·작성자·날짜: 4가지 축으로 문서를 체계적으로 분류하고 필터링할 수 있습니다.
이메일 자동 수집: IMAP 계정을 연결하면 특정 폴더의 첨부 파일을 자동으로 가져옵니다.
모바일 대응 웹 UI: 별도 앱 설치 없이 스마트폰 브라우저에서 문서 열람·검색·업로드가 가능합니다.

왜 클라우드 서비스 대신 셀프호스팅인가

Google Drive나 네이버 클라우드에 스캔 문서를 올려도 되지 않냐는 질문을 자주 받습니다. 물론 가능하지만, 몇 가지 근본적인 차이가 있습니다.

프라이버시: 주민등록증, 의료 기록, 급여 명세서 같은 민감 문서를 외부 서버에 올리는 건 불안합니다. Paperless-ngx는 내 NAS나 홈서버에서만 동작합니다.
자동 분류: 클라우드 드라이브는 폴더 정리를 사람이 직접 해야 합니다. Paperless-ngx는 AI가 알아서 태그를 붙이고 유형을 분류합니다.
전문 검색: 클라우드 드라이브의 OCR 검색은 제한적이거나 유료입니다. Paperless-ngx는 모든 문서의 전체 텍스트를 무료로 검색합니다.
용량 제한 없음: 저장 용량은 디스크 크기에만 의존합니다. 월 구독료도 없습니다.

Docker Compose로 5분 만에 설치하기

Paperless-ngx는 공식적으로 Docker Compose 배포를 권장합니다. Redis(작업 큐)와 PostgreSQL(또는 SQLite)이 필요하지만, Compose 파일 하나로 전부 해결됩니다.

사전 준비

Docker와 Docker Compose가 설치된 서버(NAS, 미니 PC, 노트북 등)
최소 2GB RAM (OCR 처리 시 메모리를 사용합니다)
저장 공간: 문서량에 따라 다르지만, 시작은 10GB면 충분합니다

설치 절차

먼저 작업 디렉터리를 만들고 공식 Docker Compose 파일을 다운로드합니다.

mkdir -p ~/paperless-ngx && cd ~/paperless-ngx

curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml

mv docker-compose.postgres.yml docker-compose.yml

다운로드한 docker-compose.yml을 열어 환경 변수를 수정합니다. 핵심 설정 항목은 다음과 같습니다.

# docker-compose.yml 내 webserver 서비스의 environment 섹션
environment:
  PAPERLESS_OCR_LANGUAGE: kor+eng          # 한국어+영어 OCR
  PAPERLESS_TIME_ZONE: Asia/Seoul          # 시간대
  PAPERLESS_SECRET_KEY: 여기에-랜덤-문자열-입력  # 반드시 변경
  PAPERLESS_URL: https://paperless.example.com  # 외부 접속 시
  PAPERLESS_ADMIN_USER: admin              # 초기 관리자 ID
  PAPERLESS_ADMIN_PASSWORD: 강력한비밀번호    # 초기 관리자 PW

PAPERLESS_OCR_LANGUAGE가 가장 중요합니다. 기본값은 영어(eng)만 설정되어 있어서 한국어 문서를 인식하지 못합니다. kor+eng로 반드시 변경하세요. 일본어가 필요하면 kor+eng+jpn처럼 추가할 수 있습니다.

이제 컨테이너를 실행합니다.

docker compose up -d

약 1~2분 후 http://서버IP:8000으로 접속하면 로그인 화면이 나타납니다. 위에서 설정한 관리자 계정으로 로그인하세요.

Synology NAS에 설치할 때 주의점

Synology NAS의 Container Manager(구 Docker 패키지)를 사용한다면 몇 가지 추가 설정이 필요합니다.

공유 폴더 권한: /docker/paperless 공유 폴더를 만들고, 볼륨 마운트 경로를 해당 폴더로 지정하세요.
포트 충돌: 기본 포트 8000이 다른 서비스와 겹칠 수 있습니다. ports: "8777:8000"처럼 외부 포트를 변경하세요.
메모리 제한: DS220+ 같은 2GB 모델에서는 OCR 처리 시 메모리 부족이 발생할 수 있습니다. PAPERLESS_TASK_WORKERS: 1과 PAPERLESS_THREADS_PER_WORKER: 1로 동시 처리를 줄이세요.
dsm7 사용자 ID: USERMAP_UID와 USERMAP_GID를 NAS 사용자의 UID/GID에 맞춰야 파일 권한 문제가 없습니다. SSH로 id 명령어를 실행해 확인하세요.

스캐너 없이 스마트폰으로 문서 등록하기

전용 스캐너가 있으면 좋지만, 대부분의 가정에서는 스마트폰 카메라로 충분합니다. Paperless-ngx에 문서를 넣는 방법은 크게 세 가지입니다.

방법 1: 웹 UI에서 직접 업로드

가장 간단한 방법입니다. 스마트폰 브라우저에서 Paperless-ngx에 접속한 뒤, 우측 하단의 업로드 버튼을 눌러 사진이나 PDF를 올립니다. 여러 파일을 한꺼번에 드래그 앤 드롭으로 올릴 수도 있습니다.

방법 2: 스캔 앱 + 자동 업로드 조합

더 깔끔한 결과물을 원한다면 스마트폰 스캔 앱을 활용하세요. 스캔 앱은 기울어진 문서를 자동 보정하고, 명암을 조절해 OCR 인식률을 높여줍니다.

iOS: 기본 메모 앱의 스캔 기능 또는 Microsoft Lens
Android: Google 드라이브 스캔 기능 또는 Microsoft Lens

스캔한 PDF를 Paperless-ngx의 consume 폴더에 넣으면 자동으로 처리됩니다. Syncthing이나 SMB 공유를 설정해 두면, 스캔 앱에서 저장한 파일이 자동으로 consume 폴더에 도착하게 만들 수 있습니다.

방법 3: 이메일로 전송

Paperless-ngx에 IMAP 메일 계정을 연결하면, 해당 메일 주소로 보낸 문서가 자동으로 등록됩니다. 예를 들어 [email protected]이라는 전용 이메일을 만들고, 청구서나 영수증 메일을 이 주소로 전달하면 첨부 파일이 자동 수집됩니다.

# docker-compose.yml environment에 추가
PAPERLESS_EMAIL_HOST: imap.gmail.com
PAPERLESS_EMAIL_PORT: 993
PAPERLESS_EMAIL_HOST_USER: [email protected]
PAPERLESS_EMAIL_HOST_PASSWORD: 앱비밀번호
PAPERLESS_EMAIL_CHECKING_INTERVAL: 300   # 5분마다 확인

consume 폴더 활용 팁

consume 폴더는 Paperless-ngx가 감시하는 특별한 폴더입니다. 여기에 파일을 넣으면 자동으로 OCR 처리되고 데이터베이스에 등록된 뒤 원본 파일은 삭제됩니다(내부 저장소로 이동). Docker Compose에서 이 폴더의 위치를 호스트 경로로 매핑해 두면, 다양한 자동화와 연결할 수 있습니다.

volumes:
  - ./consume:/usr/src/paperless/consume    # 이 폴더에 파일을 넣으면 자동 처리

자동 분류 규칙 설정하기

Paperless-ngx의 진짜 힘은 자동 매칭(Auto Matching)에 있습니다. 문서를 올리기만 하면 AI가 알아서 태그를 붙이고, 문서 유형을 지정하고, 작성자를 판별합니다.

분류 체계 설계

자동 분류를 설정하기 전에, 먼저 자신만의 분류 체계를 정하는 것이 중요합니다. 다음은 개인 문서 관리에 효과적인 예시입니다.

문서 유형(Document Types)

영수증 / 청구서
계약서
보험 서류
의료 기록
자동차 관련
증명서 / 자격증
세금 / 연말정산

태그(Tags)

연도별: 2024, 2025, 2026
가족: 본인, 배우자, 자녀
상태: 보관중, 처리완료, 만료됨
중요도: 중요, 일반

작성자(Correspondents)

국민건강보험공단, 국세청, 삼성화재, 현대자동차, 우리은행 등 문서를 보낸 기관/기업

매칭 알고리즘 이해하기

Paperless-ngx는 태그·문서 유형·작성자 각각에 대해 매칭 알고리즘을 선택할 수 있습니다.

Any (하나라도 포함): 지정한 키워드 중 하나라도 문서에 포함되면 매칭. 예를 들어 “영수증” 태그에 “영수증, 결제, 카드매출”을 등록하면 세 단어 중 하나만 있어도 태그가 붙습니다.
All (모두 포함): 지정한 키워드가 모두 포함된 경우에만 매칭.
Exact (정확히 일치): 문서 제목이나 본문에 정확한 문자열이 있을 때 매칭.
Regular Expression (정규식): 정규표현식으로 복잡한 패턴을 지정. 예를 들어 \d{3}-\d{2}-\d{5}로 사업자등록번호가 포함된 문서를 찾을 수 있습니다.
Auto (자동 학습): 사용자가 수동으로 분류한 이력을 기반으로 머신러닝이 자동 판별합니다. 처음에는 정확도가 낮지만, 50건 이상 학습하면 상당히 정확해집니다.

실전 자동 분류 예시

관리 화면의 Tags 메뉴에서 새 태그를 만들고 매칭 규칙을 설정합니다.

예시 1: 의료비 영수증 자동 태그

태그명: 의료비
매칭 알고리즘: Any
매칭 키워드: 진료비, 처방전, 의료비, 수납, 건강보험

예시 2: 자동차 정비 문서 자동 분류

문서 유형: 자동차 관련
매칭 알고리즘: Any
매칭 키워드: 정비, 수리, 차량, 엔진오일, 타이어, BMW, 점검

예시 3: 국세청 문서 작성자 자동 지정

작성자: 국세청
매칭 알고리즘: Any
매칭 키워드: 국세청, 홈택스, 원천징수, 종합소득세

이렇게 규칙을 10~15개만 만들어 두면, 이후에는 문서를 스캔해서 넣기만 하면 자동으로 정리됩니다. Auto 알고리즘을 병행하면, 규칙을 직접 만들지 않아도 기존 분류 패턴을 학습해 새 문서를 알아서 분류합니다.

한국어 OCR 정확도 높이기

Paperless-ngx는 내부적으로 Tesseract OCR을 사용합니다. 한국어 인식 성능을 극대화하려면 몇 가지 추가 설정이 필요합니다.

OCR 설정 최적화

# docker-compose.yml environment
PAPERLESS_OCR_LANGUAGE: kor+eng
PAPERLESS_OCR_MODE: skip_noarchive     # 이미 OCR된 PDF는 건너뜀
PAPERLESS_OCR_CLEAN: clean             # 노이즈 제거 전처리
PAPERLESS_OCR_DESKEW: true             # 기울어진 문서 자동 보정
PAPERLESS_OCR_ROTATE_PAGES: true       # 회전된 페이지 자동 교정
PAPERLESS_OCR_OUTPUT_TYPE: pdfa        # PDF/A 장기보존 형식

각 옵션이 하는 일을 정리하면 다음과 같습니다.

OCR_CLEAN: 스캔 이미지의 배경 노이즈, 얼룩, 그림자를 제거해 인식률을 높입니다.
OCR_DESKEW: 스캐너에서 비뚤게 들어간 문서를 자동으로 수평 보정합니다.
OCR_ROTATE_PAGES: 세로 문서가 가로로 스캔된 경우 자동 회전합니다.
OCR_OUTPUT_TYPE: pdfa: PDF/A는 장기 보존용 표준 형식입니다. 10년 후에도 동일하게 열 수 있다는 보장이 됩니다.

한국어 인식률을 높이는 실전 팁

Tesseract의 한국어 인식률은 영어보다 낮은 편이지만, 다음 방법으로 상당히 개선할 수 있습니다.

고해상도 스캔: 최소 300dpi 이상으로 스캔하세요. 스마트폰 카메라를 사용한다면 가장 높은 해상도로 촬영하고, 조명이 균일한 곳에서 찍으세요.
그림자 제거: 문서 위에 스마트폰 그림자가 지면 인식률이 크게 떨어집니다. 밝은 조명 아래에서 약간 비스듬하게 촬영하거나, 스캔 앱의 플래시 기능을 활용하세요.
한 장씩 촬영: 여러 장을 한꺼번에 촬영하면 각 문서의 경계를 인식하지 못합니다. 문서 한 장당 사진 한 장을 원칙으로 하세요.
배경 대비: 흰 문서는 어두운 배경 위에, 어두운 문서는 밝은 배경 위에 놓으면 문서 경계 자동 인식이 잘 됩니다.

인식 결과 수동 보정

OCR 결과가 완벽하지 않을 수 있습니다. 특히 손글씨, 도장, 오래된 팩스 문서 등은 오인식이 발생합니다. Paperless-ngx 웹 UI에서 문서를 열면 추출된 텍스트를 직접 수정할 수 있습니다. 수정한 텍스트는 검색 인덱스에 즉시 반영됩니다.

실전 활용 시나리오

설치와 설정을 마쳤으니, 실제로 어떤 상황에서 Paperless-ngx가 빛을 발하는지 구체적인 시나리오를 살펴보겠습니다.

시나리오 1: 연말정산 서류 한방 정리

매년 1월이면 연말정산 시즌이 돌아옵니다. 의료비 영수증, 기부금 영수증, 교육비 납입 증명서, 주택자금 관련 서류 등을 모아야 하는데, 1년치 서류를 한꺼번에 찾으려면 난감합니다.

Paperless-ngx에 연중 수시로 영수증을 스캔해 넣어 두면, 연말정산 시기에 “의료비 + 2025” 태그로 필터링하는 것만으로 필요한 서류가 전부 나옵니다. PDF로 일괄 다운로드해서 회사에 제출하면 끝입니다.

시나리오 2: 자동차 정비 이력 관리

자동차 정비소에서 받는 정비 명세서를 매번 사진 찍어 넣어 두세요. “자동차” 문서 유형에 자동 분류되도록 설정하면, 차량 매도 시 정비 이력을 한눈에 보여줄 수 있습니다. 엔진오일 교환 주기를 검색으로 확인하는 것도 간단합니다.

시나리오 3: 보험·계약 만료일 알림

Paperless-ngx에는 문서별로 날짜를 지정할 수 있습니다. 보험 만기일, 계약 종료일을 입력해 두면 대시보드에서 곧 만료되는 문서를 확인할 수 있습니다. n8n이나 Home Assistant와 연동하면 만료 전 자동 알림을 보내는 것도 가능합니다.

시나리오 4: 가족 문서 통합 관리

Paperless-ngx는 여러 사용자 계정을 지원합니다. 가족 구성원별 계정을 만들면 각자의 문서를 독립적으로 관리할 수 있고, 공유 태그를 통해 가족 공통 문서(부동산 계약서, 가족 보험 등)는 함께 볼 수 있습니다.

백업과 보안 설정

중요한 문서를 보관하는 만큼 백업과 보안에 신경 써야 합니다.

정기 백업 설정

Paperless-ngx는 내장 백업 명령어를 제공합니다.

# 전체 백업 (문서 + DB + 설정)
docker compose exec webserver document_exporter ../export --zip

# cron으로 매일 자동 백업 (리눅스 기준)
0 3 * * * cd ~/paperless-ngx && docker compose exec -T webserver document_exporter ../export --zip && mv export/*.zip /backup/paperless/

백업 파일은 NAS의 다른 볼륨이나 외장 하드에 저장하세요. 3-2-1 백업 원칙(원본 1 + 로컬 백업 1 + 외부 백업 1)을 적용하면 더욱 안전합니다.

보안 강화 체크리스트

PAPERLESS_SECRET_KEY를 반드시 고유한 랜덤 문자열로 변경하세요. 기본값을 그대로 사용하면 세션 하이재킹 위험이 있습니다.
HTTPS 적용: Nginx Proxy Manager나 Cloudflare Tunnel을 통해 HTTPS를 적용하세요. 특히 외부에서 접속한다면 필수입니다.
기본 포트 변경: 8000번 포트를 그대로 노출하지 말고, 리버스 프록시 뒤에 두세요.
2단계 인증: Paperless-ngx 2.x부터 TOTP 기반 2단계 인증을 지원합니다. 관리자 설정에서 활성화하세요.
방화벽: 외부 접속이 필요 없다면 내부 네트워크에서만 접근 가능하도록 방화벽을 설정하세요.

유용한 확장 기능과 연동

모바일 앱

Paperless-ngx 공식 모바일 앱은 없지만, 커뮤니티에서 만든 서드파티 앱들이 있습니다.

Paperless Mobile (iOS/Android): 문서 검색·열람·업로드가 가능한 네이티브 앱
Swift Paperless (iOS): 깔끔한 UI로 문서 관리가 가능한 iOS 전용 앱

두 앱 모두 Paperless-ngx의 REST API를 사용하므로, 서버 주소와 API 토큰만 입력하면 바로 연결됩니다.

다른 셀프호스팅 서비스와 연동

n8n / Home Assistant: Paperless-ngx의 REST API를 호출해 새 문서 등록 시 알림을 보내거나, 특정 태그가 붙은 문서를 자동 처리하는 워크플로우를 만들 수 있습니다.
Nextcloud: Nextcloud의 External Storage 기능으로 Paperless-ngx의 media 폴더를 마운트하면, Nextcloud에서도 원본 문서에 접근할 수 있습니다.
Gotify / ntfy: 문서 처리 완료 시 푸시 알림을 받을 수 있습니다.

마무리: 종이 없는 생활, 생각보다 가깝습니다

Paperless-ngx는 설치부터 운영까지 놀라울 정도로 간단합니다. Docker Compose로 5분이면 설치가 끝나고, 스마트폰 카메라로 찍어서 올리기만 하면 AI가 알아서 분류해 줍니다. 처음에는 기존에 쌓인 서류를 스캔하는 데 시간이 좀 걸리지만, 한번 시스템을 갖추면 그 이후로는 영수증이나 서류를 받을 때마다 사진 한 장 찍는 습관만 들이면 됩니다.

특히 봄맞이 대청소를 계획하고 있다면, 서랍 속 서류 더미를 디지털화하는 것부터 시작해 보세요. 물리적 공간도 확보되고, 필요할 때 검색 한 번으로 원하는 문서를 찾을 수 있는 편리함은 한번 경험하면 되돌아갈 수 없습니다.

이전에 소개한 Docker 입문 가이드와 Nginx Proxy Manager 설치법을 함께 참고하면, Paperless-ngx를 HTTPS로 안전하게 외부 접속할 수 있는 완전한 문서 관리 시스템을 구축할 수 있습니다. 올봄, 종이 없는 깔끔한 생활을 시작해 보시기 바랍니다.

이미지는 Leonardo AI 로 생성되었습니다.

이미지는 Claude AI 로 생성되었습니다.