Papra 26.7.1 配置参数详解

目标：把 Papra 26.7.1 的全部配置参数讲清楚——参数从哪里看、在哪里改、怎么改才生效，并给出一套按场景分组的核心参数默认值速查与可直接套用的生产配置模板。参数清单源自官方 Configuration 文档（2026-10-31 抓取，登记 179 个变量），关键参数的生效行为已在真实环境逐项实测验证。

一、环境信息

💡 说明：Papra 没有配置文件，全部配置通过环境变量注入。官方 Configuration 页是唯一的参数权威清单；本文默认值均对照该页逐项核对（标注"实测"的取值来自真实实例）。

二、前置条件

1. 已按《Papra 26.7.1 Docker Compose 部署指南》完成一套可访问的 Papra 实例（本文实测基址 http://192.168.1.200:8134）。
2. 具备该实例部署编排文件的修改权限（参数修改的落点就在编排文件或其引用的 .env 中）。
3. 准备一个可用于验证的服务账号：演示环境使用 admin@papra.local / q1w2e3r4，并在界面"设置 → API 密钥"中创建一个带全量权限的 API Key 供 curl 验证使用。
4. 阅读本文第五节前建议先通读第四节参数总览，建立分类框架。

三、参数查看与修改方式

3.1 参数的三个来源与优先级

Papra 的一个生效参数值由三层叠加合成，后者覆盖前者：

⚠️ 注意：有 3 个参数的"打包发行内置值"与官方文档登记的代码默认值不同，直接照抄文档默认值会误判：

变量	官方文档默认（代码）	打包发行内置（实测生效）
DATABASE_URL	file:./db.sqlite	file:./app-data/db/db.sqlite
DOCUMENT_STORAGE_FILESYSTEM_ROOT	./local-documents	./app-data/documents
SERVER_SERVE_PUBLIC_DIR	false	true

3.2 查看当前生效参数

Papra 不提供运行时读取参数的 API 或命令行工具，当前生效值需要在部署编排层核对：逐一检查编排文件 environment: 列表、同目录 .env，再叠加 3.1 表中②层的四个内置变量。本文实测实例的部署注入实录（密钥值脱敏）：

其中 PAPRA_VERSION / GIT_COMMIT / BUILD_DATE 三件套由发行流程在构建时注入，界面"关于"页可见（官方注释：used for display in the about page）。

3.3 修改参数与生效验证

修改步骤：

1. 编辑部署编排文件：少量变量直接写进 environment:；含密钥的变量建议放同目录 .env 并以 AUTH_SECRET=${AUTH_SECRET} 形式引用（见部署篇 4.2）。
2. 重启实例使新值生效（编排变更后的滚动重建操作见部署篇第十章）。
3. 按参数类型选择验证手段：注册开关看注册接口返回、上传上限看大文件上传、邮件驱动看服务日志。

实测验证 1：注册开关（AUTH_IS_REGISTRATION_ENABLED）

官方默认 true。在额外注入 AUTH_IS_REGISTRATION_ENABLED=false 的 8135 实例上发起注册：

curl -s -w '\nHTTP=%{http_code}\n' -X POST http://192.168.1.200:8135/api/auth/sign-up/email \
  -H 'Content-Type: application/json' \
  -d '{"name":"newuser","email":"newuser@papra.local","password":"q1w2e3r4"}'

实测回显（HTTP 400）：

{"message":"Email and password sign up is not enabled","code":"EMAIL_PASSWORD_SIGN_UP_DISABLED"}
HTTP=400

💡 说明：注意该错误没有外层 error 对象，与业务接口错误形态不同（better-auth 认证端点风格）。生产关闭注册后，新账号由管理员在组织设置中邀请。

实测验证 2：上传大小上限（DOCUMENT_STORAGE_MAX_UPLOAD_SIZE）

保持默认值（26214400 字节 = 25MB）不变，构造 27MB 随机文件上传：

dd if=/dev/urandom of=/tmp/oversize.bin bs=1M count=27
curl -s -w '\nHTTP=%{http_code}\n' -X POST \
  http://192.168.1.200:8134/api/organizations/org_tqq4cqy4g6ui3iwvitpgucgh/documents \
  -H "Authorization: Bearer ${PAPRA_API_KEY}" \
  -F 'file=@/tmp/oversize.bin'

实测回显（HTTP 413）：

{"error":{"message":"Document size too large.","code":"document.size_too_large"}}
HTTP=413

实测验证 3：邮件驱动（EMAILS_DRY_RUN）

部署注入 EMAILS_DRY_RUN=true 的实例，启动日志中邮件服务以 driverName":"logger" 初始化（日志实录见部署篇 4.3），即所有待发邮件只落到日志、不真实外发——验证了 5.7 节邮件驱动的兜底形态。

四、参数总览

官方 Configuration 页共登记 179 个配置变量（2026-10-31 抓取统计）。按职责分为 13 组，与第五节子节一一对应：

五、核心参数分类详解

以下 13 小节给出全部高频参数的官方默认值与说明；标 ✅ 的行为在本文实测环境验证过。

5.1 基础与服务参数

5.2 数据库参数

💡 说明：单机 SQLite 是默认形态，实测 5 份文档时整个数据目录仅 860K；文档量大或多人并发写时再评估切换 PostgreSQL。

5.3 文档生命周期参数

💡 说明：重处理关闭时调用接口返回 403 document.reprocessing_disabled，超限返回 429 server.too_many_requests 并附 Retry-After（官方 API 文档口径，接口实测见《Papra 26.7.1 REST API 使用详解》）。

5.4 文档存储参数

存储驱动四选一：

S3 驱动参数（DOCUMENT_STORAGE_S3_ 前缀）：ACCESS_KEY_ID、SECRET_ACCESS_KEY、BUCKET_NAME、REGION（默认 auto）、ENDPOINT、FORCE_PATH_STYLE（默认 false）。

Azure Blob 驱动参数（DOCUMENT_STORAGE_AZURE_BLOB_ 前缀）：CONNECTION_STRING（设置后账号密码被忽略）、ACCOUNT_NAME、ACCOUNT_KEY、CONTAINER_NAME。

容量上限：

存储键体系（决定文件在存储目录中的路径，默认沿用 legacy 规则 ✅——实测数据目录布局为 {组织ID}/originals/{文档ID}.{原始后缀}）：

存储加密：

5.5 内容提取策略参数

五种策略及专属参数：

💡 说明：各策略的 MIME_TYPES_ALLOW_LIST 通用语法——* 全部；image/* 类通配；! 前缀排除且排除始终优先（如 *,!image/png 表示除 PNG 外全部）。

5.6 认证与账号参数

5.7 邮件发送参数

5.8 采集通道参数

邮件采集（把文档发进专属邮箱地址即自动归档）：

文件夹采集（监控目录，落文件即归档）：

5.9 后台任务与调度参数

任务持久化：

五个定时清理任务（cron 与启动即执行开关；启动日志实录见部署篇 4.3 ✅）：

5.10 分享链接参数

💡 说明：限流值格式统一为 次数/时间窗（如 10/h、10/2h、2/5m，单位 s/m/h）。密码验证失败的实测报错（401 share_link.invalid_password）与令牌用法见《Papra 26.7.1 REST API 使用详解》。

5.11 配额与组织参数

5.12 AI 与自动打标参数

九家模型适配器（*_BASE_URL / *_API_KEY）：

本地模型（Ollama/LM Studio/vLLM）默认即指向本机端口，内网部署无需公网出口即可启用自动打标。

5.13 遥测与安全参数

六、生产配置模板

适用场景：10 人以内团队文档归档；2C4G 起、100GB 数据盘；中文扫描件为主；单实例 SQLite；管理员统一建号、注册关闭。以下 .env 可直接套用（注释掉的是按需打开项）：

# ===== 基础 =====
APP_BASE_URL=https://docs.example.com
AUTH_SECRET=<用 openssl rand -hex 48 生成后替换>
# PORT=1221
# PROCESS_MODE=all

# ===== 注册与账号 =====
AUTH_IS_REGISTRATION_ENABLED=false        # 关闭公开注册，管理员邀请建号
AUTH_FIRST_USER_AS_ADMIN=true             # 首个注册者自动成为管理员
# AUTH_ALLOWED_EMAIL_DOMAINS=example.com  # 如需开放注册，限定企业域名
AUTH_IS_PASSWORD_RESET_ENABLED=true       # 依赖下方真实邮件通道

# ===== 数据库 =====
DATABASE_URL=file:./app-data/db/db.sqlite # 单机默认；多实例/高并发再评估 postgres://

# ===== 存储与上传 =====
DOCUMENT_STORAGE_DRIVER=filesystem
DOCUMENT_STORAGE_MAX_UPLOAD_SIZE=104857600 # 100MB，按最大单件需求调整
DOCUMENTS_OCR_LANGUAGES=chi_sim,eng        # 中文扫描件 OCR

# ===== 邮件 =====
EMAILS_DRY_RUN=true                        # 调试期只落日志；密码重置需真发时切 SMTP
# SMTP_HOST=smtp.example.com
# SMTP_PORT=587
# SMTP_USER=docs@example.com
# SMTP_PASSWORD=<SMTP 密钥>
# SMTP_SECURE=false

# ===== 生命周期与分享 =====
DOCUMENTS_DELETED_DOCUMENTS_RETENTION_DAYS=30
DOCUMENT_SHARE_LINKS_MAX_LINKS_PER_DOCUMENT=10
DOCUMENT_SHARE_LINKS_ACCESS_TOKEN_TTL_MINUTES=15

# ===== 采集（按需） =====
# INGESTION_FOLDER_IS_ENABLED=true
# INGESTION_FOLDER_ROOT_PATH=/data/ingestion
# INTAKE_EMAILS_IS_ENABLED=true
# INTAKE_EMAILS_CATCH_ALL_DOMAIN=docs.example.com

⚠️ 注意：

1. AUTH_SECRET 一旦上线不可随意更换（全部会话与 API Key 失效）；务必首次部署就固定为自己的随机值并纳入密钥管理。
2. 若启用文档加密（DOCUMENT_STORAGE_ENCRYPTION_IS_ENABLED=true），必须同时配置 KEK 并离线备份——密钥丢失即数据不可恢复。
3. 该模板对应 2C4G 档位；文档量超过 10 万份或多人并发上传时，把 DATABASE_URL 切到外部 PostgreSQL 并将 TASKS_PERSISTENCE_DRIVER 保持 memory（单实例）或 libsql（多实例）。

七、常见问题

Q1：上传文件报 Document size too large？ 默认单文件上限 25MB（DOCUMENT_STORAGE_MAX_UPLOAD_SIZE=26214400）。27MB 文件实测返回 413，完整回显见 3.3 实测验证 2。按字节调大该值（0 为不限制）并重启实例。

Q2：注册接口报 EMAIL_PASSWORD_SIGN_UP_DISABLED？ AUTH_IS_REGISTRATION_ENABLED=false 的预期行为，实测回显见 3.3 实测验证 1。注意该错误无外层 error 对象，与业务接口错误形态不同；开放注册时建议同步配置 AUTH_ALLOWED_EMAIL_DOMAINS 白名单。

Q3：AUTH_SECRET 事后更换会怎样？ 全部已有登录会话与 API Key 立即失效（实测 26.7.1 行为），用户需重新登录、API Key 需重建。例行密钥轮换请安排在维护窗口。

Q4：DATABASE_ENCRYPTION_KEY 设置后丢失怎么办？ 官方文档明确警告：密钥丢失则数据不可恢复。启用数据库加密前必须把该密钥纳入离线备份；已加密的库无法用其他密钥打开。

Q5：修改 DOCUMENT_STORAGE_KEY_PATTERN 后老文档会搬家吗？ 不会。官方注释明确存量文档不自动迁移；DOCUMENT_STORAGE_KEY_SYNC_ENABLED=true 只影响此后被更新的文档。存量迁移走官方 Guides → Migrate Document Storage 流程。

Q6：单实例需要把 TASKS_PERSISTENCE_DRIVER 换成 libsql 吗？ 不需要。官方注释明确单实例 memory 足够；只有多实例部署（多个 worker 共享任务队列）才需要统一指向 libsql 任务库。

Q7：重处理文档被限流或拒绝？ 每组织默认限流 DOCUMENT_REPROCESSING_RATE_LIMIT=100/h，超限返回 429 并附 Retry-After；整体关闭时返回 403。调整对应两个开关即可，接口行为实测见《Papra 26.7.1 REST API 使用详解》。

八、参考链接

• 官方配置参考（179 个变量全清单）：https://docs.papra.app/self-hosting/configuration （2026-10-31 查询）
• 官方文档加密指南：https://docs.papra.app/guides/document-encryption （2026-10-31 查询）
• 官方存储键模式指南：https://docs.papra.app/guides/storage-key-patterns （2026-10-31 查询）
• 官方内容提取指南：https://docs.papra.app/guides/content-extraction （2026-10-31 查询）
• 官方 LLM 配置指南：https://docs.papra.app/guides/llm-configuration （2026-10-31 查询）
• 官方文件夹采集指南：https://docs.papra.app/guides/setup-ingestion-folder （2026-10-31 查询）
• 官方仓库：https://github.com/papra-hq/papra （2026-10-31 查询）

本专栏姊妹篇：《Papra 26.7.1 介绍与选型指南》、《Papra 26.7.1 Docker Compose 部署指南》、《Papra 26.7.1 REST API 使用详解》。