docassemble 1.10.15 介绍与选型指南

目标：帮助读者在 30 分钟内建立对 docassemble 1.10.15 的完整认知——它是什么、内部怎么运转、能做什么、最小示例怎么跑通、与同类表单/问卷平台如何取舍。本文所有命令与输出均在真实环境实测：Ubuntu 26.04.1 LTS 节点（Docker 全栈形态，容器内 PID 1 为 supervisord），已完整跑通「创建访谈 → 作答 → 渲染 → 退出」全流程。

一、环境信息

操作系统：Ubuntu 26.04.1 LTS（实测节点，/etc/os-release 回显 PRETTY_NAME="Ubuntu 26.04.1 LTS"）
应用：docassemble 1.10.15（cat /usr/share/docassemble/webapp/VERSION → 1.10.15）
运行时：Python 3.14.4，虚拟环境 /usr/share/docassemble/local3.14
Web 栈：nginx 1.28.3 + uWSGI（socket /var/run/uwsgi/docassemble.sock）+ Flask 3.1.3
数据与中间件：PostgreSQL 18.6、Redis 8.0.5、RabbitMQ 4.0.5、Celery 5.6.3
进程管理：supervisord（PID 1），约 20 个受管进程
对外端口：8139 → 80（HTTP，use https: false 形态）
镜像：jhpyle/docassemble:latest（ID aaa4a57e7d06，虚拟大小 15.8GB）
取证日期：2026-11-01

⚠️ 实测口径说明：官方文档将 docassemble 定位为「基于 Python、YAML 和 Markdown 的免费开源专家系统，用于引导式访谈与文档装配」。本批次实测的 Docker 全栈形态内含 PostgreSQL、Redis、RabbitMQ、Celery、LibreOffice（unoserver）、NLTK、exim4 等组件，并不包含 Elasticsearch——全文检索类需求需另行规划，勿按「ES 全栈」选型。

二、软件概述

docassemble 由 Jonathan Pyle（GitHub 账号 jhpyle）设计开发，代码以 MIT 许可证 开源（官网首页声明 "Code licensed under MIT"，文档为 CC BY 3.0）。它不是一个普通的「在线表单制作器」，而是一个引导式访谈（guided interview）+ 文档装配（document assembly）专家系统：

用 YAML/Markdown 混合 DSL 描述「问什么问题、怎么问、答案之间有什么逻辑关系」；
引擎按「拉取（pull）模型」驱动流程：先声明哪些信息是必需的，引擎自动倒推需要向用户提哪些问题（实测验证见「三、核心架构」3.3 节）；
访谈结束后把收集到的变量注入 DOCX/Markdown 模板，生成法律文书（PDF/DOCX）或直接提交数据。

典型使用方：法律援助组织（替当事人填法院表格）、政府服务窗口（资格预审问卷）、企业合规（尽调清单）、律所（合同生成）。官方口号是 "Ask the questions. Get the documents."

GitHub 仓库实测元数据（2026-11-01 查询 GitHub API）：

license: MIT | stars: 998 | forks: 322 | open_issues: 12
pushed_at: 2026-10-30T00:25:23Z
description: A free, open-source expert system for guided interviews
and document assembly, based on Python, YAML, and Markdown.

三、核心架构

3.1 进程拓扑（实测）

Docker 全栈形态下，supervisord 作为 PID 1 统一拉起全部角色。supervisorctl status 实测回显（节选，uptime 为取证时刻值）：

apache2        STOPPED   Not started
celery         RUNNING   pid 3442, uptime 1:37:20
celerysingle   RUNNING   pid 3443, uptime 1:37:20
cron           RUNNING   pid 1662, uptime 1:40:53
exim4          RUNNING   pid 2027, uptime 1:40:50
main:initialize RUNNING pid 7,  uptime 1:58:14
main:postgres  RUNNING   pid 177, uptime 1:57:33
main:redis     RUNNING   pid 234, uptime 1:57:27
nginx          RUNNING   pid 1569, uptime 1:40:57
nltk           RUNNING   pid 1374, uptime 1:41:18
rabbitmq       RUNNING   pid 3125, uptime 1:37:22
unoserver      RUNNING   pid 1600, uptime 1:40:55
uwsgi          RUNNING   pid 1510, uptime 1:41:02
watchdog       RUNNING   pid 9,  uptime 1:58:14
websockets     RUNNING   pid 2771, uptime 1:37:26

各进程职责：

进程	职责
nginx	静态文件、反向代理，`location /` → uWSGI Unix socket
uwsgi	承载 Flask 应用 `docassemble.webapp.run:application`（1 进程 × 6 线程）
main:postgres / main:redis	内置 PostgreSQL 18.6 / Redis 8.0.5
rabbitmq + celery + celerysingle	异步任务（文档生成、邮件、备份等）经 RabbitMQ 4.0.5 分发
websockets	访谈实时辅助（聊天/电话协助模式）
unoserver	LibreOffice 无头服务，DOCX→PDF 转换
nltk	自然语言词库加载（分词/拼写等）
exim4	出站邮件
cron	每日备份/证书续期任务
watchdog	守护与状态上报

💡 技术拓展：docassemble 官方给出三种部署形态，不止「单容器全栈」一种——

形态特点适用
单容器 all-in-one（jhpyle/docassemble 镜像）全部组件由 supervisord 管在一个节点内，运维面最小单机、中小规模、快速上线
Compose 多服务（官方 jhpyle/docassemble-compose 仓库） webapp/core/libreoffice/pandoc/tesseract 拆为独立服务，可单独扩缩需要按角色扩容、镜像瘦身
Helm/Kubernetes（jhpyle/charts）多副本、云原生，配合 kubernetes: true 配置高可用、弹性伸缩

本文实测采用第一种单容器全栈形态（CONTAINERROLE 默认 all）；多机分角色可通过环境变量 CONTAINERROLE=web:celery:... 拆分，属进阶形态。

形态	特点	适用
单容器 all-in-one（`jhpyle/docassemble` 镜像）	全部组件由 supervisord 管在一个节点内，运维面最小	单机、中小规模、快速上线
Compose 多服务（官方 `jhpyle/docassemble-compose` 仓库）	webapp/core/libreoffice/pandoc/tesseract 拆为独立服务，可单独扩缩	需要按角色扩容、镜像瘦身
Helm/Kubernetes（`jhpyle/charts`）	多副本、云原生，配合 `kubernetes: true` 配置	高可用、弹性伸缩

3.2 请求链路（实测配置）

nginx 站点配置实测（/etc/nginx/sites-enabled/docassemblehttp）：

server {
    listen 80;
    server_tokens off;
    server_name localhost:8139;
    client_max_body_size 16777216;
    location / { try_files $uri @docassemble; }
    location @docassemble {
        include uwsgi_params;
        uwsgi_pass unix:///var/run/uwsgi/docassemble.sock;
    }
    location /ws { proxy_pass http://127.0.0.1:5000; }
    location /ws/socket.io {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_pass http://127.0.0.1:5000/socket.io;
    }
}

解读：client_max_body_size 16777216 限制上传体积 16MB；/ws 前缀转发给 websockets 进程（5000 端口）支撑实时聊天；其余全部交给 uWSGI。uWSGI 侧实测 docassemble.ini：processes = 1、threads = 6、touch-reload = docassemble.wsgi（改动 .wsgi 文件即热重载）。

3.3 访谈引擎：拉取模型（实测验证）

docassemble 的访谈不是「按 YAML 顺序一题题问」，而是拉取模型：引擎先求值 mandatory: True 的块，块里引用了哪个未定义变量，就倒推去执行「能定义该变量的那个 question 块」。实测证据：把「问候页」标为 mandatory 且引用 person.name.first，首屏渲染出来的却是「请输入您的姓名」——引擎为凑齐问候页所需变量，自动回头问了姓名。

反之，若所有 question 块都不标 mandatory 且无代码引用，引擎会认为「无事可做」直接终止并报：

Docassemble has finished executing all code blocks marked as initial
or mandatory, and finished asking all questions marked as mandatory (if any).
It is a best practice to end your interview with a question that says goodbye.

这是新手最常见的「访谈一打开就报错」根因（详见排错沉淀）。

3.4 数据模型

会话与访谈变量：PostgreSQL userdict 表（实测 25 张表之一），filename 列存访谈路径、key 列存会话号、dictionary 列存加密序列化状态；Redis（db 1 系统级 / db 2 访谈变量 DARedis）做缓存层。实测 redis-cli -n 1 dbsize → 16，redis-cli -n 2 dbsize → 0（本环境变量缓存走 PG 主存）。
文件存储：/usr/share/docassemble/files/（Playground 文件实测落 files/playground/1/<名>.yml）；生产可切 S3/Azure/MinIO（s3.enable、use minio 配置项，默认 false）。

四、功能特性

YAML 访谈 DSL：question/fields/buttons/mandatory/objects/modules 等块组合出条件分支、循环（deletion/repeat）、复核页（review）、多用户（multi）等流程；实测最小示例见「五、快速开始」。
Playground 在线编辑器：登录后 /playground 直接新建/编辑/运行 YAML，免打包；实测创建文件即写 files/playground/1/（SAVE:200）。
文档装配：Markdown→PDF/DOCX（LibreOffice unoserver 实测 RUNNING），支持邮件发送、SMS、传真（enable faxing: True 等开关实测在配置中）。
多语言与本地化：language: en 默认，支持逐访谈多语言；实测本环境 timezone: Asia/Shanghai 生效（问候页日期按此时区渲染）。
REST API：enable api: True 实测开启；/api/interview 等端点需 api_key+email 鉴权，未带密钥实测返回 404（隐藏端点存在性）。
OAuth 第三方登录：config 内置 facebook/google/auth0/keycloak/authentik/zitadel/azure/github/miniorange 九种 provider 模板（实测均 enable: False）。
数据管理：访谈数据 CSV/Excel 导出、在线查看；/logs 页可 Web 查看服务器日志（allow log viewing: true 实测 LOGS-PAGE:200）。
包管理：访谈以「包」分发（docassemble.demo 1.10.15 实测已预装），支持从 GitHub/上传安装，/package 页管理。

💡 技术拓展：文档装配的转换引擎不止 LibreOffice 一条路——

引擎用途本环境实测状态
unoserver（LibreOffice） DOCX→PDF 保真转换 RUNNING，enable unoconv: true
pandoc Markdown↔DOCX/HTML 全栈镜像未内置，官方 compose 仓库有独立服务
Gotenberg 外部转换微服务（HTTP API）配置存在但 gotenberg.enable: false

本文环境采用 unoserver 路线。

引擎	用途	本环境实测状态
unoserver（LibreOffice）	DOCX→PDF 保真转换	RUNNING，`enable unoconv: true`
pandoc	Markdown↔DOCX/HTML	全栈镜像未内置，官方 compose 仓库有独立服务
Gotenberg	外部转换微服务（HTTP API）	配置存在但 `gotenberg.enable: false`

五、快速开始（最小可用示例，实测）

以下流程在取证环境完整执行过，命令与输出均为实测。

5.1 起服务

# docker-compose.yml（实测文件）
name: docassemble-1.10.15-stack
services:
  docassemble:
    image: jhpyle/docassemble:latest
    container_name: docassemble-1.10.15-web
    hostname: da-server
    restart: unless-stopped
    stop_grace_period: 600s
    ports:
      - "8139:80"
    environment:
      DAHOSTNAME: "localhost:8139"
      TIMEZONE: "Asia/Shanghai"
      USEHTTPS: "false"
    volumes:
      - da-backup:/usr/share/docassemble/backup

docker compose up -d 后实测 docker compose ps：

NAME                      IMAGE                       STATUS      PORTS
docassemble-1.10.15-web   jhpyle/docassemble:latest   Up 2 hours  0.0.0.0:8139->80/tcp

⚠️ 首次启动需下载 Python 依赖与 NLTK 词库，实测总时长约 17 分钟；期间访问 http://localhost:8139 返回 <title>Docassemble is starting</title> 页面，完成后自动变为访谈首页。stop_grace_period: 600s 不可省略——内置 PostgreSQL 需要时间安全落盘，强杀会导致数据损坏。

5.2 登录

首访用出厂账号 admin@example.com / password 登录 /user/sign-in，系统强制跳转改密。实测密码策略回显：

Password must be at least six characters long with at least one
lowercase letter, at least one uppercase letter...

q1w2e3r4 因无大写被拒；改为 Q1w2e3r4 后实测登录成功：

LOGIN:302
GET /interviews → <title>Interviews</title>

5.3 创建并运行一个访谈

Playground 新建 g25final.yml，内容（实测通过版本）：

---
modules:
  - docassemble.base.util
---
objects:
  - person: Individual
---
id: greeting
question: 您好，${ person.name.first }！这是 docassemble 实测访谈。
subquestion: |
  当前服务器时间：${ current_datetime() }
buttons:
  - Exit: exit
mandatory: True
---
id: ask-name
question: 请输入您的姓名
fields:
  - 姓名: person.name.first

三个实测关键点：① 变量插值必须用 ${ }，单花括号 { } 不渲染、原样显示；② 1.10.15 已移除 today_datetime()，取当前时间用 current_datetime()，且需 modules: - docassemble.base.util 显式导入；③ Individual 对象的姓名要写 person.name.first，只定义 person.name 会报 reference to a variable 'person.name.first' could not be looked up。

访问 http://localhost:8139/interview?i=docassemble.playground1:g25final.yml，实测首屏（拉取模型自动先问题目）：

RUN:200  <h1>请输入您的姓名</h1>

填入「张三」提交后，实测问候页渲染：

H1: 您好，张三！这是 docassemble 实测访谈。
TIME: 当前服务器时间：November 1, 2026

点 Exit 按钮，实测返回 302，Location 指向配置的 exitpage: https://docassemble.org——访谈全生命周期（创建→运行→作答→渲染→退出）闭环验证通过。

六、适用场景与限制

适合：

法律/政务/合规类「问答式收集 + 出正式文档」场景（核心价值是拉取模型 + 文档装配）；
需要复杂条件分支、计算、复核修改、多语言的法律表单自动化；
单节点起步、后续可平滑拆多角色/上 k8s 的团队。

限制与成本（实测口径）：

镜像虚拟大小 15.8GB，官方建议节点 ≥4GB 内存、≥40GB 磁盘；首启约 17 分钟；
访谈 DSL 学习曲线陡：插值语法、拉取模型、函数导入（modules）三处新手必踩（见 5.3）；
无内置全文检索（无 Elasticsearch），历史数据复杂查询需直连 PostgreSQL；
版本发布节奏快：实测 GitHub releases 近 5 个版本 1.10.7（2026-08-02）→ 1.10.15（2026-10-23），约每 2 周一个小版本，升级需关注兼容；
容器内不提供 docassemble 管理 CLI（实测 da*/manage 入口不存在），日常管理走 supervisorctl + psql + redis-cli + Web 界面。

七、同类选型对比

实测 GitHub API 数据（查询日期 2026-11-01）：

项目	许可证	Stars	最近推送	定位
docassemble	MIT	998	2026-10-30	引导式访谈 + 法律文书装配专家系统
surveyjs/survey-library	MIT	4918	2026-11-01	JS 前端表单库（需自配后端）
formio/formio.js	MIT	2086	2026-10-30	JSON 表单构建器（表单引擎+低代码）
LimeSurvey	GPL 系（API 返回 NOASSERTION）	3786	2026-11-01	在线问卷/调查平台
getodk/central	Apache-2.0	231	2026-10-23	ODK 移动端数据采集服务器

解读与选型建议：

要「问完直接生成正式文档（DOCX/PDF 法律文书）」：选 docassemble。其余四者均无「访谈变量 → 模板文档装配」的内生闭环，SurveyJS/Form.io 是表单引擎，出文档要自己接渲染服务；
要「高颜值拖拽表单 + 嵌入自家前端」：SurveyJS（stars 最多、纯前端组件化）更合适，但它不含服务端访谈逻辑；
要「问卷统计」：LimeSurvey 开箱即用；docassemble 的 collect statistics: false 默认关闭，非其强项；
要「离线移动端采数（田野调查）」：ODK Central 是标准答案；
社区活跃度：docassemble 体量最小（998 stars）但推送活跃、issue 仅 12 个且版本节奏稳定（约 2 周/版），主作者一人主导——选型时要接受「单一维护方」风险，好在 MIT 许可证与自托管形态保证可长期锁定版本使用。

八、参考链接

官网与文档：https://docassemble.org/docs/introduction.html
GitHub 仓库：https://github.com/jhpyle/docassemble（LICENSE.txt 为 MIT）
Docker 部署文档：https://docassemble.org/docs/docker.html
配置参考：https://docassemble.org/docs/config.html
Hello World 教程：https://docassemble.org/docs/helloworld.html
官方 Compose 仓库：https://github.com/jhpyle/docassemble-compose
Helm charts：https://github.com/jhpyle/charts