Docuseal 3.3.4 Docker Compose 部署指南

目标：在一台 Ubuntu 服务器上用 Docker Compose 从零部署 Docuseal 3.3.4 电子签名平台（DocuSeal 应用 + PostgreSQL 双服务栈），完成管理员初始化、模板创建、签署流程与 REST API 验证。已在 Ubuntu 22.04（x86_64，Docker 29.9.2 / Compose v5.6.1）实测通过。

一、环境信息

操作系统：Ubuntu 22.04（x86_64，内核 5.15+ 均可）
Docker：Docker 29.9.2、Docker Compose v5.6.1（v2.x 语法兼容）
Docuseal：3.3.4（官方 Docker 镜像，2026-10-30 实查 GitHub Releases 最新稳定版）
数据库：PostgreSQL 16（官方 Compose 模板使用 PostgreSQL 15，本文实测选用 16，同为主版本线内的受支持稳定版）
应用监听端口：8132（映射到应用内部 3000 端口，3000 为 Puma 默认监听端口）
数据目录：/opt/docuseal/data（应用文件与附件）、/opt/docuseal/pg_data（数据库）
内网网段：10.89.66.0/24（独立 Compose 网络，与宿主机其他业务隔离）

💡 技术拓展：电子签名平台对「签名可信」的实现路径不止 Docuseal 的一种。常见方案对比——

方案原理特点
平台自签证书（Docuseal 采用）签署完成后由平台生成 PKCS#7/CMS 签名嵌入 PDF 开箱即用，审计链完整，证书为平台自签发
云签名服务商（DocuSign 等）签名由 CA 机构与第三方时间戳服务背书法律效力认证更完备，按签署量付费
本地 UKey/CA 证书签名密钥存于硬件令牌，本地签名合规要求高的政企场景，集成成本高

本文部署的 Docuseal 开源版采用「平台自签证书」路径，签署后的 PDF 可通过其验签接口复核签名有效性（详见本专栏姊妹篇）。

方案	原理	特点
平台自签证书（Docuseal 采用）	签署完成后由平台生成 PKCS#7/CMS 签名嵌入 PDF	开箱即用，审计链完整，证书为平台自签发
云签名服务商（DocuSign 等）	签名由 CA 机构与第三方时间戳服务背书	法律效力认证更完备，按签署量付费
本地 UKey/CA 证书	签名密钥存于硬件令牌，本地签名	合规要求高的政企场景，集成成本高

二、镜像选型说明

Docuseal 官方发布 Docker 镜像，GitHub 仓库为 docusealco/docuseal。官方仓库根目录的 docker-compose.yml 模板定义了三个服务：app（DocuSeal 应用）、postgres（PostgreSQL 15 数据库）、caddy（自动 HTTPS 反向代理）。其中 caddy 服务依赖公网域名与 DNS 解析（caddy reverse-proxy --from $HOST），内网或无公网域名的环境无法使用，本文采用「去掉 caddy、直接映射应用端口」的内网部署形态，这也是自托管评估与中小团队内网部署的常见做法。

官方镜像在 Docker Hub 上存在两个同源仓库名：docusealco/docuseal（GitHub 组织名）与 docuseal/docuseal（官方 Compose 模板中使用的名称），两个仓库的 3.3.4 标签为同一构建产物，本文实测使用 docuseal/docuseal:3.3.4。

⚠️ 网络情况说明（2026-10-30 实测）：本机 Docker 守护进程已配置 4 个国内镜像加速器（docker.m.daocloud.io、docker.1ms.run、hub.rat.dev、docker.xuanyuan.me）。按「官方源 → 国内源 → 代理」降级链实测：

docker pull docusealco/docuseal:3.3.4 —— 加速器返回「这镜像不在白名单」（DaoCloud public-image-mirror 白名单机制，未收录该仓库名），失败；
docker pull docker.1ms.run/docusealco/docuseal:3.3.4、docker pull hub.rat.dev/docusealco/docuseal:3.3.4 —— 均返回 not found，失败；
docker pull docker.xuanyuan.me/docusealco/docuseal:3.3.4 —— 该加速器免费通道不支持此镜像（需付费开通），失败；
docker pull ghcr.io/docusealco/docuseal:3.3.4 —— 官方未在 GitHub Container Registry 发布镜像（denied），失败；
docker pull docuseal/docuseal:3.3.4 —— 成功（DaoCloud 白名单收录该仓库名），拉取耗时约 1 分钟，镜像 837MB。

结论：当前国内加速渠道实测可用的是 docuseal/docuseal:3.3.4 这个仓库名；若你的网络可直连 Docker Hub，docusealco/docuseal:3.3.4 与之等效，两者可互换。

三、前置条件

部署前确认服务器满足以下条件，逐项给出验证命令与实测回显：

Docker 与 Compose 插件可用：

docker --version && docker compose version

实测回显：

Docker version 29.9.2, build a82e528
Docker Compose version v5.6.1

目标端口未被占用。本文选用 8132 端口（应用 Web 端口），确认方式：

ss -ltn | grep 8132 || echo "port 8132 free"

实测回显（空闲时）：

port 8132 free

规划 Compose 专用网段。为避免与服务器上已有网络冲突，先查看现有网段占用：

docker network ls -q | xargs docker network inspect --format '{{.Name}} -> {{range .IPAM.Config}}{{.Subnet}}{{end}}' 2>/dev/null | grep '10\.89\.'

实测回显（节选，按你服务器实际输出为准）：

isso-0.14.0-net -> 10.89.71.0/24
baikal-0101-stack_baikal-net -> 10.89.62.0/24
librebooking-v710-stack_librebooking-net -> 10.89.63.0/24

⚠️ 注意：网段选择必须避开已有网络。本文实测时曾选 10.89.65.0/24 创建失败（invalid pool request: Pool overlaps with other one on this address space，被一个未在常规列表显眼处显示的既有网络 plakar-net 占用），改用 10.89.66.0/24 后成功。创建前务必以上方命令的全量输出为准。

mkdir -p /opt/docuseal/data /opt/docuseal/pg_data

无输出即成功，用 ls -d /opt/docuseal/* 确认两个目录均已创建。

四、部署步骤

4.1 编写 Compose 文件

在 /opt/docuseal/ 下创建 docker-compose.yml，内容如下（与本文实测文件一致）：

name: docuseal-3.3.4-stack

services:
  docuseal:
    image: docuseal/docuseal:3.3.4
    container_name: docuseal-3.3.4
    ports:
      - "8132:3000"
    volumes:
      - /opt/docuseal/data:/data/docuseal
    environment:
      - DATABASE_URL=postgresql://docuseal:q1w2e3r4@docuseal-db:5432/docuseal
    depends_on:
      docuseal-db:
        condition: service_healthy
    networks:
      - docuseal-net
    restart: unless-stopped

  docuseal-db:
    image: postgres:16
    container_name: docuseal-3.3.4-db
    environment:
      POSTGRES_USER: docuseal
      POSTGRES_PASSWORD: q1w2e3r4
      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:
    name: docuseal-3-3-4-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.66.0/24

逐项说明：

name: docuseal-3.3.4-stack：显式指定 Compose 项目名。注意 Compose 会将项目名中的点号规范化为短横线，实际生成的项目名为 docuseal-3-3-4-stack，后续 down 等操作需用规范化后的名称（本文第十节给出现成命令）。
image: docuseal/docuseal:3.3.4：固定版本号而非 latest，保证升级可控。
"8132:3000"：官方镜像基于 Puma 8.0.2 监听 3000 端口（镜像 EXPOSE 3000），宿主侧映射为 8132。
DATABASE_URL：数据库连接串，指向同网络的 docuseal-db 服务。演示环境口令 q1w2e3r4，生产环境请替换为强口令。
depends_on + condition: service_healthy：等待数据库通过 pg_isready 健康检查后再启动应用，避免应用先于数据库就绪而连接失败。
networks：显式声明网段，与既有业务网络隔离；网络名 docuseal-3-3-4-net 同样做了点号规范化。

4.2 启动服务栈

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

实测回显：

 Network docuseal-3-3-4-net Creating
 Container docuseal-3.3.4-db Creating
 Container docuseal-3.3.4-db Started
 Container docuseal-3.3.4-db Waiting
 Container docuseal-3.3.4-db Healthy
 Container docuseal-3.3.4 Starting
 Container docuseal-3.3.4 Started

Container docuseal-3.3.4-db Healthy 一行说明健康检查生效，应用是在数据库就绪后才启动的。确认运行状态：

docker compose ps --format 'table {{.Name}}\t{{.Status}}\t{{.Ports}}'

实测回显：

NAME                STATUS                    PORTS
docuseal-3.3.4      Up 8 seconds              0.0.0.0:8132->3000/tcp, [::]:8132->3000/tcp
docuseal-3.3.4-db   Up 13 seconds (healthy)   5432/tcp

4.3 验证 Web 服务就绪

首次启动时应用会自动完成数据库表结构迁移（Rails migration），数秒后即可访问。验证方式：

curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' http://localhost:8132/

实测回显（首次部署、管理员未初始化时）：

302 http://localhost:8132/setup

302 且 Location 指向 /setup 说明服务已就绪，且处于「待初始化」状态。

4.4 管理员初始化

浏览器访问 http://<服务器IP>:8132/，会自动跳转到初始化页面 /setup，填写以下信息（表单字段按页面实际顺序）：

First name：Admin
Last name：Docuseal
Email：admin@docuseal.local
Company name（公司/组织名）：Docuseal
App URL：http://<服务器IP>:8132（应用对外访问地址，用于生成签署链接，部署后有域名就填域名）
Password（登录口令）：q1w2e3r4

提交后跳转到欢迎页，初始化完成。用演示账号 admin@docuseal.local / q1w2e3r4 登录即可进入模板管理界面。

⚠️ 注意：/setup 只在首次部署且无任何用户时可用；初始化完成后再次访问 http://localhost:8132/ 直接返回 200（登录欢迎页），/setup 不再开放。若忘记口令，官方开源版未提供自助找回，需要删除数据库后重新初始化（见第十节备份的重要性）。

4.5 验证版本与核心功能可用

登录后从界面右上角 Settings → API 页面确认 API Token 体系可用（后续 REST API 实测见本专栏姊妹篇）；创建一个 PDF 模板并发起一次签署的最小验证路径：Templates → Upload（上传 PDF）→ 拖拽字段 → Send。本文实测上传一份 PDF 后模板即刻生成（模板接口返回 "id":2,"slug":"mgM7Xu5MVrjsEv"，字段为空等待拖拽配置），签署完成后系统自动生成带审计日志的签署版 PDF，全流程约 2 分钟。

五、数据持久化说明

Docuseal 的全部持久化数据分为两处，均通过 bind mount 落到宿主机：

数据	容器内路径	宿主机路径	内容
应用数据	`/data/docuseal`	`/opt/docuseal/data`	附件（上传 PDF、签署后 PDF、审计日志）、自动生成的 `docuseal.env`、内嵌 Redis 持久化文件 `dump.rdb`
数据库	`/var/lib/postgresql/data`	`/opt/docuseal/pg_data`	PostgreSQL 16 全部库表数据

实测 /opt/docuseal/data 内部结构（应用运行并完成一次签署后）：

attachments/   # 上传与签署产生的文件，按内容哈希前两级分片存放（如 e2/n4/...）
docuseal.env   # 首次启动自动生成的密钥文件（root 属主 0600 权限），保存 DATABASE_URL 与 SECRET_KEY_BASE
dump.rdb       # 内嵌 Redis 的持久化文件（后台任务队列状态）

两点务必知晓：

docuseal.env 是密钥持久化机制：首次启动若未显式提供 SECRET_KEY_BASE，应用会随机生成并连同 DATABASE_URL 写入该文件，之后每次启动自动加载。该文件丢失会导致数据库中加密字段（如 SMTP 口令、App URL）无法解密，务必纳入备份。
附件目录采用内容寻址分片（如 attachments/e2/n4/xxx），直接复制整个 attachments/ 目录即可完整备份文件数据。

六、环境变量表

部署本栈可配置的环境变量如下（仅列部署层常用项；应用内全部参数的逐项详解见第七节及本专栏姊妹篇）：

变量	作用	本部署取值	默认行为
`DATABASE_URL`	数据库连接串（PostgreSQL/MySQL）	`postgresql://docuseal:q1w2e3r4@docuseal-db:5432/docuseal`	留空且未设 `DATABASE_HOST` 时自动降级为内置 SQLite（`WORKDIR/db.sqlite3`）
`WORKDIR`	应用数据目录	镜像默认 `/data/docuseal`	附件、`docuseal.env`、内嵌 SQLite 均落此目录
`RAILS_ENV`	运行环境	镜像默认 `production`	生产模式，开启自动迁移
`FORCE_SSL`	强制 HTTPS	未设置（内网 HTTP）	设置后启用 HSTS 与安全 Cookie，反代 TLS 终结时配合使用
`POSTGRES_USER/PASSWORD/DB`	数据库初始化凭据	`docuseal` / `q1w2e3r4` / `docuseal`	PostgreSQL 官方镜像变量，仅首次初始化生效

💡 说明：DATABASE_URL 与 DATABASE_HOST 等拆分变量两种写法二选一；数据库引擎除 PostgreSQL 外还支持 MySQL 与内置 SQLite，三者的决策链与完整参数（DATABASE_HOST/PORT/USER/PASSWORD/NAME/SEARCH_PATH）在本专栏姊妹篇有逐项实测说明。

七、配置参数说明

7.1 数据库连接参数

DATABASE_URL 是应用连接数据库的标准入口，格式 postgresql://<user>:<password>@<host>:<port>/<db>。实测两种替代写法：

拆分变量：设置 DATABASE_HOST、DATABASE_PORT、DATABASE_USER、DATABASE_PASSWORD、DATABASE_NAME（可选 DATABASE_SEARCH_PATH 指定 PostgreSQL schema），应用会忽略 DATABASE_URL 而按拆分变量组装连接；
全部留空：应用直接使用内置 SQLite（数据落 WORKDIR/db.sqlite3），单机评估场景零依赖，但并发写入能力弱，生产不建议。

7.2 数据库健康检查

官方 Compose 模板为数据库服务定义了 pg_isready 健康检查（5 秒间隔、10 次重试），应用服务通过 depends_on.condition: service_healthy 依赖它。实测该机制生效——启动日志先出现 Container docuseal-3.3.4-db Healthy 再出现 Container docuseal-3.3.4 Started。若自行删掉健康检查，应用首次启动可能因数据库未就绪而报连接错误（应用具备重试能力，但会拖慢启动并产生报错日志）。

7.3 端口与对外地址

ports: "8132:3000" 中的 3000 是镜像内 Puma 的固定监听端口（PORT 环境变量可改，一般无需动）；8132 是宿主侧自选端口。
初始化页面的 App URL（保存在数据库加密配置中）决定签署链接、邮件链接的域名前缀。实测发起签署后 API 返回的 embed_src 即基于该地址生成（http://localhost:8132/s/<submitter-slug>）。部署后如果域名变更，可在 Settings 内修改，不需要改数据库。

7.4 TLS 反向代理

内网 HTTP 直跑时 FORCE_SSL 不设置。若需要对外 HTTPS，推荐在应用前加一层 Nginx/Caddy 反代终结 TLS，并在应用侧设置 FORCE_SSL=true（使 Rails 启用 assume_ssl 与 force_ssl，Cookie 走 Secure 标记）。官方模板选择 Caddy 自动签发证书，需要公网域名；已有 Nginx 体系的环境用 Nginx 挂证书即可，两种方式效果一致。

八、配置文件挂载

Docuseal 应用没有传统意义上的主配置文件——配置由「环境变量 + 数据库内加密配置（Settings 界面）」两层组成，因此挂载侧只需处理数据目录：

    volumes:
      - /opt/docuseal/data:/data/docuseal

该 bind mount 覆盖了应用全部文件态数据（附件、密钥文件、内嵌 Redis 持久化）。实测卸载并重建服务栈后，/opt/docuseal/data 与 /opt/docuseal/pg_data 中的数据原样保留，管理员账号、模板、签署记录均不丢失——这正是 bind mount 相对匿名卷的价值：数据路径显式可见、备份直接 cp。

若要自定义 SMTP、对象存储等更多行为，直接在 compose 的 environment: 段追加变量后 docker compose up -d 重建生效，无需挂载额外文件。

九、等价 docker run

不使用 Compose 的等价启动方式（单机快速验证）。先创建独立网络与数据库：

docker network create --subnet 10.89.66.0/24 docuseal-manual-net
docker run -d --name docuseal-manual-db \
  -e POSTGRES_USER=docuseal -e POSTGRES_PASSWORD=q1w2e3r4 -e POSTGRES_DB=docuseal \
  -v /opt/docuseal/pg_data:/var/lib/postgresql/data \
  --network docuseal-manual-net postgres:16
docker run -d --name docuseal-manual \
  -p 8132:3000 \
  -e DATABASE_URL=postgresql://docuseal:q1w2e3r4@docuseal-manual-db:5432/docuseal \
  -v /opt/docuseal/data:/data/docuseal \
  --network docuseal-manual-net docuseal/docuseal:3.3.4

说明：应用容器需要等数据库完成首次初始化（约 5–10 秒）后启动才不会报连接重试日志，可用 docker logs docuseal-manual-db 看到 database system is ready to accept connections 出现两次后再启动应用。官方单容器极简跑法（内置 SQLite、零外部依赖）：

docker run -d --name docuseal-sqlite \
  -p 8132:3000 \
  -v /opt/docuseal/data:/data/docuseal \
  docuseal/docuseal:3.3.4

不传 DATABASE_URL 时自动使用 SQLite，适合功能体验；生产部署仍建议 PostgreSQL（数据库选型对比见本专栏姊妹篇）。

十、常用运维命令

以下命令均在 /opt/docuseal/ 目录（compose 文件所在处）执行。

# 查看两服务状态与健康检查结果
docker compose ps

实测回显：

NAME                STATUS                    PORTS
docuseal-3.3.4      Up 2 minutes              0.0.0.0:8132->3000/tcp, [::]:8132->3000/tcp
docuseal-3.3.4-db   Up 2 minutes (healthy)    5432/tcp

# 跟踪应用日志（Rails production 日志直接输出到前台）
docker compose logs -f docuseal
# 重启应用（数据库不动）
docker compose restart docuseal
# 停止整个栈（保留数据）
docker compose down
# 彻底销毁栈并删除网络与卷（bind mount 数据不受影响）
docker compose -p docuseal-3-3-4-stack down

⚠️ 注意：down 命令带 -p docuseal-3-3-4-stack 是因为 Compose 将项目名中的点号规范化为短横线；不带 -p 在 compose 文件所在目录执行 docker compose down 同样有效。跨目录清理时用规范化项目名。

数据库备份与恢复：

# 备份：导出 PostgreSQL 全库
docker compose exec docuseal-db pg_dump -U docuseal docuseal > /opt/docuseal/backup_$(date +%F).sql
# 恢复：导入备份
cat /opt/docuseal/backup_2026-10-30.sql | docker compose exec -T docuseal-db psql -U docuseal docuseal

文件数据备份（附件与密钥）：

tar czf /opt/docuseal/data_backup_$(date +%F).tar.gz /opt/docuseal/data

升级到新版本：修改 compose 中两处版本号（image: docuseal/docuseal:<新版本>）后执行 docker compose up -d，应用启动时自动执行数据库迁移（RUN_MIGRATIONS 默认开启）。回滚同理改回旧版本号重建，但需注意新版迁移可能不可逆，回滚前务必先做数据库备份。

十一、常见问题

Q1：拉取 docusealco/docuseal 报「这镜像不在白名单」？ 国内镜像加速器的白名单机制未收录该仓库名。实测改用官方 Compose 模板同款仓库名 docuseal/docuseal:3.3.4 即可成功拉取，两者为同一构建产物（详见第二节降级链实录）。若使用代理网络，也可为 Docker 守护进程配置代理后直连 Docker Hub。

Q2：创建网络报 Pool overlaps with other one on this address space？ 所选网段与服务器上既有网络（包括已停止容器遗留的网络）冲突。用第三节的全量检查命令列出所有 10.x 网段后换一个空闲网段。本文实测 10.89.65.0/24 被占用、改 10.89.66.0/24 成功。

Q3：首次访问一直 302 跳 /setup，初始化后再访问首页仍 302？ 两种情况：未初始化时跳 /setup（正常，按 4.4 完成即可）；初始化完成后若仍跳 /setup，说明浏览器会话指向了另一个未初始化的实例（比如端口映射指向了旧容器），核对 docker compose ps 确认只有一个应用实例在服务。

Q4：应用启动日志出现数据库连接错误后自动恢复？ 应用先于数据库就绪启动导致。确认 compose 中 depends_on 的 condition: service_healthy 未被删除；应用具备连接重试能力，通常几秒内自愈，但规范做法是保留健康检查依赖。

Q5：发起签署后签署人收不到邮件？ 开源版默认未配置 SMTP，邮件不会发出（本文实测发起签署时显式传 send_email: false 规避）。内网验证可通过签署链接直接访问（API 返回的 embed_src 地址）；正式启用邮件通知需配置 SMTP 全套变量（SMTP_ADDRESS/PORT/USERNAME/PASSWORD 等，逐项含义见《Docuseal 3.3.4 配置参数详解》），或在 Settings 界面配置。

十二、参考链接

官方网站：https://www.docuseal.com/
GitHub 仓库：https://github.com/docusealco/docuseal
官方 Docker Compose 模板：https://raw.githubusercontent.com/docusealco/docuseal/master/docker-compose.yml
GitHub Releases（版本发布记录）：https://github.com/docusealco/docuseal/releases
官方 API 文档：https://www.docuseal.com/docs/api
《Docuseal 3.3.4 配置参数详解》（环境变量与实例配置体系）：https://www.quzuo.net/document/EYTIRw2Tyued
《Docuseal 3.3.4 API 使用详解》（REST API 实测实录）：https://www.quzuo.net/document/t65fBiIKUQLf
《Docuseal 3.3.4 介绍与选型指南》（定位与同类对比）：https://www.quzuo.net/document/IVumgpyNfzBb