현재 답변: 2026년 Paperless-ngx 설치 모델로 1.4.2 베타 설치 실패를 사용하지 마세요
기존 설치는 ZimaOS 1.4.2-beta2에서 83%에서 중단되었으며, IceWhale은 해당 릴리스에서 앱 설치 소스/프록시 기술이 변경되었고 이 문제가 수정 중이라고 밝혔습니다. 현재 ZimaOS는 전용 Paperless-ngx 설치 절차를 제공하며, 업스트림 프로젝트에는 안정적인 Docker Compose 설치 경로가 있습니다. 2025년에 발생한 중단은 역사적인 설치 프로그램 버그로 간주해야 하며, Paperless-ngx가 ZimaOS와 근본적으로 호환되지 않는다는 증거로 보아서는 안 됩니다.
현재 ZimaOS 앱 스토어 구성부터 시작하세요
현재 ZimaOS 지침에서는 앱 스토어의 Paperless-ngx에서 사용자 지정 설치를 사용하여 처음 시작하기 전에 저장 경로, 관리자 자격 증명, OCR 언어 및 신뢰할 수 있는 URL 값을 설정할 수 있습니다. ZimaOS Paperless 설정이 현재 제품별 기준입니다.
Paperless-ngx 요구 사항에서는 대규모 OCR 작업 전에 앱의 사양을 정하는 데 도움을 줍니다.
백업할 수 있는 저장 공간에 영구 데이터를 배치하세요
Paperless에는 데이터베이스 데이터, 애플리케이션 데이터, 미디어/문서, 내보낸 파일 및 consume 폴더 등 여러 유형의 상태 데이터가 있습니다. 이러한 경로를 일시적인 컨테이너 계층 외부에 영구적으로 유지하세요. 디버깅 중 AppData를 삭제하면 이전 설치가 실패한 이유를 파악하는 데 필요한 증거나 상태까지 삭제될 수 있습니다.
Paperless Docker 설정에서는 업스트림 서비스와 권장 PostgreSQL 배포 방식을 설명합니다.
Tika 및 Gotenberg 사용 여부를 이해하세요
Paperless는 핵심 PDF/이미지 문서 처리 흐름에서 Tika/Gotenberg 없이 실행할 수 있습니다. Tika와 Gotenberg는 Office 파일 및 이메일 구문 분석이 필요할 때 사용하는 선택적 서비스입니다. 패키지에서 Tika 관련 오류가 발생하면 해당 기능이 실제로 필요한지 먼저 판단한 후, 그 기능 때문에 전체 설치를 중단할지 결정하세요.
Paperless Tika 설정에는 엔드포인트와 활성화 변수가 정리되어 있습니다.
설치가 특정 비율에서 멈추면 몇 시간씩 기다리지 말고 컨테이너를 확인하세요
docker ps -a
docker logs --tail=200 paperless-webserver
docker logs --tail=200 paperless-db
docker logs --tail=200 paperless-redis정확한 컨테이너 이름은 앱 스토어 패키지에 따라 다릅니다. 이미지 가져오기 실패, 데이터베이스 준비 상태, 권한, CSRF 구성 또는 서비스의 반복 재시작 여부를 확인하세요. “83%”는 UI에 나타나는 증상일 뿐이며, 어떤 구성 요소가 실패했는지는 컨테이너 로그에서 확인할 수 있습니다.
OCR을 탓하기 전에 consume 폴더 소유권을 수정하세요
Paperless는 consume 디렉터리에서 파일을 읽고 이동할 수 있어야 합니다. 업스트림 Docker 구성에서는 호스트 권한을 맞추기 위해 USERMAP_UID/USERMAP_GID를 지원합니다. 호스트 consume 폴더에 파일이 나타나지만 Paperless가 전혀 처리하지 않는다면 소유권, 마운트 경로 및 파일 시스템 알림을 확인하세요.
ZimaOS 앱 요구 사항을 참고하면 증가하는 문서 보관 파일을 작은 OS 드라이브에 저장하는 일을 피할 수 있습니다.
외부 URL을 올바르게 구성하세요
Paperless에 ZimaOS 호스트 주소 또는 역방향 프록시를 통해 액세스하는 경우, 사용자가 실제로 여는 주소에 맞춰 신뢰할 수 있는 오리진과 공개 URL을 설정하세요. 오리진 구성이 잘못되면 모든 컨테이너가 정상인데도 나중에 403 CSRF 오류가 발생할 수 있습니다.
데이터베이스와 문서를 함께 백업하세요
Paperless 데이터베이스 없이 문서 파일만 있으면 태그, 담당자, 사용자 지정 필드 및 워크플로 상태가 손실되고, 미디어 없이 데이터베이스만 있으면 실제 문서가 사라집니다. 두 항목을 하나의 복구 단위로 함께 백업하고, 주요 업그레이드 전에 복원을 테스트하세요.
ZimaOS 백업은 NAS 수준의 복구 계층을 제공합니다.
FAQ
Paperless-ngx가 ZimaOS에서 83%에서 멈춘 이유는 무엇인가요?
원래 사례에서 IceWhale은 이 실패가 ZimaOS 1.4.2 베타의 앱 소스/프록시 변경과 관련 있다고 설명했습니다. 현재 시스템에서는 동일한 오래된 버그라고 단정하지 말고 컨테이너 로그를 확인하세요.
Paperless-ngx에 Tika가 필요한가요?
핵심 PDF/이미지 문서 관리에는 필요하지 않습니다. Office 문서 및 이메일 구문 분석이 필요할 때 Tika와 Gotenberg를 선택적으로 사용합니다.
consume 폴더는 어디에 두어야 하나요?
호스트 경로가 명확하고 Paperless 컨테이너가 읽고 수정할 수 있는 권한이 설정된 영구 ZimaOS 데이터 저장 공간을 사용하세요.
AppData를 삭제하고 다시 설치해야 하나요?
삭제될 데이터를 파악하고 백업한 경우에만 진행하세요. 잘못된 볼륨 경로, 권한 또는 URL 구성을 재설치로 해결할 수는 없습니다.
새 Paperless 설치에는 어떤 데이터베이스를 사용해야 하나요?
현재 업스트림 프로젝트는 새 설치에 PostgreSQL을 권장합니다.
