現在の回答：2026年のPaperless-ngxセットアップモデルとして、1.4.2ベータ版のインストール失敗を使用しない
元のインストールはZimaOS 1.4.2-beta2で83%の時点で停止しました。IceWhaleは、このリリースでアプリのインストール元およびプロキシ技術が変更されており、問題を修正中だと説明しました。現在のZimaOSでは専用のPaperless-ngxインストール手順が公開されており、上流プロジェクトにも成熟したDocker Composeの手順があります。2025年の停止は過去のインストーラーの不具合として扱い、Paperless-ngxがZimaOSと根本的に互換性がない証拠とは考えないでください。
まず現在のZimaOS App Store設定から始める
現在のZimaOSの手順では、App Storeから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正確なコンテナー名はApp Storeパッケージによって異なります。イメージの取得失敗、データベースの準備状態、権限、CSRF設定、またはサービスが再起動を繰り返して停止している状態を確認してください。「83%」はUI上の症状にすぎません。どのコンポーネントが失敗しているかはコンテナーのログで特定できます。
OCRを疑う前にconsumeフォルダーの所有権を修正する
Paperlessはconsumeディレクトリからファイルを読み取り、移動できなければなりません。上流のDocker設定では、ホスト側の権限を合わせるためにUSERMAP_UID／USERMAP_GIDを使用できます。ホストのconsumeフォルダーにファイルが表示されるのにPaperlessが処理しない場合は、所有権、マウントパス、ファイルシステムの通知機能を確認してください。
ZimaOSアプリの要件を確認すると、増え続けるドキュメントアーカイブを小容量のOSドライブに保存する事態を避けられます。
外部URLを正しく設定する
PaperlessにZimaOSホストのアドレスやリバースプロキシ経由でアクセスする場合は、ユーザーが実際に開くアドレスを信頼済みオリジンと公開URLに設定してください。オリジン設定が正しくないと、すべてのコンテナーが正常でも、後から403 CSRFエラーが発生することがあります。
データベースとドキュメントを一緒にバックアップする
Paperlessのデータベースがないドキュメントファイルだけでは、タグ、取引先、カスタムフィールド、ワークフローの状態が失われます。メディアのないデータベースだけでは、実際のドキュメントが失われます。両方を1つの復旧単位としてバックアップし、大規模なアップグレードの前に復元テストを行ってください。
ZimaOSのバックアップが、NASレベルの復旧基盤を提供します。
よくある質問
ZimaOSでPaperless-ngxが83%で停止したのはなぜですか？
元の事例では、IceWhaleがこの失敗をZimaOS 1.4.2ベータ版におけるアプリソース／プロキシの変更と関連付けました。現在のシステムでは、同じ古い不具合だと決めつけず、コンテナーのログを確認してください。
Paperless-ngxにはTikaが必要ですか？
PDF／画像ドキュメントの基本的な管理には必要ありません。Officeドキュメントやメールの解析が必要な場合に、TikaとGotenbergをオプションで使用します。
consumeフォルダーはどこに配置すべきですか？
明確なホストパスがあり、Paperlessコンテナーが読み取りと変更を行える権限を持つ、永続化されたZimaOSデータストレージを使用してください。
AppDataを削除して再インストールすべきですか？
削除されるデータの内容を理解し、バックアップを取得した後に限って行ってください。再インストールしても、不適切なボリュームパス、権限、URL設定は修正されません。
新しいPaperlessインストールでは、どのデータベースを使用すべきですか？
上流プロジェクトでは現在、新規インストールにPostgreSQLを推奨しています。
