Documenso 配置参数详解

Documenso v2.21.1 环境变量体系全解：以官方 .env.example 为纲的九组参数逐项说明（必填密钥、URL 三层体系、数据库双连接串、签署证书三通道、存储 database/S3、SMTP 四通道、任务与功能开关），附实测行为佐证与配置变更纪律。

Documenso电子签名PDF 处理Nodejs2026/10/28

Documenso 配置参数详解

Documenso 社区版的全部配置都收敛在环境变量里，无独立配置文件。官方 .env.example（v2.21.1，250 行）按功能分组给出带注释的模板，本文以该文件为纲、结合一台 v2.21.1 实测实例的运行行为，对每组参数做逐项说明：哪些必填、哪些有默认值、改了会发生什么。部署层面的编排示例见《Documenso Docker Compose 部署实战》。

一、必填五参数（最小可运行集）

首次部署至少要给出以下五项，缺一应用无法正常启动或无法使用（v2.21.1 实测）：

变量必填原因实测取值
NEXTAUTH_SECRET会话 Cookie 签名密钥openssl rand -base64 32 生成
NEXT_PRIVATE_ENCRYPTION_KEY字段值/令牌对称加密主钥，≥32 字符同上
NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY对称加密次钥，≥32 字符同上
NEXT_PRIVATE_DATABASE_URLPostgreSQL 连接串postgres://documenso:***@database:5432/documenso
NEXT_PUBLIC_WEBAPP_URL对外访问地址，进入所有邮件链接http://localhost:8130

三把密钥生成一次后不可再换：加密密钥轮换会让既有加密数据（签署令牌、字段值）无法解密。官方对 .env.example 里的 CAFEBABE/DEADBEEF 占位值的注释原话是「REQUIRED: This should be a random string of at least 32 characters」，实测弱密钥不拦截启动，但属于自担风险。

二、应用 URL 体系（[[URLS]] + [[SERVER]]）

变量默认值说明
NEXT_PUBLIC_WEBAPP_URLhttp://localhost:3000浏览器与邮件链接使用的基础地址。端口映射、反向代理、域名切换都改这里
NEXT_PRIVATE_INTERNAL_WEBAPP_URLhttp://localhost:3000服务端回环调用自己的地址（后台任务、作业回调）。容器内保持 3000 不变
PORT3000容器内监听端口。一般不动，改外部端口用映射
NEXT_PRIVATE_WEBHOOK_SSRF_BYPASS_HOSTS空允许 Webhook 解析到内网/环回地址的主机白名单（逗号分隔）。内网 Webhook 接收端需要显式放行

实测验证：NEXT_PUBLIC_WEBAPP_URL=http://localhost:8130 时，注册验证邮件与签署邀请中的链接均带 8130 端口；若保持默认 3000，邮件链接全部失效（B2 篇排障坑二）。判断口诀：邮件链接看 PUBLIC，服务自调用看 INTERNAL，容器监听看 PORT。

三、数据库（[[DATABASE]]）

变量默认值说明
NEXT_PRIVATE_DATABASE_URL无（必填）应用运行时连接串，允许指向 PgBouncer 等连接池
NEXT_PRIVATE_DIRECT_DATABASE_URL回退到上一项迁移等管理操作的直连串。start.sh 中显式兜底：export NEXT_PRIVATE_DIRECT_DATABASE_URL="${...:-$NEXT_PRIVATE_DATABASE_URL}"

实测：容器内该变量由入口脚本自动兜底，未单独设置时迁移照常执行（166 个迁移、54 张表全建）。使用 PgBouncer 时必须把 DIRECT 指向真实数据库，否则迁移阶段会因 prepared statement 冲突失败。

四、认证与 OAuth/OIDC（[[AUTH]] + [[AUTH OPTIONAL]]）

除必填的 NEXTAUTH_SECRET 外，本组全部可选，用于扩展登录方式：

  • Google：NEXT_PRIVATE_GOOGLE_CLIENT_ID / NEXT_PRIVATE_GOOGLE_CLIENT_SECRET，配 Gmail 场景官方文档 setting-up-oauth-providers#google-oauth-gmail。
  • Microsoft（Azure AD）：NEXT_PRIVATE_MICROSOFT_CLIENT_ID / NEXT_PRIVATE_MICROSOFT_CLIENT_SECRET。
  • OIDC 通用：NEXT_PRIVATE_OIDC_WELL_KNOWN（.well-known/openid-configuration 地址）+ CLIENT_ID/SECRET；NEXT_PRIVATE_OIDC_PROVIDER_LABEL（登录按钮文案，默认 OIDC）、NEXT_PRIVATE_OIDC_SKIP_VERIFY（跳过证书校验，仅自签 IdP 测试用）、NEXT_PRIVATE_OIDC_PROMPT（默认 login，置空可省略 prompt 参数）。

五、签署证书与签名通道（[[SIGNING]]）

NEXT_PRIVATE_SIGNING_TRANSPORT 三选一：local（默认）/ gcloud-hsm / csc。

local 通道（自托管默认）：

变量说明
NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH.p12 文件容器内路径（实测 /opt/documenso/cert.p12）
NEXT_PRIVATE_SIGNING_LOCAL_FILE_CONTENTS.p12 内容的 base64。与 PATH 二选一，无盘环境用它
NEXT_PRIVATE_SIGNING_PASSPHRASE.p12 导出口令

实测注意：挂载的 .p12 宿主机权限需 644，否则封存任务报 EACCES（B2 篇排障坑一）；/api/certificate-status 返回 {"isAvailable":true} 即证书就绪。

gcloud-hsm 通道：NEXT_PRIVATE_SIGNING_GCLOUD_HSM_KEY_PATH（私钥路径）、..._PUBLIC_CRT_FILE_PATH（公钥证书）、..._CERT_CHAIN_FILE_PATH（证书链）、对应 *_CONTENTS base64 变体、NEXT_PRIVATE_GCLOUD_APPLICATION_CREDENTIALS_CONTENTS（GCP 凭证）、NEXT_PRIVATE_SIGNING_GCLOUD_HSM_SECRET_MANAGER_CERT_PATH（从 Secret Manager 取证书）。

csc 通道（远程签名，合规场景）：NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL、..._OAUTH_CLIENT_ID、..._OAUTH_CLIENT_SECRET、NEXT_PRIVATE_SIGNING_CSC_SIGNATURE_LEVEL（AES 默认 / QES，合格电子签名）。

签名行为微调：NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY（TSA URL 列表，逗号分隔，启用 LTV/归档时间戳）、NEXT_PRIVATE_SIGNING_REASON（默认 Signed by Documenso）、NEXT_PUBLIC_SIGNING_CONTACT_INFO（默认为 Webapp URL）、NEXT_PRIVATE_USE_LEGACY_SIGNING_SUBFILTER（置 true 用旧式 adbe.pkcs7.detached 子过滤器，默认 ETSI.CAdES.detached）。

实测佐证：local 通道签署完成的 PDF 中含 /ByteRange 与 /FT /Sig 结构（PAdES/CAdES 数字签名），非仅图片贴图。

六、存储（[[STORAGE]]）

变量默认值说明
NEXT_PUBLIC_UPLOAD_TRANSPORTdatabasedatabase（PDF 全存 PostgreSQL）或 s3
NEXT_PRIVATE_UPLOAD_ENDPOINT无S3 端点，第三方兼容存储（MinIO 等）必填
NEXT_PRIVATE_UPLOAD_FORCE_PATH_STYLEfalsetrue 用路径式 domain.com/<bucket>/<key>，MinIO 必开
NEXT_PRIVATE_UPLOAD_REGIONus-east-1S3 区域
NEXT_PRIVATE_UPLOAD_BUCKET无S3 必填
NEXT_PRIVATE_UPLOAD_ACCESS_KEY_ID / ..._SECRET_ACCESS_KEY无S3 凭证

实测佐证：database 模式下整个栈仅一个 database 数据卷（294 KB dump 覆盖 54 表含文档二进制）；切换 s3 后卷只剩会话/元数据，大文件吞吐更好但备份面变宽（数据库 + 桶两处）。

七、邮件 SMTP（[[SMTP]]）

变量默认值说明
NEXT_PRIVATE_SMTP_TRANSPORTsmtp-auth可选 smtp-auth / smtp-api / resend / mailchannels
NEXT_PRIVATE_SMTP_HOST / ..._PORT127.0.0.1 / 2500SMTP 服务地址端口
NEXT_PRIVATE_SMTP_USERNAME / ..._PASSWORDdocumenso / password认证凭证
NEXT_PRIVATE_SMTP_SECURE空强制 TLS（465 直连）
NEXT_PRIVATE_SMTP_UNSAFE_IGNORE_TLS空true 且未开 SECURE 时禁用 STARTTLS。Mailpit 等无 TLS 内网服务实测需置 true
NEXT_PRIVATE_SMTP_FROM_NAME / ..._FROM_ADDRESSDocumenso / noreply@documenso.com发件人，必填
NEXT_PRIVATE_RESEND_API_KEY / NEXT_PRIVATE_MAILCHANNELS_*无对应 SaaS 通道的密钥与 DKIM 配置

实测：本机 Mailpit（smtp-auth + HOST=mailpit + PORT=1025 + UNSAFE_IGNORE_TLS=true）走通注册验证、签署邀请、完成回执全链路，共 7 封邮件入箱；HOST 配错或未配时签署链路静默断链（B2 篇排障坑三）。

八、后台任务与遥测（[[BACKGROUND JOBS]] + [[TELEMETRY]]）

变量默认值说明
NEXT_PRIVATE_JOBS_PROVIDERlocallocal（进程内）/ inngest / bullmq。签署封存、回执邮件都由任务通道驱动
NEXT_PRIVATE_REDIS_URLredis://localhost:63790bullmq 通道专用
NEXT_PRIVATE_REDIS_PREFIXdocumensoRedis 队列前缀，共享实例时做命名空间
NEXT_PRIVATE_BULLMQ_CONCURRENCY10任务并发数
DOCUMENSO_DISABLE_TELEMETRY空置 true 关闭匿名遥测（仅采集版本/安装 ID/节点 ID）

实测佐证：local 通道下 internal.seal-document 任务日志直接打在应用容器日志里（[JOBS]: Triggering job ...），单实例部署零外部依赖；多实例或高吞吐场景再切 bullmq。

九、功能开关与安全（[[FEATURES]] + 安全项）

变量默认说明
NEXT_PUBLIC_DISABLE_SIGNUP空true 关闭全部注册通道（含组织 OIDC 门户）
NEXT_PUBLIC_DISABLE_EMAIL_PASSWORD_SIGNUP空true 仅关邮箱密码注册
NEXT_PUBLIC_DISABLE_GOOGLE_SIGNUP / ..._MICROSOFT_... / ..._OIDC_...空分别拦截对应渠道的新账号注册，老用户登录不受影响
NEXT_PRIVATE_ALLOWED_SIGNUP_DOMAINS空注册邮箱域名白名单（逗号分隔）
NEXT_PUBLIC_DISABLE_SIGNIN / NEXT_PUBLIC_DISABLE_EMAIL_PASSWORD_SIGNIN空登录总开关；后者同时关闭忘记/重置密码页
NEXT_PUBLIC_DISABLE_GOOGLE_SIGNIN / ..._MICROSOFT_... / ..._OIDC_...空隐藏对应登录按钮
NEXT_PUBLIC_DISABLE_OIDC_AUTO_REDIRECT空OIDC 为唯一登录方式时 /signin 会自动跳转，置 true 保留登录页
NEXT_PUBLIC_DOCUMENT_SIZE_UPLOAD_LIMIT5上传大小上限（MB），界面展示与校验用
NEXT_PUBLIC_FEATURE_BILLING_ENABLED空计费开关，自托管留空
NEXT_PRIVATE_SHOW_NEW_ACCOUNT_EMAIL_WARNING空新账号（48h 内）签署邮件警示条，云端强制开启
NEXT_PUBLIC_POSTHOG_KEY空留空禁用 PostHog 埋点
NEXT_PUBLIC_USE_INTERNAL_URL_BROWSERLESSfalse无头请求走内部 URL
NEXT_PUBLIC_TURNSTILE_SITE_KEY / NEXT_PRIVATE_TURNSTILE_SECRET_KEY无Cloudflare Turnstile 人机校验（注册可见/登录隐形）
DANGEROUS_BYPASS_RATE_LIMITS空仅 E2E 测试用，关闭全部限流

十、进阶与企业版（[[AI]] + [[EE ONLY]] + [[STRIPE]] + 其他）

  • AI：GOOGLE_VERTEX_PROJECT_ID / GOOGLE_VERTEX_LOCATION（默认 global）/ GOOGLE_VERTEX_API_KEY，接入 Gemini 用于文档理解类能力。
  • 企业版：NEXT_PRIVATE_DOCUMENSO_LICENSE_KEY 开启企业特性；SES 域名验证 NEXT_PRIVATE_SES_ACCESS_KEY_ID/SECRET/REGION 为 EE 专属。
  • Stripe：NEXT_PRIVATE_STRIPE_API_KEY / NEXT_PRIVATE_STRIPE_WEBHOOK_SECRET。
  • 文档转换：NEXT_PRIVATE_DOCUMENT_CONVERSION_URL（Gotenberg 兼容服务地址）。未配置时仅接受 PDF 上传，配置后 DOCX 自动转 PDF；配套 ..._TIMEOUT_MS（默认 30000）与 Basic Auth ..._USERNAME/..._PASSWORD。
  • 运维杂项：NEXT_PRIVATE_LOGGER_FILE_PATH（日志落盘，提供后关闭 stdout）、NEXT_PRIVATE_PLAIN_API_KEY（Plain 工单集成）、E2E 测试专用账号三元组。

配置变更的操作纪律

  1. 环境变量只在容器启动时读取，改完必须 docker compose up -d（会自动重建受影响服务）；
  2. 三把密钥（NEXTAUTH + 两把 ENCRYPTION）生成后永不轮换，随数据库备份单独归档；
  3. NEXT_PUBLIC_* 是浏览器可见值，改动会立刻反映到邮件链接与前端行为；NEXT_PRIVATE_* 是服务端值，错误通常在后台任务里才暴露；
  4. 排查配置生效状态的两个免认证端点：/api/health（数据库 + 证书）与 /api/certificate-status。

相关文档