Paperless-ngx 3.3.3 常用 CLI 命令与工具详解

目标：把 Paperless-ngx 3.3.3 的命令行能力讲全、讲准。Paperless-ngx 没有独立 CLI 二进制，命令行主线是 Web 应用内置的 Django management commands（python3 manage.py <子命令>），辅以 REST API 的 curl 调用。本文全部命令与回显在 Ubuntu 22.04 + Paperless-ngx 3.3.3 实测环境逐条执行采集（部署过程见 《Paperless-ngx 3.3.3 Docker Compose 部署指南》，参数含义见 《Paperless-ngx 3.3.3 配置参数详解》）。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Paperless-ngx：3.3.3（官方最新稳定版，2026-10-22 查询 GitHub Releases/latest）
• 应用目录：/opt/paperless/src/（源码安装形态；manage.py 所在），本文命令均在该目录执行
• 数据目录：/opt/paperless/data、媒体目录：/opt/paperless/media、导出目录：/opt/paperless/export
• 实测数据面：1 篇中文 OCR 文档（id 1，含标签"发票"）+ 1 篇 docx 文档（id 2）；全文检索引擎为 tantivy（3.x 起替换 Whoosh）
• 权限要求：命令以运行应用的用户执行（实测环境该用户 uid 1000）；以 root 执行会产出属主错误的索引/模型文件，引发搜索 PermissionDenied（排障实录见第十章 FAQ）

二、工具概览

manage.py help 列出的子命令按来源分组，实测回显（节选，保留 Paperless 自有组与常用 Django 组）：

[documents]
    base
    convert_mariadb_uuid
    document_archiver
    document_consumer
    document_create_classifier
    document_exporter
    document_fuzzy_match
    document_importer
    document_index
    document_llmindex
    document_renamer
    document_retagger
    document_sanity_checker
    document_thumbnails
    manage_superuser
    mixins
    prune_audit_logs
[auth]
    changepassword
    createsuperuser
[authtoken]
    drf_create_token
[django]
    check
    compilemessages
    createcachetable
    dbshell
    diffsettings
    dumpdata
    flush
    （其余 Django 内置从略）
[paperless_mail]
    mail_fetcher
[sessions]
    clearsessions

命令地图（按用途）：

三、前置条件

1. Paperless-ngx 3.3.3 已部署并可访问（部署指南篇从零完成）。
2. 进入应用环境：源码安装在应用目录直接执行 python3 manage.py <命令>；Compose 部署在部署目录用 docker compose exec webserver python3 /usr/src/paperless/src/manage.py <命令> 进入同一环境（进入方式详见部署指南篇，本文后文统一写 python3 manage.py <命令> 形式）。
3. 执行用户 = 应用运行用户（默认 uid 1000），root 执行有属主风险（见 FAQ）。

四、各命令详解

4.1 document_exporter：全量导出备份

把全部文档（原始件 + PDF/A 归档件 + 缩略图）与数据库模型清单导出到指定目录，是官方推荐的备份方式：

python3 manage.py document_exporter /opt/paperless/export

实测回显：

  Exporting documents... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1 0:00:00 0:00:00

导出后目录内容实测：

2026-10-22 中文识别测试-FA-2026-1022-archive.pdf
2026-10-22 中文识别测试-FA-2026-1022.pdf
2026-10-22 中文识别测试-FA-2026-1022-thumbnail.webp
manifest.json
metadata.json

• manifest.json：Django 序列化清单（实测 221 条记录，每条含 pk/model/fields 三键），恢复的依据。
• metadata.json：导出元信息。
• 常用参数（python3 manage.py help document_exporter 实测）：

  --no-progress-bar     Disable the progress bar
  --zip-compression {stored,deflated,bzip2,lzma,zstd}
                        --zip). Default: deflated. 'zstd' requires Python
  --zip-compression-level ZIP_COMPRESSION_LEVEL
  --data-only           If set, only the database will be imported, not files
  --passphrase PASSPHRASE
  --batch-size BATCH_SIZE

⚠️ 注意：官方 help 文案中 --data-only 的说明写的是 "only the database will be imported, not files"（imported），这是上游 help 文本的笔误，实际含义是"仅导出数据库数据，不导出文件"，此处按实测原样保留提醒读者。

增量特性：重跑导出时仅处理有变化的文档；--passphrase 可对导出做 GPG 加密。

4.2 document_importer：从备份恢复

从导出目录（或 zip）整体恢复，参数是目录路径（不是 manifest.json 文件路径）：

python3 manage.py document_importer /opt/paperless/export

实测回显（恢复成功，节选）：

Copy files into paperless...
⠋ Copying files... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/? 0:00:00
⠋ Copying share link bundles... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0/? 0:00:00
Updating search index...
  Indexing documents... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1 0:00:00 0:00:00

实测出的三条重要行为：

1. 参数必须是目录：实测传文件路径 /opt/paperless/export/manifest.json 直接报 CommandError: That directory doesn't appear to contain a manifest.json file.
2. 非空库守卫只是 WARNING：对已有数据的实例导入会打印三条提示（实测回显）：

Found file 0000001.pdf, this might indicate a non-empty installation
Found existing user(s), this might indicate a non-empty installation
Found existing documents(s), this might indicate a non-empty installation

命令不会因此中止，继续执行会因目标文件已存在抛异常（实测）：FileExistsError: /opt/paperless/media/documents/originals/0000001.pdf。恢复演练的正确姿势是先清库清目录（完整演练过程见部署指南篇 10.4）。 3. 常用参数（实测）：--data-only（仅恢复数据库）、--passphrase（对应加密导出）、--no-progress-bar、--batch-size。

4.3 document_index：全文索引管理

搜索结果异常时的修复手段。用法 document_index reindex|optimize：

python3 manage.py document_index reindex

实测回显：

  Indexing documents... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1 0:00:00 0:00:00

python3 manage.py document_index optimize

实测回显：

  Optimizing index...

reindex 全量重建索引；optimize 压缩索引段。恢复导入后若检索无结果，reindex 一次即恢复（实测：中文关键词"云栖科技"恢复命中）。

4.4 document_thumbnails：缩略图重生成

python3 manage.py document_thumbnails --document 1

实测回显：

[INFO] [paperless.parsing] convert exited 0
  Regenerating thumbnails... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1/1 0:00:03 0:00:00

• --document <id> 指定单篇；不带参数则全库重生成（文档量大时耗时显著）。
• 改用 CJK 字体修缩略图方块字后，用它生效（PAPERLESS_THUMBNAIL_FONT_NAME 见配置篇）。

4.5 document_create_classifier：训练自动归类模型

基于已有标签/通讯对象/类型的文档训练机器学习模型，供"自动归类"与 document_retagger 使用：

python3 manage.py document_create_classifier

实测回显：

✓ Classifier training complete (0.0s)

⚠️ 注意：实测环境仅 1 篇已标注文档，训练完成但未生成模型文件 data/classification_model.pkl（样本量不足时训练是空跑）。模型文件随标注文档积累产生，生产上建议数十篇标注后再依赖自动归类。

4.6 document_retagger：按模型重打标签

python3 manage.py document_retagger --suggest

参数表（--help 实测节选）：

  --no-progress-bar     Disable the progress bar
  --use-first           By default this command will not try to assign a
  --suggest             Show what would be changed without applying anything.
  --base-url BASE_URL   Base URL used to build document links in suggest
  --id-range ID_RANGE ID_RANGE

--suggest 是官方提供的"预览模式"（只显示将改什么不实际改），等效于其他工具的 dry-run；--use-first 允许把置信度最高的猜测直接落库；--id-range 100 200 限定文档范围。

4.7 document_renamer：按模板重排归档文件名

python3 manage.py document_renamer

实测行为：按 PAPERLESS_FILENAME_FORMAT 模板重算并重命名 media/documents/archive/ 与 originals/ 下的文件（实测默认模板下文件名形如 2026-10-22 中文识别测试-FA-2026-1022.pdf）。参数表实测没有 --dry-run 选项（实测传 --dry-run 报 error: unrecognized arguments: --dry-run），只有 --no-progress-bar；预览需求请先备份 media 目录或在测试实例演练。

4.8 document_sanity_checker：归档库健康巡检

python3 manage.py document_sanity_checker

实测回显：

╭──────────────────────────────── Sanity Check ────────────────────────────────╮
│ No issues detected.                                                          │
╰──────────────────────────────────────────────────────────────────────────────╯

校验项包括：文档文件存在性、PDF 完整性、缩略图与索引一致性等；建议纳入日常巡检（Web 界面的 sanity checker 定时任务同样在跑）。

4.9 document_fuzzy_match：内容近似查重

python3 manage.py document_fuzzy_match --ratio 95.0

参数表（--help 实测）：

  --no-progress-bar     Disable the progress bar
  --processes PROCESSES
  --ratio RATIO         Ratio to consider documents a match (0.0 - 100.0)
  --delete              If set, one document of matches above the ratio WILL
  --yes                 Skip the confirmation prompt when used with --delete
  --url URL             Base URL of the Paperless instance (e.g.

--ratio 设判定阈值；--delete 才会真删（每组重复保留一篇），且配 --yes 跳过确认；--url 用于输出结果里拼文档链接。实测当前库无重复，真实回显：

╭──────────────────────────────── Fuzzy Match ─────────────────────────────────╮
│ No duplicate documents found.                                                │
╰──────────────────────────────────────────────────────────────────────────────╯

4.10 document_archiver：补生成 PDF/A 归档件

python3 manage.py document_archiver --document 1

实测回显（已有归档件的文档自动跳过，无可处理项）：

⠋ Archiving... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0/0 0:00:00 -:--:--

参数实测：--processes 控制并发；指定 --document <id> 单篇处理，不带则全库。适用场景：早期导入的纯图片文档只有原始件没有 PDF/A 归档件时批量补齐；已有归档件的文档不会重做。

4.11 document_consumer：消费目录守护（了解即可）

python3 manage.py document_consumer --oneshot

实测参数：--oneshot（扫一遍现有文件即退出，适合脚本触发）、--testing（短超时测试模式）。Compose 部署形态该守护已在 webserver 内常驻，此命令用于源码安装形态以独立进程跑消费目录监视，一般无需手动执行。

4.12 mail_fetcher：邮件规则手动拉取

python3 manage.py mail_fetcher

无业务参数（--help 实测仅通用参数）。执行时按 Web 界面配置的邮件账户与规则拉取附件入库；邮件账户未配置时执行无动作。适合配 cron 定时（官方部署形态亦有内置定时）。

4.13 账号管理三件套

createsuperuser（脚本化建超管）：

DJANGO_SUPERUSER_PASSWORD=q1w2e3r4 python3 manage.py createsuperuser --noinput --username root --email root@example.com

实测回显：

Superuser created successfully.

drf_create_token（为用户签发 REST API Token）：

python3 manage.py drf_create_token admin

实测回显：

Generated token 76831b5038796395d97acb8682dc436e08c3b53c for user admin

（与 POST /api/token/ 取到的 Token 一致，两路凭证同源。）

changepassword（交互式改密）：必须在交互终端（TTY）中运行，逐遍输入新口令后提示改密成功；非交互管道喂入实测直接报 EOFError（getpass 无法读口令，实测回显含 File "/usr/local/lib/python3.14/getpass.py", line 183, in _raw_input ... EOFError）。改密的可行路径：交互会话执行本命令，或走 Web 界面用户设置修改。

4.14 会话与审计清理

python3 manage.py clearsessions

实测：清空过期 Django 会话，成功时无输出。建议每周 cron。

python3 manage.py prune_audit_logs

审计日志修剪（auditlog 组），配合保留天数策略使用；日常未配置审计保留时可暂不使用。

4.15 document_llmindex：AI 索引构建（3.x 新特性）

python3 manage.py document_llmindex --help

实测：命令存在（[documents] 组下），参数仅通用项；其作用是为 AI 对话/相似文档检索构建向量索引，需先在 Web 界面配置 LLM 后端（官方定位 AI 能力 opt-in、默认关闭）。

4.16 REST API 抽样（curl）

以 drf_create_token 签发的 Token 调用 REST API，三个高频场景实测：

全文检索（中文关键词 URL 编码后）：

curl -sS -H "Authorization: Token 76831b5038796395d97acb8682dc436e08c3b53c" \
  "http://localhost:8000/api/documents/?query=云栖科技"

实测回显（节选）：

{"count": 1, ... "results": [{"id": 1, "title": "中文识别测试-FA-2026-1022", ...}]}

建标签：

curl -sS -X POST http://localhost:8000/api/tags/ \
  -H "Authorization: Token 76831b5038796395d97acb8682dc436e08c3b53c" \
  -H "Content-Type: application/json" -d '{"name":"发票","colour":1}'

实测回显（节选）：

{"id": 1, "slug": "", "name": "发票", "color": "#a6cee3", ...}

改文档标签（PATCH）：

curl -sS -X PATCH http://localhost:8000/api/documents/1/ \
  -H "Authorization: Token 76831b5038796395d97acb8682dc436e08c3b53c" \
  -H "Content-Type: application/json" -d '{"tags":[1]}'

实测回显：HTTP 200，随后 GET /api/documents/1/ 返回 "tags": [1]。API 全集（文档/标签/通讯对象/工作流/分享链接等）见官方 API 文档与 /api/schema/（drf_spectacular 生成）。

五、注意事项

1. 执行身份：管理命令统一以应用运行用户执行（实测 uid 1000）。root 执行后索引/模型文件属主错位，服务读不到会报 Search index is corrupted or incomplete 与 PermissionDenied，需 chown -R 修复后 document_index reindex（实录见 FAQ）。
2. importer 不是增量同步：它面向"空实例整体恢复"，对已有数据实例强推会 FileExistsError；两实例间迁移请始终走 export → 空实例 import。
3. classifier 依赖已标注数据量：样本过少时空跑（实测不落盘模型），自动归类准确率随标注量提升。
4. document_renamer 无预览参数：改文件名动作直接生效，执行前先备份 media。
5. --suggest 优于事后修复：retagger 的 --suggest 预览、fuzzy_match 不带 --delete 的只读跑法，都是先看后动的安全姿势。

六、常见问题（FAQ）

Q1：执行 document_index reindex 后搜索反而报错/无结果，日志有 PermissionDenied？

实测定位：命令以 root 执行 → data/index/ 内tantivy 文件（.fast/.idx/.pos/.term）属主变 root → 服务用户 uid 1000 打不开 → 日志实测：[ERROR] [paperless.search] Search index is corrupted or incomplete - rebuilding from scratch. 与 ValueError: Failed to open file for read: IoError { io_error: Os { code: 13, kind: PermissionDenied ... filepath: ".managed.json" } }。解决：chown -R 1000:1000 /opt/paperless/data 后，以应用用户重新 document_index reindex，实测中文检索恢复命中。

Q2：document_importer 传 manifest.json 路径为什么报 manifest 不存在？

参数语义是"包含 manifest.json 的目录"（源码实测 pre_check_manifest_exists 检查的是 source / "manifest.json"）。传目录即可：document_importer /opt/paperless/export。

Q3：恢复导入后文件都在但全文检索无结果？

导入流程自身会跑一次索引（实测 Updating search index... 1/1），但若索引目录存在属主/残留问题仍可能检索空手。标准动作：导入完成后手动 document_index reindex 一次并抽查中文关键词（实测修复）。

Q4：createsuperuser --noinput 不带 DJANGO_SUPERUSER_PASSWORD 会怎样？

实测不报错：正常输出 Superuser created successfully.，但账号密码字段为 Django 的不可用标记（shell 实测 u.password 形如 '!eaRGPtdXhlhZT4REMpxVmcW2m1aUcFHwL06HImh3'，! 前缀=不可登录），该账号需再走一次 changepassword 或 Web 界面设密后才能登录。脚本化一步到位仍推荐 4.13 的 DJANGO_SUPERUSER_PASSWORD 组合。

Q5：cron 里跑这些命令怎么写路径？

源码安装形态：cd /opt/paperless/src && python3 manage.py document_sanity_checker（或绝对路径 /usr/bin/python3 /opt/paperless/src/manage.py ...）；执行用户切到应用运行用户（su -s /bin/bash <运行用户> -c '...'），避免 root 属主问题。

七、参考链接

• 官方管理命令文档：https://docs.paperless-ngx.com/administration/
• 官方 API 文档：https://docs.paperless-ngx.com/api/
• GitHub 仓库源码（management/commands）：https://github.com/paperless-ngx/paperless-ngx/tree/v3.3.3/src/documents/management/commands
• 本站配套文档：《Paperless-ngx 介绍与选型指南》、《Paperless-ngx 3.3.3 Docker Compose 部署指南》、《Paperless-ngx 3.3.3 配置参数详解》