简介
DocuSeal 是一个开源的数字文档签署和处理平台，提供安全、高效的电子签名解决方案。它允许用户创建可填写和签署的 PDF 表单，可在任何设备上使用，具有易于使用的、移动优化的 Web 工具。DocuSeal 是 DocuSign 的开源替代方案，可自托管部署。
核心功能
文档签署流程
| 功能 |
说明 |
| PDF 表单字段构建器 (WYSIWYG) |
可视化编辑器，用于创建可填写的 PDF 表单 |
| 12 种字段类型 |
包括签名、日期、文件、复选框等字段类型 |
| 多签署人支持 |
允许多人签署同一份文档 |
| 自动 PDF 电子签名 |
数字签名自动应用到文档 |
| PDF 签名验证 |
内置签名验证功能 |
| 移动端优化 |
响应式设计，支持任何设备 |
模板与表单
- 通过 HTML API 创建模板: 可编程创建可填写表单
- 通过 PDF/DOCX 字段标签创建模板: 使用嵌入式文本字段标签
- 嵌入式签署表单: 支持 React、Vue、Angular 和 JavaScript
- 嵌入式文档表单构建器: 主要框架的集成 SDK
通信与存储
- SMTP 自动邮件: 签署流程的邮件通知
- 文件存储选项: 本地磁盘、AWS S3、Google Storage、Azure Cloud
- 用户管理: 用户管理功能
- 多语言支持: 7 种 UI 语言，签署支持 14 种语言
Pro 企业版功能
| 功能 |
说明 |
| 公司 Logo 与白标定制 |
品牌自定义 |
| 用户角色管理 |
权限管理 |
| 自动提醒 |
跟进通知 |
| SMS 邀请与验证 |
通过短信进行身份验证 |
| 条件字段与公式 |
动态表单行为 |
| 批量发送 |
CSV/XLSX 导入批量签署 |
| SSO / SAML |
企业级身份认证 |
| 模板创建 API |
HTML API、PDF/DOCX 字段标签 |
技术架构
语言分布
| 语言 |
占比 |
| Ruby |
~43.9% |
| Vue |
~32.1% |
| HTML |
~24.3% |
| JavaScript |
~13.8% |
| SCSS |
~0.2% |
后端架构
核心框架: Ruby on Rails (Ruby 4.0.1)
主要后端技术:
| 技术 |
用途 |
| Rails |
Web 核心框架 |
| Devise |
身份认证（支持双因素） |
| Cancancan |
授权/权限管理 |
| Sidekiq |
后台任务处理 |
| Puma |
Web 服务器 |
| Turbo-Rails |
Hotwired 实时更新 |
| Pagy |
分页 |
数据库支持:
| 数据库 |
说明 |
| SQLite3 |
默认（零配置） |
| PostgreSQL |
生产环境推荐 |
| MySQL |
支持（trilogy gem） |
PDF 处理:
| 技术 |
用途 |
| HexaPDF |
PDF 操作与签名 |
| RubyXL |
Excel/XLSX 处理 |
| Ruby-Vips |
图像处理 |
云存储:
| 服务 |
Gem |
| AWS S3 |
aws-sdk-s3 |
| Google Cloud Storage |
google-cloud-storage |
| Azure Blob |
azure-blob |
安全与认证:
| 技术 |
用途 |
| JWT |
API 认证 |
| ROTP |
TOTP 时间令牌 |
| RQRCode |
QR 码生成 |
| Devise-Two-Factor |
双因素认证 |
前端架构
核心框架: Vue.js 3.3.2 + Shakapacker
主要前端技术:
| 技术 |
版本 |
用途 |
| Vue 3 |
3.3.2 |
组件框架 |
| Hotwired Turbo |
- |
实时页面更新 |
| TailwindCSS |
3.4 |
CSS 框架 |
| DaisyUI |
3.9 |
Tailwind 组件库 |
| Shakapacker |
9.5 |
Rails Webpack 集成 |
| Webpack |
5.104 |
模块打包 |
富文本与表单:
| 技术 |
版本 |
用途 |
| TipTap |
3.19 |
富文本编辑器 |
| CodeMirror |
6 |
代码编辑 |
| Signature Pad |
4.1 |
数字签名捕获 |
架构模式
混合单体架构: Rails 单体后端 + Vue.js 嵌入组件（通过 Shakapacker）。使用 Hotwired Turbo 进行服务器驱动的导航，Vue 用于交互式组件（签名板、表单构建器、富文本编辑器）。
安装与部署
Docker 快速启动
bash
复制代码
# 使用 SQLite（最简单）
docker run --name docuseal -p 3000:3000 -v .:/data docuseal/docuseal
Docker Compose 生产部署
bash
复制代码
# 下载配置文件
curl https://raw.githubusercontent.com/docusealco/docuseal/master/docker-compose.yml > docker-compose.yml
# 启动（自动 SSL）
sudo HOST=your-domain-name.com docker compose up
Docker Compose 包含：
- app: DocuSeal 应用（端口 3000）
- postgres: PostgreSQL 18 数据库
- caddy: 反向代理（自动 SSL）
云平台一键部署
环境变量配置
数据库配置
| 变量 |
说明 |
DATABASE_URL |
PostgreSQL/MySQL 连接 URL，空则使用 SQLite |
DATABASE_HOST |
数据库主机 |
DATABASE_PORT |
数据库端口（默认 5432） |
DATABASE_USER |
数据库用户名 |
DATABASE_PASSWORD |
数据库密码 |
DATABASE_NAME |
数据库名称 |
存储配置
本地存储:
| 变量 |
说明 |
WORKDIR |
数据存储目录（默认 .） |
ACTIVE_STORAGE_PUBLIC |
设为 true 公开文件访问 |
AWS S3:
| 变量 |
说明 |
AWS_ACCESS_KEY_ID |
AWS 访问密钥 |
AWS_SECRET_ACCESS_KEY |
AWS 密钥 |
AWS_REGION |
AWS 区域（默认 us-east-1） |
S3_ATTACHMENTS_BUCKET |
S3 存储桶名称 |
S3_ENDPOINT |
自定义 S3 端点 |
Google Cloud Storage:
| 变量 |
说明 |
GCS_CREDENTIALS |
GCS 凭证 JSON |
GCS_PROJECT |
GCS 项目名称 |
GCS_BUCKET |
GCS 存储桶名称 |
Azure Blob Storage:
| 变量 |
说明 |
AZURE_STORAGE_ACCOUNT_NAME |
Azure 存储账户 |
AZURE_STORAGE_ACCESS_KEY |
Azure 访问密钥 |
AZURE_CONTAINER |
Azure 容器名称 |
SMTP 邮件配置
| 变量 |
说明 |
SMTP_ADDRESS |
SMTP 服务器地址 |
SMTP_PORT |
SMTP 端口（默认 587） |
SMTP_DOMAIN |
SMTP 域名 |
SMTP_USERNAME |
SMTP 用户名 |
SMTP_PASSWORD |
SMTP 密码 |
SMTP_AUTHENTICATION |
认证方式（默认 plain） |
SMTP_ENABLE_STARTTLS |
启用 STARTTLS（默认 true） |
安全配置
| 变量 |
说明 |
SECRET_KEY_BASE |
Rails 密钥（未设置时自动生成） |
FORCE_SSL |
强制 SSL 的域名 |
RAILS_ENV |
环境模式（production） |
Redis 配置
| 变量 |
说明 |
REDIS_URL |
Redis 连接 URL（未设置时自动创建本地实例） |
API 文档
API 端点
| 资源 |
端点 |
方法 |
说明 |
| Submissions |
/submissions |
GET, POST |
列出/创建提交 |
|
/submissions/{id} |
GET, DELETE |
获取/删除提交 |
|
/submissions/{id}/documents |
GET |
获取提交文档 |
|
/submissions/pdf |
POST |
从 PDF 创建提交 |
|
/submissions/docx |
POST |
从 DOCX 创建提交 |
|
/submissions/html |
POST |
从 HTML 创建提交 |
| Templates |
/templates |
GET |
列出所有模板 |
|
/templates/{id} |
GET |
获取模板 |
|
/templates/pdf |
POST |
从 PDF 创建模板 |
|
/templates/docx |
POST |
从 DOCX 创建模板 |
|
/templates/html |
POST |
从 HTML 创建模板 |
|
/templates/merge |
POST |
合并模板 |
| Submitters |
/submitters |
GET |
列出所有签署人 |
|
/submitters/{id} |
GET, PATCH |
获取/更新签署人 |
API 服务器:
| 区域 |
URL |
| 美国 |
https://api.docuseal.com |
| 欧洲 |
https://api.docuseal.eu |
认证
使用 X-Auth-Token 头进行 API Key 认证：
bash
复制代码
curl https://api.docuseal.com/templates -H 'X-Auth-Token: API_KEY'
获取 API Key：
- 注册 https://docuseal.com/sign_up
- 访问 https://console.docuseal.com/api
Webhooks
| Webhook 类型 |
说明 |
| Form Webhook |
表单提交时触发 |
| Submission Webhook |
提交状态变更时触发 |
| Template Webhook |
模板事件触发 |
SDK 支持
API SDK
| 语言/平台 |
包名 |
安装命令 |
| JavaScript/TypeScript |
@docuseal/api |
npm install @docuseal/api |
| Python |
docuseal |
pip install docuseal |
| Ruby |
docuseal |
gem install docuseal |
| PHP |
docusealco/docuseal-php |
composer require docusealco/docuseal-php |
| CLI |
docuseal |
npm install -g docuseal |
嵌入式组件 SDK
集成示例
React 嵌入签署表单
jsx
复制代码
import React from "react"
import { DocusealForm } from '@docuseal/react'
function App() {
return (
<DocusealForm
src="https://docuseal.com/d/LEVGR9rhZYf86M"
email="submitter@example.com"
onComplete={(data) => console.log('签署完成!', data)}
/>
)
}
JavaScript/HTML 嵌入
html
复制代码
<script src="https://docuseal.com/js/embed.js"></script>
<docuseal-form src="https://docuseal.com/d/LEVGR9rhZYf86M"></docuseal-form>
API 创建提交
javascript
复制代码
const resp = await fetch("https://api.docuseal.com/submissions", {
method: "POST",
headers: {
"X-Auth-Token": "API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
template_id: 123,
send_to: ["signer@example.com"],
submitters_order: "random",
submitters: [
{
email: "submitter@example.com",
name: "John Doe",
fields: [
{ name: "signature_field", value: "" }
]
}
]
})
});
const data = await resp.json();
console.log(data);
Python SDK 使用
python
复制代码
from docuseal import Docuseal
docuseal = Docuseal(api_key="API_KEY")
submissions = docuseal.list_submissions(limit=10)
Ruby SDK 使用
ruby
复制代码
require 'docuseal'
Docuseal.key = "API_KEY"
submissions = Docuseal.list_submissions(limit: 10)
生产部署示例
yaml
复制代码
# docker-compose.yml 生产配置
services:
app:
image: docuseal/docuseal:latest
ports:
- "3000:3000"
volumes:
- ./docuseal:/data/docuseal
environment:
- DATABASE_URL=postgresql://user:password@postgres:5432/docuseal
- SMTP_ADDRESS=smtp.example.com
- SMTP_USERNAME=user@example.com
- SMTP_PASSWORD=yourpassword
- FORCE_SSL=your-domain.com
postgres:
image: postgres:18
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: password
POSTGRES_DB: docuseal
自托管最低要求
最小配置（SQLite 模式）:
- Docker 容器
- 端口 3000
- 数据持久化卷
/data
生产配置:
- PostgreSQL 或 MySQL 数据库
- Redis（自动配置或通过
REDIS_URL）
- SMTP 服务器（邮件通知）
- 可选：S3/GCS/Azure 文件存储
- SSL 终止（使用
FORCE_SSL 或反向代理）
应用场景
| 行业 |
应用 |
| 金融银行 |
贷款合同、开户协议 |
| 医疗健康 |
患者同意书、医疗记录 |
| 交通物流 |
运输合同、货物签收 |
| 房地产 |
租赁合同、买卖协议 |
| 电子商务 |
用户协议、订单确认 |
| KYC 认证 |
身份验证文档 |
| CRM 系统 |
客户合同管理 |
资源链接
快速开始指南
评估功能
- 使用 Docker 快速启动：
docker run --name docuseal -p 3000:3000 -v .:/data docuseal/docuseal
- 访问 http://localhost:3000 测试功能
- 创建模板并测试签署流程
生产部署
- 使用 docker-compose.yml 配置 PostgreSQL
- 配置 SMTP 邮件发送
- 设置
FORCE_SSL 启用 HTTPS
- 可选配置云存储（S3/GCS/Azure）
API 集成
- 注册获取 API Key
- 选择合适的 SDK（React/Vue/Angular/JS/Python/Ruby）
- 嵌入签署表单或使用 REST API
总结
DocuSeal 是一个功能完整的开源电子签名平台，具备：
- 开源免费: AGPLv3 许可证，可自托管
- 技术栈现代: Ruby on Rails + Vue.js 3 + TailwindCSS
- 部署灵活: Docker、云平台一键部署
- API 完善: REST API + 多语言 SDK
- 嵌入集成: React/Vue/Angular 嵌入组件
- 企业功能: SSO、批量发送、白标定制
适合需要自托管电子签名解决方案的企业和开发者，是 DocuSign 等商业产品的优质开源替代方案。