Paperless-ngx 3.3.3 Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上用 Docker Compose 从零部署 Paperless-ngx 3.3.3 完整五组件栈（webserver + Valkey + PostgreSQL + Gotenberg + Tika），覆盖数据持久化、中文 OCR 语言包（tesseract-ocr-chi-sim）实测、超级管理员创建、健康验证、备份与升级。整套流程已在 Ubuntu 22.04 + Docker 29.8.1 环境逐命令实测通过。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Docker：29.8.1（docker --version 实测回显：Docker version 29.8.1, build 4a63305）
Docker Compose 插件：v5.5.1（docker compose version 实测回显：Docker Compose version v5.5.1）
Paperless-ngx：3.3.3（官方最新稳定版，2026-10-22 查询 GitHub Releases/latest 实查；版本溯源与选型见《Paperless-ngx 介绍与选型指南》）
部署目录：/opt/paperless/（compose 文件与四个数据目录所在）
宿主服务端口：8128（本例宿主 8000 已被占用，映射到 8128；无占用时可写 8000:8000）
数据库：PostgreSQL 18；消息代理：Valkey 9（Redis 协议兼容）；文档转换：Gotenberg 8.37；文本抽取：Apache Tika 3.3.1.0

二、镜像选型说明

Paperless-ngx 官方以 Compose 形态发布编排文件，v3.3.3 官方仓库（tag v3.3.3，2026-10-22 下载取证）提供的镜像组合如下：

服务	官方镜像 pin	角色	必选
webserver	`ghcr.io/paperless-ngx/paperless-ngx:latest`（Docker Hub 同步发布 `paperlessngx/paperless-ngx:3.3.3`）	主应用：Web UI、REST API、OCR 消费管线	是
broker	`docker.io/valkey/valkey:9-alpine`	Celery 消息代理（Redis 协议兼容）	是
db	`docker.io/library/postgres:18`	关系数据库	是（也可 SQLite 免装）
gotenberg	`docker.io/gotenberg/gotenberg:8.37`	Chromium 文档转 PDF（.eml 等邮件文件）	否（推荐）
tika	`docker.io/apache/tika:3.3.1.0`	Office 文档文本抽取	否（推荐）

选型解读：

broker 官方已从 Redis 切换为 Valkey：v3.3.3 官方 compose 写的是 valkey/valkey:9-alpine，Paperless 侧仍用 redis:// 协议地址连接（Valkey 与 Redis 协议兼容）。老教程里写 redis:7 也能工作，但跟随官方 pin 更稳。
webserver 建议把 :latest 固定为具体版本号：官方 compose 写 ghcr.io/paperless-ngx/paperless-ngx:latest，生产环境固定到 paperlessngx/paperless-ngx:3.3.3（Docker Hub 官方仓库）可让升级完全可控。
Gotenberg + Tika 是 Office/邮件消费的前提：官方 compose 注释明确 "Office document and email consumption support is optional and provided by Apache Tika"，不带这两个服务则 Word/Excel/PPT/.eml 文档无法入库。
数据库官方示例用 PostgreSQL；个人小规模也可选官方 docker-compose.sqlite.yml 变体（免 db 服务，数据存 data/ 目录），但多用户/大数据量场景 PostgreSQL 更可靠。

💡 技术拓展：消息代理不止 Valkey/Redis 一种。Celery 常见 broker 对比——

代理特点适用场景
Redis/Valkey 轻量、内存型、部署最简单单机/中小规模（Paperless-ngx 官方默认）
RabbitMQ 专业消息队列、可靠性高大规模任务管线
数据库作 broker 零额外组件极小规模（Celery 官方不推荐生产）

Paperless-ngx 官方编排固定采用 Redis 协议代理（现用 Valkey 分支），自托管单机场景无需替换。

代理	特点	适用场景
Redis/Valkey	轻量、内存型、部署最简单	单机/中小规模（Paperless-ngx 官方默认）
RabbitMQ	专业消息队列、可靠性高	大规模任务管线
数据库作 broker	零额外组件	极小规模（Celery 官方不推荐生产）

三、前置条件

已安装 Docker Engine 与 Compose 插件，并验证版本：

docker --version

实测回显：

Docker version 29.8.1, build 4a63305

docker compose version

实测回显：

Docker Compose version v5.5.1

确认目标端口未被占用（本例用 8128）：

ss -ltn | grep 8128 || echo "8128 空闲"

实测回显：

8128 空闲

部署完成后再查，实测回显（服务已监听）：

LISTEN 0      4096         0.0.0.0:8128       0.0.0.0:*
LISTEN 0      4096            [::]:8128          [::]:*

规划运行用户：Paperless 服务默认以容器内 uid/gid 1000 运行，需保证挂载目录对 uid 1000 可写（见第五章）。

四、部署步骤

4.1 目录准备

在 /opt/paperless/ 下创建部署目录与四个数据目录（数据目录归属 uid 1000，与容器内服务用户一致）：

mkdir -p /opt/paperless/{data,media,export,consume}
chown -R 1000:1000 /opt/paperless/{data,media,export,consume}
ls -la /opt/paperless/

实测回显：

total 24
drwxr-xr-x 8 root  root  4096 10月 22 00:29 .
drwxr-xr-x 9 root  root  4096 10月 22 00:23 ..
drwxr-xr-x 2 1000 1000  4096 10月 22 00:29 consume
drwxr-xr-x 3 1000 1000  4096 10月 22 00:36 data
drwxr-xr-x 2 1000 1000  4096 10月 22 00:29 export
drwxr-xr-x 2 1000 1000  4096 10月 22 00:29 media

4.2 编写 docker-compose.yml

在 /opt/paperless/docker-compose.yml 写入以下内容（基于官方 v3.3.3 编排，镜像固定版本号、数据目录改 bind mount、补充中文 OCR 与超管初始化变量）：

name: paperless-ngx-3.3.3-stack

networks:
  pngx:
    driver: bridge

volumes:
  pgdata:
  redisdata:

services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    container_name: paperless-ngx-3.3.3-broker
    restart: unless-stopped
    networks: [pngx]
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:18
    container_name: paperless-ngx-3.3.3-db
    restart: unless-stopped
    networks: [pngx]
    volumes:
      - pgdata:/var/lib/postgresql
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: paperless

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.37
    container_name: paperless-ngx-3.3.3-gotenberg
    restart: unless-stopped
    networks: [pngx]
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=^file:///tmp/.*"

  tika:
    image: docker.io/apache/tika:3.3.1.0
    container_name: paperless-ngx-3.3.3-tika
    restart: unless-stopped
    networks: [pngx]

  webserver:
    image: paperlessngx/paperless-ngx:3.3.3
    container_name: paperless-ngx-3.3.3-web
    restart: unless-stopped
    networks: [pngx]
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8128:8000"
    volumes:
      - /opt/paperless/data:/usr/src/paperless/data
      - /opt/paperless/media:/usr/src/paperless/media
      - /opt/paperless/export:/usr/src/paperless/export
      - /opt/paperless/consume:/usr/src/paperless/consume
    environment:
      USERMAP_UID: 1000
      USERMAP_GID: 1000
      http_proxy: http://192.168.1.62:7897
      https_proxy: http://192.168.1.62:7897
      no_proxy: localhost,127.0.0.1,broker,db,gotenberg,tika
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: paperless
      PAPERLESS_SECRET_KEY: "pngx-3f8a1c92e7d64b05a1e3c8f2d6b94a07c5e1f8d3b6a29c405e7f1d8b3a6c92e4"
      PAPERLESS_TIME_ZONE: Asia/Shanghai
      PAPERLESS_OCR_LANGUAGE: chi_sim+eng
      PAPERLESS_OCR_LANGUAGES: chi-sim
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      PAPERLESS_URL: http://192.168.1.62:8128
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: q1w2e3r4
      PAPERLESS_ADMIN_MAIL: admin@example.com

逐项说明（关键项）：

name: paperless-ngx-3.3.3-stack：显式指定 Compose 项目名，避免与其他项目的 compose 栈互相干扰。
networks.pngx：五个服务同处一张自定义 bridge 网络，服务名即 DNS 名（db、broker、gotenberg、tika）。
db 的 pgdata:/var/lib/postgresql：PostgreSQL 18 官方镜像的数据目录是 /var/lib/postgresql（注意不是老版本的 /var/lib/postgresql/data），官方 v3.3.3 编排同样挂这一层。
gotenberg 的 command：来自官方编排原文，禁用 Chromium 内 JS 并限制文件协议访问，转 PDF 时防跟踪像素/恶意脚本。
USERMAP_UID/GID: 1000：容器内服务进程以 uid 1000 运行并与宿主目录属主对齐（不设时默认也是 1000，显式写出防止误解）。
http_proxy/https_proxy/no_proxy：给 webserver 初始脚本访问 Debian 软件源装 OCR 语言包用；no_proxy 必须包含四个内部服务名，否则内部 HTTP 调用（Tika/Gotenberg/Redis/DB 健康检查）会被错误地推到代理上。网络无限制的服务器可直接删掉这三行。
PAPERLESS_OCR_LANGUAGE: chi_sim+eng：OCR 识别语言（中文简体+英文）。
PAPERLESS_OCR_LANGUAGES: chi-sim：容器启动时自动安装的 Tesseract 语言包名（Debian 包名用连字符），这是实测出的关键写法，详见第七章与第十一章。
PAPERLESS_SECRET_KEY：会话签名密钥，用 python3 -c "import secrets; print(secrets.token_urlsafe(64))" 自行生成，切勿照抄本文示例值。
PAPERLESS_ADMIN_USER/PASSWORD/MAIL：首次启动自动创建超级管理员；密码示例为测试口令 q1w2e3r4，生产环境务必替换。
PAPERLESS_URL：对外访问地址，用于邮件里链接、CSRF 校验等；按实际域名/IP 修改。

4.3 拉取镜像

cd /opt/paperless && docker compose pull

实测回显：

 Image docker.io/gotenberg/gotenberg:8.37 Pulling
 Image docker.io/valkey/valkey:9-alpine Pulling
 Image docker.io/apache/tika:3.3.1.0 Pulling
 Image docker.io/library/postgres:18 Pulled
 Image docker.io/valkey/valkey:9-alpine Pulled
 Image docker.io/gotenberg/gotenberg:8.37 Pulled
 Image paperlessngx/paperless-ngx:3.3.3 Pulled
 Image docker.io/apache/tika:3.3.1.0 Pulled

4.4 启动

docker compose up -d

实测回显：

[+] Running 6/6
 ✔ Network paperless-ngx-33-3-stack_pngx  Created
 ✔ Container paperless-ngx-3.3.3-tika      Started
 ✔ Container paperless-ngx-3.3.3-broker    Started
 ✔ Container paperless-ngx-3.3.3-db        Started
 ✔ Container paperless-ngx-3.3.3-gotenberg Started
 ✔ Container paperless-ngx-3.3.3-web       Started

4.5 首次启动日志解读

首次启动需要完成数据库迁移、语言包安装、超管创建等初始化，观察 webserver 日志：

docker compose logs -f webserver

实测关键日志（节选，按出现顺序）：

[init-tesseract-langs] Checking if additional teseract languages needed
Installing languages...
[init-tesseract-langs] Installing package tesseract-ocr-chi-sim...
[init-tesseract-langs] Installed tesseract-ocr-chi-sim
[init-tesseract-langs] Additional packages installed
[init-migrations] Apply database migrations...
Applying documents.0001_initial... OK
  （中间省略数十行迁移，均以 OK 结尾）
[init-superuser] Creating superuser...
Created superuser "admin" with provided password.
[init-superuser] Superuser creation done
[init-checks] Running Django checks
System check identified no issues (0 silenced).
[INFO] Listening at: http://:::8000

出现 [INFO] Listening at: http://:::8000 即启动完成，Ctrl+C 退出日志跟踪。

⚠️ 注意：语言包安装发生在每次容器启动的初始化阶段（不是固化在镜像里），所以启动脚本要联网访问 Debian 软件源。若服务器网络受限，必须给 webserver 配置 http_proxy/https_proxy（见 4.2 与第十一章 FAQ-1）。

4.6 超级管理员

本指南通过 PAPERLESS_ADMIN_USER/PASSWORD/MAIL 环境变量自动创建，日志已确认 Created superuser "admin" with provided password.。补建其他管理员时，在 webserver 内执行（也可用同名环境变量新建第二个管理员）：

docker compose exec -e DJANGO_SUPERUSER_PASSWORD=q1w2e3r4 webserver python3 /usr/src/paperless/src/manage.py createsuperuser --noinput --username root --email root@example.com

实测回显：

Superuser created successfully.

4.7 健康验证

服务状态（webserver 带 healthcheck，出现 healthy 为就绪）：

docker compose ps --format 'table {{.Name}}\t{{.Status}}'

实测回显：

NAME                            STATUS
paperless-ngx-3.3.3-broker      Up 19 minutes
paperless-ngx-3.3.3-db          Up 19 minutes
paperless-ngx-3.3.3-gotenberg   Up 19 minutes
paperless-ngx-3.3.3-tika        Up 19 minutes
paperless-ngx-3.3.3-web         Up 3 minutes (healthy)

Web 入口与登录页：

curl -sS -o /dev/null -w 'root: %{http_code} -> %{redirect_url}\n' http://localhost:8128/
curl -sS -o /dev/null -w 'login page: %{http_code}\n' http://localhost:8128/accounts/login/

实测回显：

root: 302 -> http://localhost:8128/accounts/login/?next=/
login page: 200

浏览器访问 http://<服务器IP>:8128，用 admin / q1w2e3r4 登录即见文档仪表盘。

REST API 取 token（后续脚本化调用凭证）：

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

实测回显：

{"token":"911a8bda1744ca59e45e63ce2fd0b498b2203b75"}

中文 OCR 端到端验证：向消费目录投放一份纯图像中文 PDF（由扫描仪产出或图片转 PDF），观察消费日志并按中文关键词全文检索：

[INFO] [paperless.management.consumer] File is stable: /usr/src/paperless/consume/中文识别测试-FA-2026-1022.pdf
[INFO] [paperless.management.consumer] Adding /usr/src/paperless/consume/中文识别测试-FA-2026-1022.pdf to the task queue
[INFO] [paperless.consumer] [4e181c38] Consuming 中文识别测试-FA-2026-1022.pdf
[INFO] [ocrmypdf._graft] [4e181c38] Parsing 1 pages with HocrParser
[INFO] [paperless.consumer] [4e181c38] Document 2026-10-22 中文识别测试-FA-2026-1022 consumption finished

检索验证（云栖科技 为该测试件中的公司名）：

curl -sS -H "Authorization: Token 911a8bda1744ca59e45e63ce2fd0b498b2203b75" "http://localhost:8128/api/documents/?query=云栖科技"

实测回显（节选）：

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

中文 OCR 与全文检索链路验证通过。

五、数据持久化说明

挂载	类型	容器内路径	内容	重要性
`/opt/paperless/data`	bind mount	`/usr/src/paperless/data`	应用数据：全文索引、分类器模型、密文密钥等	★★★
`/opt/paperless/media`	bind mount	`/usr/src/paperless/media`	文档本体：originals（原始件）、archive（PDF/A 归档件）、thumbnails（缩略图）	★★★
`/opt/paperless/export`	bind mount	`/usr/src/paperless/export`	导出目录（document_exporter 备份落点）	★★
`/opt/paperless/consume`	bind mount	`/usr/src/paperless/consume`	消费目录：放入的文件会被自动扫描入库	★★
`pgdata`	named volume	`/var/lib/postgresql`	PostgreSQL 数据	★★★
`redisdata`	named volume	`/data`	Valkey 队列数据（可丢，重启自动恢复任务态）	★

持久化验证：docker compose restart 后文档、索引、用户均完好；对 bind mount 目录的属主要求见第五章说明。特别注意 named volume 只随 docker compose down -v 删除，普通 down/restart 均保留。

⚠️ 注意：bind mount 目录必须对 uid 1000 可写。若目录属主是其他用户，会出现消费任务失败、搜索索引报 PermissionDenied 等问题（第十一章 FAQ-4 有真实排障实录）。

六、环境变量表

本部署实际使用的全部环境变量与实测取值：

变量	实测取值	作用
USERMAP_UID / USERMAP_GID	1000 / 1000	容器内服务进程运行 uid/gid，需与挂载目录属主一致
http_proxy / https_proxy	http://192.168.1.62:7897	启动时装 OCR 语言包访问 Debian 源用（网络受限时需要）
no_proxy	localhost,127.0.0.1,broker,db,gotenberg,tika	内部服务调用不走代理
PAPERLESS_REDIS	redis://broker:6379	Celery 消息代理地址（Valkey 兼容 Redis 协议）
PAPERLESS_DBHOST	db	数据库主机名（compose 服务名）
PAPERLESS_DBENGINE	postgresql	数据库引擎（postgresql/sqlite/mariadb/mysql）
PAPERLESS_DBNAME / DBUSER / DBPASS	paperless / paperless / paperless	数据库库名/用户/密码
PAPERLESS_SECRET_KEY	见 4.2	会话与签名密钥，必须唯一且不外泄
PAPERLESS_TIME_ZONE	Asia/Shanghai	时区（默认 UTC）
PAPERLESS_OCR_LANGUAGE	chi_sim+eng	OCR 识别语言（Tesseract 语言代码，多语言用 `+` 连接）
PAPERLESS_OCR_LANGUAGES	chi-sim	启动时自动安装的 Tesseract 语言包（Debian 包名，连字符）
PAPERLESS_TIKA_ENABLED	1	启用 Tika 文本抽取
PAPERLESS_TIKA_ENDPOINT	http://tika:9998	Tika 服务地址
PAPERLESS_TIKA_GOTENBERG_ENDPOINT	http://gotenberg:3000	Gotenberg 服务地址
PAPERLESS_URL	http://192.168.1.62:8128	对外访问地址（CSRF/邮件链接用）
PAPERLESS_ADMIN_USER / PASSWORD / MAIL	admin / q1w2e3r4 / admin@example.com	首次启动自动建超管

参数含义与官方默认值的逐项详解见《Paperless-ngx 3.3.3 配置参数详解》。

七、配置参数说明

语言包参数必须区分两种拼写：PAPERLESS_OCR_LANGUAGE 用 Tesseract 语言代码（chi_sim，下划线）；PAPERLESS_OCR_LANGUAGES 是启动安装的 Debian 包名后缀（chi-sim，连字符，对应包 tesseract-ocr-chi-sim）。本指南实测：写 PAPERLESS_OCR_LANGUAGES: chi_sim 时启动日志报 [init-tesseract-langs] Skipped tesseract-ocr-chi_sim: Package not found! :(（脚本直接把语言代码拼到 tesseract-ocr- 后面），改为 chi-sim 后日志正常 [init-tesseract-langs] Installed tesseract-ocr-chi-sim。
语言包安装是启动期行为：语言包装在容器文件层，容器重建（up -d 配置变更触发 recreate）后会按 PAPERLESS_OCR_LANGUAGES 重装，因此该变量必须常驻 compose，手工 apt-get install 的语言包在重建后会丢失（实测复现过）。
识别语言与安装语言的关系：PAPERLESS_OCR_LANGUAGE 只能使用已安装的语言；未安装时启动自检直接失败：SystemCheckError: The selected ocr language chi_sim is not installed.（实测回显）。
代理变量只影响初始化脚本：http_proxy/https_proxy 仅用于启动时装语言包访问软件源；no_proxy 缺少内部服务名会导致 Tika/Gotenberg/DB 健康检查走代理而启动失败，务必带上。
超管创建的三种途径：环境变量自动创建（首次启动）；createsuperuser --noinput（脚本化，配 DJANGO_SUPERUSER_PASSWORD）；createsuperuser 交互式（逐项输入）。三者实测均可用。

八、配置文件挂载

Paperless-ngx 的源码安装形态用 paperless.conf 配置文件，而官方 Docker 镜像的配置入口是环境变量（容器内 /usr/src/paperless/paperless.conf 仅为源码安装形态服务）。Compose 形态下推荐的配置组织方式是官方的 env_file 模式——把上述 environment: 中的 PAPERLESS_* 变量移入独立文件 docker-compose.env，compose 里改为：

  webserver:
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql

官方 v3.3.3 发布的 docker-compose.env 模板即此形态（docker/compose/docker-compose.env @ tag v3.3.3，2026-10-22 下载取证），其头部注释标明两项必看配置：PAPERLESS_SECRET_KEY（必填，附生成命令）与 PAPERLESS_OCR_LANGUAGE（默认 eng）。environment: 与 env_file: 同时存在时，environment: 优先级更高，可把少数随环境变化的键（如代理地址）留在外层覆盖。全部参数的含义、默认值与生产推荐值见配置参数详解篇。

九、等价 docker run 参考

不使用 Compose 时，单跑 webserver 的等价命令如下（其余四个服务同理，需自行组网；仅作理解用，生产建议 Compose）：

docker network create pngx
docker run -d --name paperless-web --network pngx \
  -p 8128:8000 \
  -v /opt/paperless/data:/usr/src/paperless/data \
  -v /opt/paperless/media:/usr/src/paperless/media \
  -v /opt/paperless/export:/usr/src/paperless/export \
  -v /opt/paperless/consume:/usr/src/paperless/consume \
  -e PAPERLESS_REDIS=redis://broker:6379 \
  -e PAPERLESS_DBHOST=db \
  -e PAPERLESS_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(64))") \
  paperlessngx/paperless-ngx:3.3.3

十、常用运维命令

10.1 日常操作

docker compose ps                      # 状态一览
docker compose logs -f webserver       # 跟踪主服务日志
docker compose restart webserver       # 仅重启主服务
docker compose stop                    # 停整栈（保留数据）
docker compose up -d                   # 再次拉起

docker compose stop 与 up -d 之间数据不丢（bind mount 与 named volume 均保留），实测重启后文档与登录态均完好。

10.2 数据库备份（pg_dump）

docker exec paperless-ngx-3.3.3-db pg_dump -U paperless paperless | gzip > /opt/paperless/paperless-db-$(date +%Y%m%d).sql.gz
ls -lh /opt/paperless/paperless-db-*.sql.gz

实测回显：

-rw-r--r-- 1 root root 29K 10月 22 00:45 /opt/paperless/paperless-db-20261022.sql.gz

10.3 全量导出备份（document_exporter）

docker compose exec webserver python3 /usr/src/paperless/src/manage.py document_exporter /usr/src/paperless/export

实测回显：

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

导出完成后 /opt/paperless/export/ 内容实测：

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 条记录，含用户/标签/文档等全量模型数据），是恢复的依据。命令详解见《Paperless-ngx 3.3.3 常用 CLI 命令与工具详解》。

10.4 恢复演练（document_importer，实测全过程）

停 webserver、清空数据库 schema 与数据目录，模拟灾难：

docker compose stop webserver
docker exec paperless-ngx-3.3.3-db psql -U paperless -c 'DROP SCHEMA public CASCADE; CREATE SCHEMA public;'
rm -rf /opt/paperless/data/* /opt/paperless/media/*
docker compose start webserver

psql 实测回显（节选）：

NOTICE:  drop cascades to 75 other objects
DETAIL:  drop cascades to table django_migrations
drop cascades to table documents_document
DROP SCHEMA
CREATE SCHEMA

重启后日志实测：迁移全部重建 + Created superuser "admin" with provided password.（空库实例就绪）。

docker compose exec webserver python3 /usr/src/paperless/src/manage.py document_importer /usr/src/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

验证：文档列表恢复（/api/documents/ 返回 1 条，内容完整），媒体文件回位（media/documents/originals/0000001.pdf、media/documents/archive/0000001.pdf 均在）。⚠️ 若导入后全文检索无结果，是索引文件属主问题，执行 docker compose exec webserver python3 /usr/src/paperless/src/manage.py document_index reindex 重建即可（真实排障过程见第十一章 FAQ-4）。

10.5 升级

cd /opt/paperless
docker compose exec webserver python3 /usr/src/paperless/src/manage.py document_exporter /usr/src/paperless/export   # 1. 升级前全量备份
docker compose pull                                                                                                   # 2. 拉新版镜像（先把 yml 中版本号改到目标版）
docker compose up -d                                                                                                  # 3. 滚动重建，启动时自动跑迁移

升级要点：版本号写死在 image: 字段，改后 pull + up -d 即完成；启动日志会自动执行新增数据库迁移（Applying documents.xxxx... OK）；回滚 = 把版本号改回旧版再 up -d，但数据库已迁移到新 schema 后不能直接回滚，必须用升级前的导出备份在新实例上恢复。截至 2026-10-22 官方最新稳定版即 3.3.3，暂无更新版本可做实测升级。

10.6 卸载

cd /opt/paperless
docker compose down      # 停止并删服务（保留 named volume）
docker compose down -v   # 连 pgdata/redisdata 卷一起删（危险，数据全清）
rm -rf /opt/paperless    # 删配置与 bind mount 数据（先确认备份已带走）

十一、常见问题（FAQ）

Q1：启动报 The selected ocr language chi_sim is not installed，同时日志有 `Skipped tesseract-ocr-chi_sim: Package not found! :(

实测定位：init 脚本把 PAPERLESS_OCR_LANGUAGES 的值直接拼成 Debian 包名 tesseract-ocr-chi_sim（下划线），而 Debian 实际包名是 tesseract-ocr-chi-sim（连字符），apt-cache show 验证：下划线名 NOT FOUND、连字符名 EXISTS。解决：PAPERLESS_OCR_LANGUAGES 写连字符形式 chi-sim（识别语言 PAPERLESS_OCR_LANGUAGE 仍写下划线 chi_sim）。

Q2：语言包安装一直卡住/失败（直连 Debian 源超时）

实测定位：容器内直连 deb.debian.org 下载极慢，init 的 apt-get 长时间占锁；手动安装时报 Could not get lock /var/lib/apt/lists/lock. It is held by process 111 (apt-get)。解决：给 webserver 服务加 http_proxy/https_proxy 环境变量（走可用代理，实测下载速率从超时恢复到 6.4 MB/s），并配 no_proxy: localhost,127.0.0.1,broker,db,gotenberg,tika 防内部调用误走代理。

Q3：手动 apt-get install tesseract-ocr-chi-sim 装好后，某次 up -d 又报语言未安装

实测定位：语言包装在容器文件层，docker compose up -d 因配置变更重建容器后文件层重置（tesseract --list-langs 只剩 deu/eng/fra/ita/osd/spa）。解决：把 PAPERLESS_OCR_LANGUAGES: chi-sim 常驻 compose，让每次启动自动安装；不要依赖手工安装。

Q4：恢复/导入后全文检索无结果，日志报 Search index is corrupted or incomplete - rebuilding from scratch 与 PermissionDenied

实测定位：3.3.3 的搜索引擎已从 Whoosh 换成 tantivy（data/index/ 下是 .fast/.idx/.pos/.term 格式文件）。管理命令若以 root 身份执行（docker exec 默认用户），生成的索引文件属主为 root，而容器内服务进程以 uid 1000（paperless 用户，实测 id paperless 回显 uid=1000(paperless) gid=1000(paperless)）运行，读不了 root 属主的索引文件 → 报 ValueError: Failed to open file for read: IoError ... PermissionDenied, filepath: ".managed.json"。解决：宿主数据目录 chown -R 1000:1000；管理命令统一用 docker compose exec webserver ...（Compose 下 exec 落到与镜像 USERMAP 一致的用户）或显式 -u paperless 执行，然后 document_index reindex 重建索引，实测检索恢复。

Q5：OCR 时日志警告 No installed font has glyphs for the detected 'chi_sim' text ('中' U+4E2D ...)

实测定位：OCR 文本层 graft 时容器内无 CJK 渲染字体，警告说文字"以不可见文本层加入，仍可搜索/复制，但在 PDF 查看器里高亮显示为空白"。解决：需要可见高亮时按警告提示安装 NotoSansSC 字体族；仅做检索可忽略，实测该警告不影响全文检索（云栖科技 检索命中）。

Q6：消费日志有 Ghostscript 10.5.1 drops ToUnicode mappings ... Please upgrade to Ghostscript 10.7.0 or later 警告

实测定位：镜像内置 Ghostscript 10.5.1 写 PDF/A 时会丢弃展开为多字符的 ToUnicode 映射，影响复杂文字连字的复制/搜索精度。属上游 ocrmypdf 提示，等待官方镜像升级 Ghostscript 即可，中文实测检索未受影响。

十二、参考链接

官方 Docker 安装文档：https://docs.paperless-ngx.com/setup/
官方 Compose 编排文件（tag v3.3.3）：https://github.com/paperless-ngx/paperless-ngx/tree/v3.3.3/docker/compose
官方镜像（Docker Hub）：https://hub.docker.com/r/paperlessngx/paperless-ngx
官方镜像（ghcr.io）：https://github.com/paperless-ngx/paperless-ngx/pkgs/container/paperless-ngx
配置参数全解：https://docs.paperless-ngx.com/configuration/
管理命令全解：https://docs.paperless-ngx.com/administration/
本站配套文档：《Paperless-ngx 介绍与选型指南》、《Paperless-ngx 3.3.3 配置参数详解》、《Paperless-ngx 3.3.3 常用 CLI 命令与工具详解》