Paperless-ngx 3.3.3 配置参数详解

目标：把 Paperless-ngx 3.3.3 的配置参数按域逐项讲清——含义、官方默认值与实测行为，并给出生产配置模板。参数清单以官方 v3.3.3 发布的 paperless.conf.example 与 docker-compose.env 模板为基准（2026-10-22 下载取证），实测行为来自 Ubuntu 22.04 + Docker Compose 部署环境（部署过程见《Paperless-ngx 3.3.3 Docker Compose 部署指南》）。

一、环境信息

Paperless-ngx：3.3.3（官方最新稳定版，2026-10-22 查询 GitHub Releases/latest；项目背景见《Paperless-ngx 介绍与选型指南》）
参数基准文件：官方仓库 tag v3.3.3 的 paperless.conf.example（94 行）与 docker/compose/docker-compose.env，均为 2026-10-22 从官方 raw 下载取证
实测环境：Ubuntu 22.04 + Docker 29.8.1 + Compose v5.5.1，五组件栈（webserver/Valkey/PostgreSQL 18/Gotenberg 8.37/Tika 3.3.1.0），时区 Asia/Shanghai，OCR 语言 chi_sim+eng
验证过的行为：中文 OCR 全文检索、docx 经 Tika/Gotenberg 入库、超管自动创建、语言包自动安装、USERMAP 属主映射（均有实测日志，见各参数行）

二、前置条件

已完成 Paperless-ngx 3.3.3 部署并能登录 Web 界面（从零部署见部署指南篇）。
理解两种部署形态的配置入口差异：源码安装用配置文件 paperless.conf（systemd 服务引用）；官方 Compose 部署用环境变量（environment: 或 env_file: 注入），服务进程不读 paperless.conf。本篇参数名在两种形态下完全一致，仅注入方式不同。
修改参数后需要重启服务生效：源码安装重启 systemd 服务；Compose 形态 docker compose up -d（配置变更会自动重建 webserver）。

三、参数查看与修改方式

源码安装形态：编辑应用目录下的 paperless.conf（每行 KEY=value），重启服务生效。官方模板 paperless.conf.example 按域分组注释，全部参数默认值以 # 注释行形式给出。
Compose 部署形态：参数写在 compose 的 environment: 块或独立 docker-compose.env 文件（env_file: 引用，官方模板即此形态）；两者同时存在时 environment: 优先。修改后 docker compose up -d 重建 webserver 生效。
查看运行中生效值：在应用运行环境内执行 env | grep PAPERLESS，逐行核对键值。
注意事项：PAPERLESS_SECRET_KEY 在官方 docker-compose.env 模板中被标注为 Required（必填）并附生成命令；其余参数不设即用内置默认值。

四、参数总览

按官方 paperless.conf.example 的分组顺序给出全量参数速查（默认值即官方模板注释行原值）：

域	参数	官方默认值
必需服务	PAPERLESS_REDIS	redis://localhost:6379
必需服务	PAPERLESS_DBHOST	localhost
必需服务	PAPERLESS_DBPORT	5432
必需服务	PAPERLESS_DBNAME	paperless
必需服务	PAPERLESS_DBUSER	paperless
必需服务	PAPERLESS_DBPASS	paperless
必需服务	PAPERLESS_DBSSLMODE	prefer
必需服务	PAPERLESS_DBENGINE	postgresql（官方 compose 使用）
路径目录	PAPERLESS_CONSUMPTION_DIR	../consume
路径目录	PAPERLESS_DATA_DIR	../data
路径目录	PAPERLESS_EMPTY_TRASH_DIR	（空，= 直接删除）
路径目录	PAPERLESS_MEDIA_ROOT	../media
路径目录	PAPERLESS_STATICDIR	../static
路径目录	PAPERLESS_FILENAME_FORMAT	（空，= 内置命名）
路径目录	PAPERLESS_FILENAME_FORMAT_REMOVE_NONE	（空）
安全托管	PAPERLESS_SECRET_KEY	change-me（必填，须替换）
安全托管	PAPERLESS_URL	（空）
安全托管	PAPERLESS_CSRF_TRUSTED_ORIGINS	可由 PAPERLESS_URL 推导
安全托管	PAPERLESS_ALLOWED_HOSTS	可由 PAPERLESS_URL 推导
安全托管	PAPERLESS_CORS_ALLOWED_HOSTS	可由 PAPERLESS_URL 推导
安全托管	PAPERLESS_FORCE_SCRIPT_NAME	（空）
安全托管	PAPERLESS_STATIC_URL	/static/
安全托管	PAPERLESS_AUTO_LOGIN_USERNAME	（空）
安全托管	PAPERLESS_COOKIE_PREFIX	（空）
安全托管	PAPERLESS_ENABLE_HTTP_REMOTE_USER	false
安全托管	PAPERLESS_SOCIAL_ACCOUNT_SYNC_SUPERUSER_GROUP	（空）
安全托管	PAPERLESS_SOCIAL_ACCOUNT_SYNC_STAFF_GROUP	（空）
OCR	PAPERLESS_OCR_LANGUAGE	eng
OCR	PAPERLESS_OCR_MODE	skip
OCR	PAPERLESS_OCR_SKIP_ARCHIVE_FILE	never
OCR	PAPERLESS_OCR_OUTPUT_TYPE	pdfa
OCR	PAPERLESS_OCR_PAGES	1（官方模板示例行）
OCR	PAPERLESS_OCR_IMAGE_DPI	300
OCR	PAPERLESS_OCR_CLEAN	clean
OCR	PAPERLESS_OCR_DESKEW	true
OCR	PAPERLESS_OCR_ROTATE_PAGES	true
OCR	PAPERLESS_OCR_ROTATE_PAGES_THRESHOLD	12.0
OCR	PAPERLESS_OCR_USER_ARGS	{}
OCR	PAPERLESS_CONVERT_MEMORY_LIMIT	0
OCR	PAPERLESS_CONVERT_TMPDIR	/var/tmp/paperless
软件调优	PAPERLESS_TASK_WORKERS	1
软件调优	PAPERLESS_THREADS_PER_WORKER	1
软件调优	PAPERLESS_TIME_ZONE	UTC
软件调优	PAPERLESS_CONSUMER_POLLING_INTERVAL	10
软件调优	PAPERLESS_CONSUMER_DELETE_DUPLICATES	false
软件调优	PAPERLESS_CONSUMER_RECURSIVE	false
软件调优	PAPERLESS_CONSUMER_IGNORE_PATTERNS	[]（内置默认模式）
软件调优	PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS	false
软件调优	PAPERLESS_CONSUMER_ENABLE_BARCODES	false
软件调优	PAPERLESS_CONSUMER_BARCODE_STRING	PATCHT
软件调优	PAPERLESS_CONSUMER_BARCODE_UPSCALE	0.0
软件调优	PAPERLESS_CONSUMER_BARCODE_DPI	300
软件调优	PAPERLESS_CONSUMER_ENABLE_TAG_BARCODE	false
软件调优	PAPERLESS_CONSUMER_TAG_BARCODE_MAPPING	{"TAG:(.*)": "\g<1>"}
软件调优	PAPERLESS_CONSUMER_TAG_BARCODE_SPLIT	false
软件调优	PAPERLESS_CONSUMER_ENABLE_COLLATE_DOUBLE_SIDED	false
软件调优	PAPERLESS_CONSUMER_COLLATE_DOUBLE_SIDED_SUBDIR_NAME	double-sided
软件调优	PAPERLESS_CONSUMER_COLLATE_DOUBLE_SIDED_TIFF_SUPPORT	false
软件调优	PAPERLESS_PRE_CONSUME_SCRIPT	（空）
软件调优	PAPERLESS_POST_CONSUME_SCRIPT	（空）
软件调优	PAPERLESS_FILENAME_DATE_ORDER	（空）
软件调优	PAPERLESS_FILENAME_PARSE_TRANSFORMS	[]
软件调优	PAPERLESS_NUMBER_OF_SUGGESTED_DATES	5
软件调优	PAPERLESS_THUMBNAIL_FONT_NAME	（空，用内置字体）
软件调优	PAPERLESS_IGNORE_DATES	（空）
软件调优	PAPERLESS_ENABLE_UPDATE_CHECK	（空）
Tika	PAPERLESS_TIKA_ENABLED	false
Tika	PAPERLESS_TIKA_ENDPOINT	http://localhost:9998
Tika	PAPERLESS_TIKA_GOTENBERG_ENDPOINT	http://localhost:3000
二进制	PAPERLESS_CONVERT_BINARY	/usr/bin/convert
二进制	PAPERLESS_GS_BINARY	/usr/bin/gs
Compose 部署专属	USERMAP_UID / USERMAP_GID	1000 / 1000（官方默认映射）
Compose 部署专属	PAPERLESS_ADMIN_USER / PASSWORD / MAIL	（空，不自动建超管）

⚠️ 注意：上表"官方默认值"列逐行来自 paperless.conf.example 的注释行原文与官方 docker-compose.env 注释；PAPERLESS_DBENGINE 与 Compose 部署专属三组来自官方 compose 编排与官方发布约定，不在 conf 模板内。

五、核心参数分类详解

5.1 必需服务类（数据库与消息代理）

这一组决定 Paperless 连哪里取数据、往哪里发任务。源码安装默认全指向 localhost（同机部署）；Compose 部署改为服务名。

PAPERLESS_REDIS（默认 redis://localhost:6379）：Celery 消息代理地址。Compose 形态实测值 redis://broker:6379——注意官方 broker 已采用 Valkey（编排引用 valkey/valkey:9-alpine），但连接地址仍是 redis:// 协议头，实测工作正常。
PAPERLESS_DBHOST（默认 localhost）：数据库主机。Compose 形态写服务名 db。
PAPERLESS_DBPORT（默认 5432）：PostgreSQL 端口，一般不改。
PAPERLESS_DBNAME / PAPERLESS_DBUSER / PAPERLESS_DBPASS（默认均为 paperless）：库名/用户/密码。与 db 服务的 POSTGRES_DB/POSTGRES_USER/POSTGRES_PASSWORD 三个变量一一对应，改必须成对改。
PAPERLESS_DBSSLMODE（默认 prefer）：数据库连接 SSL 模式，内网自托管保持默认即可。
PAPERLESS_DBENGINE（官方 compose 实测取值 postgresql）：数据库引擎标识，可选 postgresql/sqlite/mariadb/mysql。SQLite 形态不需要 db 服务，直接省略本组参数。

5.2 路径与目录类

PAPERLESS_CONSUMPTION_DIR（默认 ../consume）：消费目录。文件放入后由守护进程自动扫描入库；实测投递中文 PDF 约 10 秒内被拾取（日志 File is stable → Adding ... to the task queue）。Compose 部署形态该目录固定挂载到 /usr/src/paperless/consume。
PAPERLESS_DATA_DIR（默认 ../data）：应用数据目录（全文索引、分类器模型等），Compose 部署形态挂载 /usr/src/paperless/data。
PAPERLESS_MEDIA_ROOT（默认 ../media）：文档本体目录（originals/archive/thumbnails），Compose 部署形态挂载 /usr/src/paperless/media。
PAPERLESS_EMPTY_TRASH_DIR（默认空）：设置后删除的文档先移入该回收站目录而非直接删除，建议生产设置以防误删。
PAPERLESS_STATICDIR（默认 ../static）：静态文件目录，一般不动。
PAPERLESS_FILENAME_FORMAT（默认空，用内置命名）：归档文件命名模板，可用变量如 {correspondent}/{created_year}/{title}；不设时用"日期标题"内置格式（实测导出文件名形如 2026-10-22 中文识别测试-FA-2026-1022.pdf）。
PAPERLESS_FILENAME_FORMAT_REMOVE_NONE（默认空）：命名模板变量取值缺失（如无通讯对象）时，设 true 移除该段而非留 "none"。

5.3 安全与托管类

PAPERLESS_SECRET_KEY（模板占位 change-me，必填）：会话签名密钥。官方 docker-compose.env 注释给出生成命令 python3 -c "import secrets; print(secrets.token_urlsafe(64))"。实测部署用随机 64 位串启动正常。⚠️ 换密钥会使现有会话失效，勿随意轮换。
PAPERLESS_URL（默认空）：对外访问地址。设置后自动推导 CSRF/ALLOWED_HOSTS/CORS 三项（官方模板注释："can be set using PAPERLESS_URL"）。实测取值 http://192.168.1.62:8128。反代域名场景写 https://paperless.example.com。
PAPERLESS_CSRF_TRUSTED_ORIGINS / PAPERLESS_ALLOWED_HOSTS / PAPERLESS_CORS_ALLOWED_HOSTS（默认空，可由 PAPERLESS_URL 推导）：仅在多域名/特殊反代下需要显式展开。
PAPERLESS_FORCE_SCRIPT_NAME（默认空）与 PAPERLESS_STATIC_URL（默认 /static/）：子路径发布用（如 https://example.com/paperless/），直连部署不设。
PAPERLESS_AUTO_LOGIN_USERNAME（默认空）：设为已有用户名则访问即自动以该用户登录，仅适合完全内网的只读大屏场景，生产勿用。
PAPERLESS_COOKIE_PREFIX（默认空）：同域多实例时给 Cookie 加前缀防互踩。
PAPERLESS_ENABLE_HTTP_REMOTE_USER（默认 false）：开启后信任反向代理传入的 Remote-User 头做 SSO，必须配合代理端认证才安全。
PAPERLESS_SOCIAL_ACCOUNT_SYNC_SUPERUSER_GROUP / STAFF_GROUP（默认空）：OAuth/SSO 登录用户自动并入指定组的组名。
PAPERLESS_ADMIN_USER / PAPERLESS_ADMIN_PASSWORD / PAPERLESS_ADMIN_MAIL（默认空，Compose 部署专属）：首次启动自动创建超级管理员。实测 PAPERLESS_ADMIN_USER=admin + 密码启动后日志输出 Created superuser "admin" with provided password.；已存在同名用户时跳过（日志 Did not create superuser, a user admin already exists）。
USERMAP_UID / USERMAP_GID（默认 1000/1000，Compose 部署专属）：服务进程运行身份。实测不设置时服务以 paperless 用户（id paperless → uid=1000(paperless) gid=1000(paperless)）运行；挂载目录属主必须与其一致，否则触发搜索索引 PermissionDenied（排障实录见部署指南篇 FAQ-4）。

5.4 OCR 类（识别质量核心）

PAPERLESS_OCR_LANGUAGE（默认 eng）：识别语言，用 Tesseract 语言代码，多语言 + 连接。实测 chi_sim+eng 后中文扫描件正确识别并可全文检索（检索"云栖科技"命中）。⚠️ 只能使用已安装语言：未安装时启动自检直接失败，实测回显 SystemCheckError: The selected ocr language chi_sim is not installed.
PAPERLESS_OCR_LANGUAGES（默认空，Compose 部署专属）：启动时自动安装的 Tesseract 语言包列表（空格分隔多个）。⚠️ 值是 Debian 包名后缀（连字符）：中文简体写 chi-sim（装 tesseract-ocr-chi-sim），写语言代码 chi_sim 会因包名 tesseract-ocr-chi_sim 不存在而跳过（实测日志 Skipped tesseract-ocr-chi_sim: Package not found! :(）。语言包装在服务运行环境的文件层，webserver 重建后按此变量自动重装，故必须常驻配置。
PAPERLESS_OCR_MODE（默认 skip）：已有文本层的页处理策略。skip=跳过已有文本页（快），redo=强制重识别，force=全部重跑。扫描件库建议默认 skip。
PAPERLESS_OCR_SKIP_ARCHIVE_FILE（默认 never）：归档文件存在时的再处理策略，配合 OCR_MODE 使用。
PAPERLESS_OCR_OUTPUT_TYPE（默认 pdfa）：输出格式，默认 PDF/A 长期归档格式；可选 pdf（普通 PDF）、pdfa-1/pdfa-2/pdfa-3（具体 PDF/A 子版本）。
PAPERLESS_OCR_PAGES（模板示例 1）：限制识别页数，大文档先只识别首页提类的场景可用。
PAPERLESS_OCR_IMAGE_DPI（默认 300）：图像 DPI 缺省值，对无 DPI 元数据的截图/照片件影响识别率。
PAPERLESS_OCR_CLEAN（默认 clean）：识别前图像清理级别（clean/clean-final/none），clean-final 保留清理后图像但文件更大。
PAPERLESS_OCR_DESKEW（默认 true）：自动纠正倾斜页面。
PAPERLESS_OCR_ROTATE_PAGES（默认 true）与 PAPERLESS_OCR_ROTATE_PAGES_THRESHOLD（默认 12.0）：自动旋转横放页及其置信度阈值。实测中文件日志 page is facing ⇧, confidence 11.10 - no change（低于阈值不旋转）。
PAPERLESS_OCR_USER_ARGS（默认 {}）：透传给 ocrmypdf 的高级 JSON 参数。
PAPERLESS_CONVERT_MEMORY_LIMIT（默认 0，不限制）与 PAPERLESS_CONVERT_TMPDIR（默认 /var/tmp/paperless）：ImageMagick 处理大图的内存上限与临时目录，低内存机器建议限制。

5.5 软件调优类（消费管线与体验）

PAPERLESS_TASK_WORKERS（默认 1）与 PAPERLESS_THREADS_PER_WORKER（默认 1）：任务 worker 数与每 worker OCR 线程数。多核机器提吞吐主要靠这两项；OCR 官方声明支持多核并行消费。
PAPERLESS_TIME_ZONE（默认 UTC）：时区。实测 Asia/Shanghai 后文档创建日期前缀为本地日期（如 2026-10-22）。
PAPERLESS_CONSUMER_POLLING_INTERVAL（默认 10）：消费目录轮询秒数；官方部署形态默认走 inotify 实时监听，轮询是兼容模式兜底。
PAPERLESS_CONSUMER_DELETE_DUPLICATES（默认 false）：发现内容重复文档时自动删除重复份（默认仅标记）。
PAPERLESS_CONSUMER_RECURSIVE（默认 false）与 PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS（默认 false）：递归扫描子目录、把子目录名转为标签。
PAPERLESS_CONSUMER_IGNORE_PATTERNS（默认 []，另有内置默认忽略模式）：追加忽略的文件名正则数组，如 ["^\\.DS_Store$", "^desktop\\.ini$"]。
条码组：PAPERLESS_CONSUMER_ENABLE_BARCODES（默认 false）开启条码识别后，PAPERLESS_CONSUMER_BARCODE_STRING（默认 PATCHT）作为分页补丁条码、PAPERLESS_CONSUMER_BARCODE_UPSCALE（默认 0.0）与 BARCODE_DPI（默认 300）调识别精度；PAPERLESS_CONSUMER_ENABLE_TAG_BARCODE（默认 false）+ TAG_BARCODE_MAPPING（默认 {"TAG:(.*)": "\\g<1>"}）支持用条码打标签；TAG_BARCODE_SPLIT（默认 false）按条码拆分文档。
双面扫描整理组：PAPERLESS_CONSUMER_ENABLE_COLLATE_DOUBLE_SIDED（默认 false）、COLLATE_DOUBLE_SIDED_SUBDIR_NAME（默认 double-sided）、COLLATE_DOUBLE_SIDED_TIFF_SUPPORT（默认 false）：双面扫描 A/B 面自动配对。
PAPERLESS_PRE_CONSUME_SCRIPT / PAPERLESS_POST_CONSUME_SCRIPT（默认空）：消费前后钩子脚本路径，可用于病毒扫描、归档推送等。
PAPERLESS_FILENAME_DATE_ORDER（默认空）：从文件名解析日期时的年月日顺序（YMD/DYM 等）。
PAPERLESS_FILENAME_PARSE_TRANSFORMS（默认 []）：文件名解析的正则变换数组。
PAPERLESS_NUMBER_OF_SUGGESTED_DATES（默认 5）：文档日期候选建议数。
PAPERLESS_THUMBNAIL_FONT_NAME（默认空）：缩略图渲染字体；不设用内置字体。⚠️ 中文标题文档缩略图出现方块字时，指向 CJK 字体可解（与 OCR 日志中 NotoSansSC 提示同源）。
PAPERLESS_IGNORE_DATES（默认空）：忽略特定日期不作文档日期。
PAPERLESS_ENABLE_UPDATE_CHECK（默认空）：升级检查开关（true/false），不设则首次启动在界面询问。

5.6 Tika 类（Office 与邮件文档支持）

PAPERLESS_TIKA_ENABLED（默认 false）：启用 Tika 文本抽取。实测设 1 后投递 .docx 文件，日志依次出现 Sending ... to Tika server → Converting ... to PDF（Gotenberg）→ consumption finished，中文正文全文检索命中。
PAPERLESS_TIKA_ENDPOINT（默认 http://localhost:9998）：Tika 服务地址，Compose 形态实测 http://tika:9998。
PAPERLESS_TIKA_GOTENBERG_ENDPOINT（默认 http://localhost:3000）：Gotenberg 地址，Compose 形态实测 http://gotenberg:3000。

5.7 二进制路径类（源码安装形态）

PAPERLESS_CONVERT_BINARY（默认 /usr/bin/convert）与 PAPERLESS_GS_BINARY（默认 /usr/bin/gs）：ImageMagick 与 Ghostscript 可执行文件路径，源码安装且二进制不在标准路径时才需要改；Compose 部署形态内置勿动。

5.8 代理类（Compose 部署专属，实测补充）

http_proxy / https_proxy：webserver 初始脚本安装 OCR 语言包时访问 Debian 源用。实测无代理时直连超时（apt-get 长期持锁），配置代理后下载恢复 6.4 MB/s。
no_proxy：必须包含 localhost,127.0.0.1,broker,db,gotenberg,tika，否则内部服务健康检查/调用会被推给代理导致启动失败。

六、生产配置模板

适用场景：4 核 CPU / 8GB 内存 / SSD 磁盘的中小团队自托管服务器（10 用户以内，日均 100 页扫描量），Compose 形态 docker-compose.env 写法：

# —— 必需服务（compose 内部服务名）——
PAPERLESS_SECRET_KEY=<python3 -c "import secrets; print(secrets.token_urlsafe(64))" 生成>
PAPERLESS_REDIS=redis://broker:6379
PAPERLESS_DBHOST=db
PAPERLESS_DBENGINE=postgresql
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=<与 db 服务 POSTGRES_PASSWORD 一致>

# —— 安全与托管 ——
PAPERLESS_URL=https://paperless.example.com
PAPERLESS_TIME_ZONE=Asia/Shanghai
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=<替换为强口令>
PAPERLESS_ADMIN_MAIL=admin@example.com
USERMAP_UID=1000
USERMAP_GID=1000

# —— OCR：中文为主的双语环境 ——
PAPERLESS_OCR_LANGUAGE=chi_sim+eng
PAPERLESS_OCR_LANGUAGES=chi-sim
PAPERLESS_OCR_MODE=skip
PAPERLESS_OCR_OUTPUT_TYPE=pdfa
PAPERLESS_OCR_IMAGE_DPI=300

# —— 消费管线：4 核机器 ——
PAPERLESS_TASK_WORKERS=2
PAPERLESS_THREADS_PER_WORKER=2
PAPERLESS_CONSUMER_POLLING_INTERVAL=10
PAPERLESS_CONSUMER_RECURSIVE=true
PAPERLESS_EMPTY_TRASH_DIR=../trash

# —— Office/邮件支持 ——
PAPERLESS_TIKA_ENABLED=1
PAPERLESS_TIKA_ENDPOINT=http://tika:9998
PAPERLESS_TIKA_GOTENBERG_ENDPOINT=http://gotenberg:3000

要点解读：① PAPERLESS_TASK_WORKERS=2 + THREADS_PER_WORKER=2 把 4 核用满又不至于 OCR 时挤占 Web 响应；② PAPERLESS_EMPTY_TRASH_DIR 落回收站是防误删底线（对应挂载目录需一并建好）；③ 中文环境两项语言参数的拼写差异（chi_sim 识别 / chi-sim 安装）是最常见翻车点；④ 16GB 以上内存或批量回扫历史档案时，可把 TASK_WORKERS 提到 4 并给 PAPERLESS_CONVERT_MEMORY_LIMIT 设上限（如 256Mi）防大图 OOM。

七、常见问题（FAQ）

Q1：PAPERLESS_OCR_LANGUAGES 写 chi_sim 为什么装不上中文包？

官方 init 脚本把该值直接拼进 tesseract-ocr- 后形成 Debian 包名：chi_sim → tesseract-ocr-chi_sim，而 Debian 实际包名为连字符 tesseract-ocr-chi-sim（实测 apt-cache show：下划线名 NOT FOUND、连字符名 EXISTS）。因此该参数写连字符形式 chi-sim，而 PAPERLESS_OCR_LANGUAGE 仍写 Tesseract 语言代码 chi_sim。

Q2：改了参数为什么没生效？

Compose 形态改完必须 docker compose up -d 让 webserver 重建（restart 不会应用新环境变量）；源码形态改 paperless.conf 后必须重启 systemd 服务。另外确认没有 environment: 覆盖 env_file: 里的同名键（前者优先）。

Q3：PAPERLESS_URL 需要带端口吗？

带外部访问端口：形如 http://192.168.1.62:8128 或 https://paperless.example.com（443 可省略端口）。写错会导致登录 CSRF 校验失败与邮件内链接错误。

Q4：USERMAP_UID 改成多少合适？

与挂载目录属主保持一致即可。宿主上有专用运行用户（uid 1000）就用默认；多服务共用目录时显式指定并 chown -R 对齐。属主错位会引发消费失败与搜索索引 PermissionDenied（实录见部署指南篇 FAQ-4）。

八、参考链接

官方配置文档：https://docs.paperless-ngx.com/configuration/
官方参数模板 paperless.conf.example（tag v3.3.3）：https://github.com/paperless-ngx/paperless-ngx/blob/v3.3.3/paperless.conf.example
官方 docker-compose.env 模板（tag v3.3.3）：https://github.com/paperless-ngx/paperless-ngx/blob/v3.3.3/docker/compose/docker-compose.env
本站配套文档：《Paperless-ngx 介绍与选型指南》、《Paperless-ngx 3.3.3 Docker Compose 部署指南》、《Paperless-ngx 3.3.3 常用 CLI 命令与工具详解》