PdfDing 1.14 配置参数详解

目标：系统性讲清 PdfDing v1.14.1 全部配置参数的作用域、取值与默认值，给出「查看运行时参数、修改并验证生效」的可复现方法，并提供两套可直接落地的生产配置模板。全部变量经官方文档站、v1.14.1 源码（pdfding/core/settings/prod.py）与本地容器实测三方交叉验证，测试日期 2026-10-29。

一、环境信息

PdfDing 的配置参数按功能分为 8 组：基础（general）、安全（security）、SSO 单点登录（sso_oidc）、邮件（email）、数据库（databases）、界面定制（customization）、consume 自动导入（consumption）、演示模式（demo，官方文档未收录，本文从源码挖出并实测）。

二、前置条件

1. 已按部署指南完成 Compose 部署且服务健康（curl http://127.0.0.1:8139/healthz 返回 200）；
2. 可执行 docker exec pdfding-1.14.1 …（容器名按你的 container_name 替换）；
3. 理解一个前提：环境变量是 PdfDing 唯一的配置入口——镜像内没有可编辑的配置文件，任何参数变更都走「改 compose → 重建容器」路径。

三、参数查看与修改方式

3.1 参数体系：环境变量 → Django settings

启动时容器内的 Django settings 模块读取环境变量并完成三类加工：布尔值解析（TRUE/True 均识别）、默认值兜底（未设置时取内置默认）、派生计算（如 HOST_NAME 自动展开为 ALLOWED_HOSTS 与 CSRF_TRUSTED_ORIGINS）。因此「容器环境变量」和「运行时生效值」并不总是字面相等，排障时要以运行时值为准。

3.2 查看参数的三条路径（实测）

路径一：看容器环境变量（原始注入值）：

docker exec pdfding-1.14.1 env | grep -E 'HOST_NAME|SECRET_KEY|EMAIL_BACKEND|CONSUME' | sort

实测回显：

ACCOUNT_EMAIL_VERIFICATION=TRUE
CONSUME_ENABLE=TRUE
CONSUME_SCHEDULE=*/5 * * * *
CONSUME_TAGS=自动导入 consume
CSRF_COOKIE_SECURE=FALSE
DEFAULT_THEME=dark
EMAIL_BACKEND=CONSOLE
HOST_NAME=127.0.0.1
SECRET_KEY=…

路径二：读 Django 运行时配置（解析后的生效值，排障首选）：

docker exec pdfding-1.14.1 python pdfding/manage.py shell -c \
  "from django.conf import settings; print(settings.ALLOWED_HOSTS); print(settings.CSRF_TRUSTED_ORIGINS); print(settings.ACCOUNT_EMAIL_VERIFICATION)"

实测回显：

['127.0.0.1']
['https://127.0.0.1', 'http://127.0.0.1']
mandatory

注意第三行：环境变量写 TRUE，Django 内部实际值为 mandatory（allauth 的枚举值），这是「环境变量 ≠ 运行时值」的典型例子。

路径三：看启动日志（只反映启动时刻的严重问题）：

docker logs pdfding-1.14.1

3.3 修改参数并验证生效（实测全流程）

标准动作：编辑 compose 的 environment 段 → docker compose up -d 重建 → 路径二验证。本次实测同时修改 HOST_NAME=127.0.0.1 → pdfding.lab.local 与 DEFAULT_THEME=dark → light：

docker compose up -d

实测回显：

 Container pdfding-1.14.1 Recreated
 Container pdfding-1.14.1 Starting
 Container pdfding-1.14.1 Started

验证运行时生效：

DEFAULT_THEME = light
ALLOWED_HOSTS = ['pdfding.lab.local']
CSRF_TRUSTED_ORIGINS = ['https://pdfding.lab.local', 'http://pdfding.lab.local']

三个结论：

1. 重建容器即可让任意环境变量生效，无需镜像重拉；
2. ALLOWED_HOSTS 精确等于 HOST_NAME（源码 prod.py：逐个读入）；CSRF_TRUSTED_ORIGINS 由源码对每个 host 自动补 https:// 与 http:// 两条——不要在 HOST_NAME 里手写协议前缀；
3. HOST_NAME 变更后必须同步变更访问方式，否则触发 400（见 §7.1 实测）。

3.4 取值约定

• 布尔值：TRUE/FALSE 官方文档用大写，实测 True/true 等价（v1.6.3 起支持混合大小写，源码按 ['TRUE', 'True'] 白名单判断）；
• 多值：HOST_NAME 用逗号分隔（pdfding.com,127.0.0.1）；CONSUME_TAGS 官方说明用空格分隔（tag1 tag2），实测逗号分隔同样生效，建议从官方写法；
• cron 表达式：CONSUME_SCHEDULE 为标准五段 cron（*/5 * * * * = 每 5 分钟）。

四、参数总览

下表为 v1.14.1 全部配置参数速查（「文档」列表示是否见于官方文档站；默认值取源码）：

💡 三处「文档与源码不一致」均为本次实测发现：DEFAULT_THEME_COLOR 文档残留已失效；CONSUME_SCHEDULE 与 demo 组只存在于源码。

五、核心参数分类详解

5.1 基础参数（general 组）

HOST_NAME——全系统最重要的一个变量，一参三用（§3.3 已实测）：

1. 进入 Django ALLOWED_HOSTS：不在列表中的 Host 头直接 400 拒绝（实测日志见 §7.1）；
2. 展开 CSRF_TRUSTED_ORIGINS：自动补 http(s):// 两条；
3. 拼装账号相关链接：实测密码重置邮件的主题与链接均由它生成——HOST_NAME=127.0.0.1 时收到主题为 [127.0.0.1:8139] Password Reset Email 的邮件，重置链接形如 http://127.0.0.1:8139/accountpassword/reset/key/2-…。因此生产换域名时，改这一个变量即可同步换掉邮件里的链接。

ACCOUNT_EMAIL_VERIFICATION——默认 TRUE，未验证邮箱的账号无法登录。对无外网 SMTP 的内网部署，这个默认值会造成「注册后永远登不进去」的体感故障，三选一处理：配好 SMTP（§5.4）、内网自建可投递的邮局、或改 FALSE（牺牲邮箱真实性校验）。

DISABLE_USER_SIGNUP——默认允许任何人注册。个人/团队实例建议 TRUE，配合管理员手动建号（CLI 命令见 《PdfDing 1.14 常用 CLI 命令与工具详解》）。

ALLOW_PDF_SUB_DIRECTORIES——控制 UI 上传时能否把 PDF 存进媒体目录的子目录。官方文档特别注明这是纯 UI 层设置，随时切换不会损坏数据库。

WORKERS / THREADS / WORKER_TIMEOUT——Gunicorn 三件套，默认 1 worker × 3 线程（gthread 模式，实测启动日志 Using worker: gthread）。官方文档明确：常规实例默认值即可；上传大文件频繁超时就加大 WORKER_TIMEOUT（默认 30 秒）。个人实例不建议盲目加 worker——PdfDing 的负载主要是文件 IO 而非 CPU，1×3 的组合到几十并发用户前都不是瓶颈。

LOG_LEVEL——默认 ERROR，排障期建议临时调到 INFO（本文实验即用 INFO，能看到 consume 扫描、分享清理等行为日志），排障完改回。

5.2 安全参数（security 组）

SECRET_KEY——签名会话 Cookie、CSRF 令牌与密码重置令牌的根密钥。实测不设置时容器仍能启动（Django 检查框架给出 SECRET_KEY 为空的警告后继续运行），但这属于不安全回退：签名密钥退化为临时值，每次重启全部用户被登出，且签名可被伪造。必须设为长随机串（如 openssl rand -base64 48 生成），并在备份策略中把它与数据库同等对待——换密钥的代价是全体会话失效。

Cookie 安全与传输组合——三个变量决定传输安全基线：

关键坑：SECURE_SSL_REDIRECT=TRUE 在反向代理后会导致无限重定向（官方文档原文警告：代理后端看到的是代理发来的 http 请求），TLS 已由代理终结时务必保持 FALSE。SECURE_HSTS_SECONDS 建议先用小值（如 3600）验证全站 HTTPS 正常后再放大到 31536000。

MFA 组——PdfDing 内置三类第二因子：TOTP（验证器 App）、恢复码（MFA_USE_RECOVERY_CODES，默认开，MFA_TRUST_COOKIE_AGE 天内可信任浏览器跳过）、WebAuthn（MFA_USE_WEBAUTHN，默认开）。两个值得注意的安全默认：

• MFA_ALLOW_UNVERIFIED_EMAIL=FALSE：未验证邮箱的账号不许开 MFA——官方文档解释了威胁模型：若允许，攻击者可抢注未验证邮箱、开启 MFA 后把真实所有者锁在门外；
• MFA_WEBAUTHN_ALLOW_INSECURE_ORIGIN=FALSE：localhost 不算安全源，本地开发测 WebAuthn 需临时开 TRUE，严禁带上生产。

5.3 SSO 单点登录参数（sso_oidc 组）

接入 Authelia、Authentik、Keycloak 等 OIDC IdP 的最小集合：OIDC_ENABLE=TRUE + OIDC_CLIENT_ID + OIDC_CLIENT_SECRET + OIDC_AUTH_URL（指向 IdP 的 .well-known/openid-configuration）。三个进阶行为：

• 管理员映射：OIDC_ADMIN_GROUP=admins 后，IdP 中 admins 组的用户登录即自动获得管理员权限；若 IdP 不默认签发用户组信息，需配 OIDC_EXTRA_SCOPE=groups 追加 scope；
• OIDC_ONLY 默认 TRUE——这个默认容易造成接入事故：一旦 OIDC_ENABLE=TRUE 而本地密码登录被关闭，若 IdP 配置有误将无人能登录。首次接入建议显式设 OIDC_ONLY=FALSE 验证通过后再收紧；
• OIDC_PROVIDER_NAME：登录页按钮文案 LOG IN VIA <名称>，可写 Authelia/Keycloak 等。

5.4 邮件参数（email 组）

EMAIL_BACKEND 两值：

• CONSOLE（默认）：所有邮件打印到容器日志，零配置可测全流程。实测 sendtestemail 的完整输出（节选）：

Subject: Test email from 45c81fbb1594 on 2026-10-29 …
From: info@127.0.0.1
To: demo@pdfding.local
…（正文）

注意发件人 info@127.0.0.1：文档默认值写 info@pdfding，实测发件人跟随 HOST_NAME 拼接为 info@<HOST_NAME>——又一处「文档 ≠ 运行时」。

• SMTP：生产形态，需配 SMTP_HOST/SMTP_PORT（默认 587）/SMTP_USER/SMTP_PASSWORD。SMTP_USE_TLS 与 SMTP_USE_SSL 互斥（官方原文明示），587 端口配 SMTP_USE_TLS=TRUE，465 端口配 SMTP_USE_SSL=TRUE，同时开启会导致连接失败。

EMAIL_ADDRESS 可覆盖发件人显示地址（如 no-reply@yourdomain.com），不设则用上述拼接默认。

5.5 数据库参数（databases 组）

默认 SQLite（单文件 db/db.sqlite3，零外部依赖）。切换 PostgreSQL 需要同时做三件事：DATABASE_TYPE=POSTGRES、补齐 POSTGRES_HOST/NAME/USER/PASSWORD、换用官方 PostgreSQL 版编排（仓库 compose/postgres.docker-compose.yaml，包含 app + db 双服务与健康检查）。五件套默认值：HOST postgres、NAME pdfding、USER pdfding、PORT 5432（密码无默认必填）。

选型判断：≤10 用户、单机部署，SQLite 完全够用且备份最简单；多实例、高频并发写入或需要独立数据库运维体系时再上 PostgreSQL。SQLite → PostgreSQL 无自动迁移工具，属重建式切换（导出/重传），初始部署时就该想清楚。

5.6 界面定制参数（customization 组）

该组官方文档页仅存两个变量，实际有效只有一个：

• DEFAULT_THEME：新注册用户的默认主题，light / dark / system（v1.7.0 起支持 system 跟随操作系统）。实测改 light 后重建即生效（§3.3 回显）。注意它只影响新用户的初始选择，已存在用户的个人设置存于各自 Profile，不受此变量影响；
• DEFAULT_THEME_COLOR：已失效。v1.13.0 移除了主题色选择功能，v1.14.1 源码中已无该变量的任何读取逻辑（本次 grep 源码零命中），但官方文档页仍列出——设置了不报错也无效果，属于文档滞后残留。

5.7 consume 自动导入参数（consumption 组）

该功能默认关闭，开启后 Huey 定时任务扫描容器内 consume/<用户ID>/ 目录，把 PDF 入库、打标签、删除源文件。四个变量：

• CONSUME_ENABLE=TRUE：总开关。开启后启动日志出现 Huey consumer started 与 + pdf.tasks.consume_task（实测回显见部署指南 §4.4）；
• CONSUME_SCHEDULE：cron 表达式，启用时默认 */5 * * * *；未启用 consume 时源码给它一个占位值 0 2 * * *（无实际作用）。官方文档页未收录此变量，以源码与实测为准；
• CONSUME_TAGS：自动打的标签，空格分隔；实测导入的文件成功挂上所配标签；
• CONSUME_SKIP_EXISTING：默认 TRUE，按「同用户 + 同文件名 + 同文件大小」去重跳过——批量导入重复文件时靠它幂等。

运维要点两条：目录属主必须是 uid 1000（root 投放的文件删除时报 PermissionError: [Errno 13]，实测排障见部署指南 §11.2）；导入动作按「先入库后删源」执行，看到日志 Importing 1 PDF(s) from the consume directory. → Processed 1 PDF(s) from the consume directory. 即完成一轮。

5.8 演示模式参数（demo 组，官方文档未收录）

源码 prod.py 中还存在一组 demo 变量，官方文档完全未提及（推测用于作者维护的官方演示站）：

自托管场景无使用必要，列出仅为参数体系完整性。若你发现实例出现「数据定时消失」的灵异现象，先检查 compose 里是否误配了 DEMO_MODE=TRUE。

六、生产配置模板

6.1 模板一：个人 / 小团队 SQLite 形态

适用：1–10 用户、单机部署、2GB 内存 / 20GB 磁盘起、无内网 IdP。选择理由：零外部依赖、备份即拷文件、资源占用最低。

services:
  pdfding:
    container_name: pdfding
    image: mrmn/pdfding:v1.14.1
    volumes:
      - ./db:/home/nonroot/pdfding/db
      - ./media:/home/nonroot/pdfding/media
      - ./consume:/home/nonroot/pdfding/consume
    environment:
      - HOST_NAME=pdfding.example.com          # 实际访问域名
      - SECRET_KEY=<openssl rand -base64 48 生成>
      # HTTPS 由反代终结：
      - SECURE_HSTS_SECONDS=31536000
      - ACCOUNT_DEFAULT_HTTP_PROTOCOL=https
      - DISABLE_USER_SIGNUP=TRUE
      - EMAIL_BACKEND=SMTP
      - EMAIL_ADDRESS=no-reply@example.com
      - SMTP_HOST=smtp.example.com
      - SMTP_PORT=587
      - SMTP_USER=pdfding@example.com
      - SMTP_PASSWORD=<SMTP密码>
      - SMTP_USE_TLS=TRUE
      - CONSUME_ENABLE=TRUE
      - CONSUME_TAGS=inbox
      - LOG_LEVEL=INFO
    ports:
      - "127.0.0.1:8000:8000"    # 只绑定本机回环，由反代对外
    restart: unless-stopped

要点：端口绑定 127.0.0.1 交由 Nginx/Caddy 终结 TLS 后反代；CSRF_COOKIE_SECURE/SESSION_COOKIE_SECURE 保持默认 TRUE 不写出来；SECURE_SSL_REDIRECT 保持 FALSE 防反代后无限重定向。

6.2 模板二：团队 PostgreSQL + SMTP + OIDC 形态

适用：10–100 用户、4GB 内存 / 100GB 磁盘、已有内网 IdP（Authelia/Authentik/Keycloak）。在官方 postgres.docker-compose.yaml 基础上补齐关键环境变量：

services:
  pdfding:
    image: mrmn/pdfding:v1.14.1
    depends_on:
      db:
        condition: service_healthy
    environment:
      - HOST_NAME=pdfding.example.com
      - SECRET_KEY=<长随机串>
      - ACCOUNT_DEFAULT_HTTP_PROTOCOL=https
      - SECURE_HSTS_SECONDS=31536000
      - DISABLE_USER_SIGNUP=TRUE
      # PostgreSQL
      - DATABASE_TYPE=POSTGRES
      - POSTGRES_HOST=db
      - POSTGRES_NAME=pdfding
      - POSTGRES_USER=pdfding
      - POSTGRES_PASSWORD=<DB密码>
      # SMTP
      - EMAIL_BACKEND=SMTP
      - SMTP_HOST=smtp.example.com
      - SMTP_PORT=587
      - SMTP_USER=pdfding@example.com
      - SMTP_PASSWORD=<SMTP密码>
      - SMTP_USE_TLS=TRUE
      # OIDC SSO
      - OIDC_ENABLE=TRUE
      - OIDC_CLIENT_ID=pdfding
      - OIDC_CLIENT_SECRET=<长随机串>
      - OIDC_AUTH_URL=https://auth.example.com/.well-known/openid-configuration
      - OIDC_ADMIN_GROUP=pdfding-admins
      - OIDC_EXTRA_SCOPE=groups
      - OIDC_ONLY=FALSE          # 首次接入先允许本地密码兜底，验证后改 TRUE
      - CONSUME_ENABLE=TRUE
    ports:
      - "127.0.0.1:8000:8000"
    restart: unless-stopped

要点：depends_on + service_healthy 保证数据库就绪后再起应用；OIDC_ONLY 的放行-收紧两步走（§5.3）；WORKERS/THREADS 保持默认，百用户内无压力，出现排队再加 WORKERS=2。

七、常见问题

7.1 改了 HOST_NAME 后访问报 400（DisallowedHost）

实测：HOST_NAME 改为 pdfding.lab.local 后仍用 127.0.0.1:8139 访问，返回 HTTP 400，日志：

django.core.exceptions.DisallowedHost: Invalid HTTP_HOST header: '127.0.0.1:8139'.
You may need to add '127.0.0.1' to ALLOWED_HOSTS.

处理：HOST_NAME 逗号分隔写入所有实际访问入口（域名 + IP），如 pdfding.example.com,10.0.0.5，重建容器。

7.2 HTTP 环境下登录后立即掉线 / CSRF 校验失败

原因与处理见部署指南 §11.4：CSRF_COOKIE_SECURE/SESSION_COOKIE_SECURE 默认 TRUE，HTTP 下浏览器拒收 Secure Cookie。试运行改 FALSE，生产走 HTTPS 保持默认。

7.3 反向代理后无限重定向

原因：SECURE_SSL_REDIRECT=TRUE 且 TLS 在代理层终结，应用看到的请求永远是 http，不断 301。处理：代理后保持 FALSE，传输安全交给代理与 HSTS。

7.4 注册后一直无法登录

ACCOUNT_EMAIL_VERIFICATION 默认 TRUE 且邮件发不出去（未配 SMTP）。三选一：配 SMTP；EMAIL_BACKEND=CONSOLE 时从 docker logs 复制验证链接完成自验证；或改 FALSE。管理员还可用容器内命令补已验证邮箱（CLI 详解篇 §5）。

7.5 设置了 DEFAULT_THEME_COLOR 主题色却没效果

该变量已随 v1.13.0 移除主题色功能而失效（源码零引用，文档页残留）。v1.14.1 只有 DEFAULT_THEME 一个界面变量。

7.6 consume 文件导入后目录越积越多 / 源文件删不掉

属主问题：root 投放的文件 uid 0，容器进程（uid 1000）无权删除，日志报 PermissionError: [Errno 13]。处理：chown -R 1000:1000 consume 目录；投递链路（脚本/网盘同步）以 uid 1000 落盘。

7.7 上传大文件时 502 / 超时

Gunicorn 默认 30 秒请求超时。加大 WORKER_TIMEOUT（如 120），重建容器；若反代层也有超时（Nginx proxy_read_timeout），同步调整。

八、参考链接

• 官方配置文档（General）：https://docs.pdfding.com/configuration/general/
• 官方配置文档（Security / SSO / Email / Databases / Customization / Consumption）：https://docs.pdfding.com/configuration/security/ 等同级页面
• v1.14.1 源码 settings（参数实现权威）：https://codeberg.org/mrmn/PdfDing/src/branch/master/pdfding/core/settings/prod.py
• 官方 PostgreSQL 编排示例：https://codeberg.org/mrmn/PdfDing/src/branch/master/compose/postgres.docker-compose.yaml
• 项目主仓库：https://codeberg.org/mrmn/PdfDing
• 相关文档：《PdfDing 介绍与选型指南》、《PdfDing 1.14 Docker Compose 部署指南》、《PdfDing 1.14 常用 CLI 命令与工具详解》