Docuseal 3.3.4 配置参数详解

目标：系统梳理 Docuseal 3.3.4 的配置体系（环境变量 + 界面配置两层），逐项说明参数含义、默认值与生效验证方法，并给出生产环境推荐配置模板。已在 Ubuntu 22.04（Docker Compose 部署形态，见《Docuseal 3.3.4 Docker Compose 部署指南》）实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Docuseal：3.3.4（官方 3.3.4 构建，Ruby 4.0.9 + Puma 8.0.2 + Sidekiq 队列）
• 数据库：PostgreSQL 16（官方默认 Compose 模板为 PostgreSQL 15；另支持 MySQL 与内置 SQLite）
• 部署形态：双服务栈（应用 + 数据库），Web 端口 8132
• 数据目录：/opt/docuseal/data（应用）、/opt/docuseal/pg_data（数据库）
• 参数源实查：应用源码 config/environments/production.rb、config/database.yml、config/puma.rb、config/initializers/dotenv.rb 等文件（官方仓库 master 分支，2026-10-30 核对）

二、前置条件

• 已按部署指南完成 Docuseal 3.3.4 双服务栈部署并能访问 Web 界面（curl http://localhost:8132/ 返回 200 或 302 均代表服务在运行）；
• 管理员账号已初始化（本文实测使用演示账号 admin@docuseal.local / q1w2e3r4）；
• 理解 Docuseal 的两层配置模型：环境变量（部署时注入，改后需重启应用进程）与界面配置（Settings 页面，保存进数据库加密字段，改后立即生效）。

三、参数查看与修改方式

3.1 两层配置模型

Docuseal 的可配置项分布在两层，修改方式与生效时机不同：

实测界面配置层的存在证据：Settings 页面包含 Profile、Account、Email、Storage、SMS、Notifications、Personalization、Users、API、Webhooks、SSO 等十余个配置子页（2026-10-30 实测页面导航清单）；其中 App URL 等敏感项在初始化时录入，保存后落入数据库加密字段（应用源码 EncryptedConfig::APP_URL_KEY 定义了该键名）。

3.2 密钥文件的自动生成与持久化

首次启动且未显式提供 SECRET_KEY_BASE 时，应用会自动生成随机密钥并连同数据库连接串写入数据目录下的 docuseal.env 文件（属主 root、权限 0600），之后每次启动自动加载。实测该文件生成于 /opt/docuseal/data/docuseal.env，包含两个键：

DATABASE_URL
SECRET_KEY_BASE

⚠️ 注意：SECRET_KEY_BASE 是应用会话与数据库字段加密的根密钥。该文件一旦丢失，数据库内所有加密字段（SMTP 口令、App URL、各类界面配置）将无法解密，且已有登录会话全部失效。升级、迁移、备份时必须包含此文件。

环境变量层修改的标准做法是在 Compose 文件 environment: 段追加变量后重建服务：

cd /opt/docuseal && docker compose up -d

实测回显（追加变量后重建，数据不受影响）：

Container docuseal-3.3.4 Running
Container docuseal-3.3.4-db Running

若修改涉及应用进程环境，Compose 会检测到配置变化并自动重建（回显中 Recreate 替代 Running），几秒内完成滚动重建。

3.3 参数生效的验证方法

配置类文档最忌「改了但不确认」。每类参数给出宿主侧可执行的验证手段，本文统一采用三种：HTTP 行为验证（curl 观察响应头/重定向）、文件系统验证（数据目录落盘产物）、日志验证（应用启动日志输出）。下文各参数逐项给出。

四、参数总览

Docuseal 3.3.4 支持的全部环境变量按用途分类如下（默认值取自应用源码，实测核对于 2026-10-30）：

💡 技术拓展：Docuseal 的数据库引擎不止 PostgreSQL 一种。应用按「DATABASE_HOST 有值 → 拆分变量连 PostgreSQL；DATABASE_URL 为空 → 内置 SQLite；DATABASE_URL 以 postgres 开头 → PostgreSQL；以 mysql/trilogy 开头 → MySQL」的顺序决策（实查自应用源码 config/database.yml 生产段）。三者对比——

引擎	触发条件	适用场景	取舍
SQLite	DATABASE_URL 留空	单机评估、功能体验	零依赖，但并发写入弱，生产不建议
PostgreSQL	URL 前缀 postgresql:	生产首选	官方 Compose 模板即此形态，全文检索与并发最佳
MySQL	URL 前缀 mysql:	既有 MySQL 体系复用	连接串自动转为 trilogy 适配器

本文实测环境采用 PostgreSQL 16（连接串前缀 postgresql://）。

五、核心参数分类详解

5.1 数据库参数

DATABASE_URL 是数据库连接的总入口，格式 postgresql://<user>:<password>@<host>:<port>/<database>。本文实测部署使用的值：

postgresql://docuseal:q1w2e3r4@docuseal-db:5432/docuseal

拆分写法（设置 DATABASE_HOST 后生效）等价于：

environment:
  - DATABASE_HOST=docuseal-db
  - DATABASE_PORT=5432
  - DATABASE_USER=docuseal
  - DATABASE_PASSWORD=q1w2e3r4
  - DATABASE_NAME=docuseal
  # 可选：DATABASE_SEARCH_PATH=public

连接池大小由两个变量共同决定：RAILS_MAX_THREADS（默认 15）+ SIDEKIQ_THREADS（默认 5）= 20 连接。数据库连接串不含 pool 参数，应用自动按此公式设置。

迁移开关 RUN_MIGRATIONS：生产环境下应用启动时自动执行数据库迁移；设为 false 可关闭（多实例滚动升级时先由一个实例执行迁移）。验证方法——升级版本后启动日志出现迁移执行记录，且数据库表结构随新版本变化。

验证方法：数据库类型可从数据目录落盘产物验证——PostgreSQL 形态下 /opt/docuseal/pg_data/ 内出现 PG_VERSION 文件：

cat /opt/docuseal/pg_data/PG_VERSION

实测回显：

16

5.2 密钥与加密参数

这一组参数决定「谁都能解密什么」，是安全核心。

SECRET_KEY_BASE：未提供时首启自动生成（随机 hex 64 字节，写入 docuseal.env）。它承担两个职责：Rails 会话签名、以及作为 ENCRYPTION_SECRET 的回落值。验证方法：文件存在且权限为 0600：

ls -l /opt/docuseal/data/docuseal.env

实测回显：

-rw------- 1 root root 221 Oct 30 11:53 /opt/docuseal/data/docuseal.env

ENCRYPTION_SECRET：显式指定时的字段加密密钥，未指定则取 SECRET_KEY_BASE 的 SHA256 摘要派生（源码逻辑：摘要前 32 字符做 primary_key、后 32 字符做 deterministic_key、整体摘要做 key_derivation_salt）。多实例部署时必须保证各实例密钥一致，否则同一密文字段在不同实例解密结果不一致。

AWS_SECRET_MANAGER_ID：企业密钥管理通道。设置后应用启动时从 AWS Secrets Manager 拉取密文并按 KEY=VALUE 逐行注入环境变量，适合不希望在编排文件里出现明文口令的场景。实测该通道与本地 docuseal.env 互斥（走 AWS 通道时不再生成本地文件）。

RUBY_YJIT_ENABLE：设为 true 时启动 Ruby YJIT 即时编译（源码中在密钥处理流程后执行 RubyVM::YJIT.enable）。高并发场景可降低 CPU 占用，代价是内存略增。

5.3 存储参数

附件存储四选一，应用按优先级自动决策（源码逻辑）：S3_ATTACHMENTS_BUCKET 有值 → S3；否则 GCS_BUCKET 有值 → GCS；否则 AZURE_CONTAINER 有值 → Azure；全部为空 → 本地磁盘（默认）。

默认本地磁盘：附件落 WORKDIR/attachments（默认 /data/docuseal/attachments），按内容哈希前两级分片。实测完成一次签署后目录结构：

attachments/
├── e2/n4/...
├── kk/gq/...
└── or/l8/...

S3 兼容存储（MinIO 等）：除三个标准 S3 变量外，S3_ENDPOINT 指向自建端点时自动启用 force_path_style（MinIO 类存储必需）：

environment:
  - S3_ATTACHMENTS_BUCKET=docuseal
  - S3_ENDPOINT=http://minio.internal:9000
  - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
  - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
  - AWS_REGION=us-east-1

⚠️ 注意：第三方对象存储的访问密钥属系统级敏感信息，应通过部署环境注入（如上方 ${VAR} 形式），不要把真实 AccessKey 写进编排文件或文档。

ACTIVE_STORAGE_PUBLIC：控制附件 URL 形态。默认 false，附件通过应用代理访问（URL 带签名与过期时间）；设为 true 且后端为公共存储时，附件直接走存储公共 URL。配合的 PRESIGNED_URLS_EXPIRE_MINUTES（默认 240 分钟）控制代理 URL 的有效期。

5.4 Web 与 TLS 参数

PORT（默认 3000）：应用监听端口，部署形态下配合端口映射使用，一般不改。

FORCE_SSL：值为非空且不等于 false 时启用（源码：assume_ssl 与 force_ssl 同时置位）。启用后 Rails 要求 HTTPS、Cookie 追加 Secure 标记。验证方法——启用前 curl -sD- http://localhost:8132/ 响应头不含 Strict-Transport-Security；启用后出现该头且 HTTP 请求被重定向到 HTTPS：

curl -sD- -o /dev/null http://localhost:8132/ | head -5

启用 FORCE_SSL=true 后的实测回显（节选）：

HTTP/1.1 301 Moved Permanently
strict-transport-security: max-age=31536000; includeSubDomains
location: https://localhost:8132/

内网 HTTP 直跑时不要启用该参数，否则所有请求被强制跳转 HTTPS 而服务端并未提供 TLS，站点将不可访问。

HOST 与 APP_URL：HOST 是对外主机名默认值，APP_URL 是生成签署链接的基地址（默认 http://localhost:3000）。注意初始化页面录入的 App URL 属于界面配置层（数据库加密字段），优先级高于环境变量的 APP_URL——两者都存在时以界面配置为准，实测发起签署后返回的 embed_src 与初始化时录入的地址一致（http://localhost:8132/s/<submitter-slug>）。

5.5 SMTP 参数

SMTP_ADDRESS 是 SMTP 总开关：有值即启用邮件发送（action_mailer.delivery_method = :smtp），为空则完全不发邮件。全套参数见第四节总览表，几个易错点：

• SMTP_PORT 默认 587（STARTTLS 标准端口）；直连 465 端口的服务需设 SMTP_ENABLE_SSL=true；
• SMTP_USERNAME 与 SMTP_PASSWORD 都设置后才启用认证（authentication 默认 plain）；
• SMTP_SSL_VERIFY=false 会跳过服务器证书校验，仅限自签证书的内网 SMTP 调试，生产禁用；
• 未配置 SMTP 时发起签署不会报错，但邮件静默不发——实测在未配置 SMTP 的情况下发起签署（API 传 send_email: false 或不传均不投递），签署人需通过签署链接访问。生产环境启用邮件通知前，先用 Settings → Email 页面或测试签署验证连通性。

5.6 并发与队列参数

Docuseal 应用是 Puma 多线程 Web 服务 + Sidekiq 后台队列的组合。默认配置下，队列与 Redis 内嵌在应用进程中运行（实测应用进程内部同时运行 redis-server 127.0.0.1:16379 与 Sidekiq 工作线程，无需独立的队列服务实例）——这是单应用部署形态的关键设计。

• RAILS_MAX_THREADS（默认 15）：Web 请求线程池上限，同时决定数据库连接池大小（加 SIDEKIQ_THREADS）；
• WEB_CONCURRENCY（默认 0）：Puma worker 进程数，0 = 单进程多线程；多核服务器设为 2–4 可提升吞吐；
• WEB_CONCURRENCY_AUTO=true：按 CPU 核数自动设定 worker 数（源码取 Etc.nprocessors）；
• MULTITENANT 与 DEMO：影响内嵌队列行为——默认（非多租户或演示模式）内嵌运行；商业多租户形态则要求独立的队列与 Redis 进程。

验证方法：应用启动日志可见 Puma 与内嵌组件的启动序列，内嵌 Redis 绑定回环地址（不对外暴露），无独立监听端口。

5.7 运维与杂项参数

• RUN_MIGRATIONS：见 5.1；
• SIDEKIQ_BASIC_AUTH_PASSWORD：设置后 Sidekiq 队列面板启用 Basic 认证（口令做 SHA256 比对），为空时面板不开放访问路径；
• SESSION_REMEMBER_DAYS：登录「记住我」有效期，默认 730 天（两年）。安全要求高的环境建议缩短；
• SESSION 相关：会话签名依赖 SECRET_KEY_BASE，轮换密钥会使全部在线会话失效。

六、生产配置模板

以下模板适用于「16GB 内存、NVMe SSD、50 用户以内的企业内部签署系统」场景，在双服务栈基础上追加生产化参数：

name: docuseal-3.3.4-stack

services:
  docuseal:
    image: docuseal/docuseal:3.3.4
    ports:
      - "8132:3000"
    volumes:
      - /opt/docuseal/data:/data/docuseal
    environment:
      - DATABASE_URL=postgresql://docuseal:${DB_PASSWORD}@docuseal-db:5432/docuseal
      - FORCE_SSL=true
      - RAILS_MAX_THREADS=20
      - WEB_CONCURRENCY=2
      - SIDEKIQ_THREADS=10
      - RUBY_YJIT_ENABLE=true
      - PRESIGNED_URLS_EXPIRE_MINUTES=60
      - SMTP_ADDRESS=smtp.example.com
      - SMTP_PORT=587
      - SMTP_USERNAME=noreply@example.com
      - SMTP_PASSWORD=${SMTP_PASSWORD}
      - SMTP_DOMAIN=example.com
      - SESSION_REMEMBER_DAYS=30
    depends_on:
      docuseal-db:
        condition: service_healthy
    networks:
      - docuseal-net
    restart: unless-stopped

  docuseal-db:
    image: postgres:16
    environment:
      POSTGRES_USER: docuseal
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: docuseal
    volumes:
      - /opt/docuseal/pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U docuseal"]
      interval: 5s
      timeout: 5s
      retries: 10
    networks:
      - docuseal-net
    restart: unless-stopped

networks:
  docuseal-net:
    driver: bridge

逐项解读：

• WEB_CONCURRENCY=2 + RAILS_MAX_THREADS=20：双 worker × 20 线程，应对 50 用户规模的峰值并发（数据库连接池相应为 20+10=30，PostgreSQL 默认 max_connections=100 足够）；
• RUBY_YJIT_ENABLE=true：高并发下降低 CPU 消耗，内存富余时开启；
• PRESIGNED_URLS_EXPIRE_MINUTES=60：缩短附件链接有效期，降低外泄风险；
• SESSION_REMEMBER_DAYS=30：企业内网签署系统将记住会话从默认两年缩到 30 天；
• SMTP 全套：正式环境邮件通知必需；
• ${DB_PASSWORD} / ${SMTP_PASSWORD}：口令通过部署环境注入，不落编排文件。

若签署量大、附件多（日均数百份以上），建议把附件存储切到对象存储（5.3 节 S3 兼容参数），本地磁盘只保留密钥文件。

七、常见问题

Q1：修改环境变量后不生效？ 环境变量在应用进程启动时读取，改完必须重建服务（docker compose up -d 会因配置变化自动 Recreate）。注意区分两层：Settings 界面配置保存即生效，无需重启；环境变量必须重建。另外 APP_URL 类参数界面配置优先于环境变量，排查时先确认数据库里是否已有界面配置值。

Q2：误删 docuseal.env 后界面配置全部读不出？ 该文件是字段加密密钥的持久化载体，删除后应用重启会生成新密钥，数据库内旧密文无法解密。恢复方法：从备份还原该文件后重启应用。因此部署指南中的数据备份命令必须包含数据目录全量（附件 + 密钥文件）。

Q3：启用 FORCE_SSL 后站点打不开？ FORCE_SSL 只是强制跳转 HTTPS，不提供 TLS 终结。应用前必须有反代承担 HTTPS（Nginx/Caddy），或直接以 HTTPS 端口对外。内网无 TLS 环境保持该变量不设置。

Q4：想用 MySQL？ 支持。把 DATABASE_URL 前缀换成 mysql:// 即可（应用自动转 trilogy 适配器）。注意首次部署就定好引擎，部署后跨引擎迁移需自备数据迁移手段（应用不提供自动转换）。

Q5：多实例横向扩容怎么配？ 保证三件事：各实例 SECRET_KEY_BASE/ENCRYPTION_SECRET 一致（统一注入而非依赖本地自动生成文件）、RUN_MIGRATIONS=false（迁移只由滚动升级中的第一个实例执行）、附件存储切到共享对象存储。内嵌 Redis 形态下队列随各实例进程运行，任务互不冲突。

八、参考链接

• 官方网站：https://www.docuseal.com/
• GitHub 仓库（参数默认值出处 config/ 目录）：https://github.com/docusealco/docuseal
• 《Docuseal 3.3.4 Docker Compose 部署指南》（部署形态与数据目录）：https://www.quzuo.net/document/mWAuoENTrgGz
• 《Docuseal 3.3.4 API 使用详解》（API Token 创建与 REST 调用实录）：https://www.quzuo.net/document/t65fBiIKUQLf
• 《Docuseal 3.3.4 介绍与选型指南》（架构与选型背景）：https://www.quzuo.net/document/IVumgpyNfzBb
• GitHub Releases：https://github.com/docusealco/docuseal/releases