docassemble 1.10.15 Docker Compose 部署指南

目标：在单台服务器上以 Docker Compose 部署 docassemble 1.10.15 官方全栈镜像（Web + PostgreSQL + Redis + RabbitMQ + Celery + LibreOffice 一体），并完成「登录 → 创建访谈 → 运行作答 → 退出」端到端验收。本文已在真实环境实测通过：Ubuntu 26.04.1 LTS 宿主，Docker Compose 5.6.1，映射端口 8139→80。

一、环境信息

• 宿主操作系统：Ubuntu 26.04.1 LTS，x86_64
• 编排工具：Docker Compose 5.6.1（com.docker.compose.version 标签实测值）
• 应用镜像：jhpyle/docassemble:latest（ID aaa4a57e7d06，虚拟大小 15.8GB；内置 docassemble 1.10.15，/usr/share/docassemble/webapp/VERSION → 1.10.15）
• 镜像基座：Ubuntu 26.04.1 LTS（org.opencontainers.image.version=26.04 标签实测）
• 内置组件版本（实测）：Python 3.14.4 / Flask 3.1.3 / PostgreSQL 18.6 / Redis 8.0.5 / RabbitMQ 4.0.5 / nginx 1.28.3 / Celery 5.6.3
• 服务名与容器名：docassemble / docassemble-1.10.15-web，主机名 da-server
• 端口映射：0.0.0.0:8139->80/tcp
• 数据卷：命名卷 da-backup → /usr/share/docassemble/backup
• 网络：自定义 bridge docassemble-net（子网 10.89.61.0/24）
• 资源要求（官方口径，实测吻合）：内存 ≥4GB，磁盘 ≥40GB

二、镜像选型说明

docassemble 官方提供三条容器化路线：

💡 技术拓展：单容器全栈的「持久化」与常规中间件不同——镜像设计为除 backup 卷外全部可丢弃：安全关机时把 config/files/日志打包进 /usr/share/docassemble/backup，下次开机反向恢复；因此只挂 backup 一个卷即可保住全部状态（机制详解见「五、数据持久化说明」）。

镜像 tag 实测（2026-11-01 经代理查询 Docker Hub jhpyle/docassemble/tags，官方源直连超时）：latest, 1.10.15, 1.10.14, 1.10.13, 1.10.12, 1.10.11, 1.10.10, 1.10.9——生产建议锁定版本号 tag（如 1.10.15）而非 latest，便于回滚。

三、前置条件

1. 宿主机已安装 Docker 与 Docker Compose（docker compose version 有回显即可）。
2. 宿主端口 8139 空闲（本环境 Web 端口槽分配 8139）。
3. 磁盘余量 ≥40GB：df -h 确认。
4. 拉取国外镜像走宿主 Docker 守护进程配置的加速器/代理即可；本次 docker pull 实测成功。

四、部署步骤

4.1 编写 compose 文件

# docker-compose.yml（实测文件，项目名 docassemble-11015-stack）
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
    networks:
      - docassemble-net

networks:
  docassemble-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.61.0/24

volumes:
  da-backup:

逐项说明：

• stop_grace_period: 600s：必须设置。内置 PostgreSQL 在安全关机时要把 config/files/数据库备份到 backup 卷，官方要求 docker stop -t 600 等价的 600 秒优雅停机窗口，强杀会触发「不安全关机」保护（见 5.2）。
• DAHOSTNAME: "localhost:8139"：写入生成配置 config.yml 的 external hostname 与 url root（实测 url root: http://localhost:8139）。生产应填真实域名。
• TIMEZONE: "Asia/Shanghai"：实测落到 config.yml 的 timezone: Asia/Shanghai。
• USEHTTPS: "false"：HTTP 形态（use https: false），生产配证书时改 true 并可加 USELETSENCRYPT/LETSENCRYPTEMAIL。

4.2 启动

docker compose up -d

实测 docker compose ps 回显：

NAME                      IMAGE                       COMMAND                  SERVICE       CREATED       STATUS       PORTS
docassemble-1.10.15-web   jhpyle/docassemble:latest   "/usr/bin/supervisor…"   docassemble   2 hours ago   Up 2 hours   0.0.0.0:8139->80/tcp, [::]:8139->80/tcp

4.3 首启时序（实测）

首次启动 supervisord 后按序拉起组件：initialize（PID 7）→ postgres/redis 秒级就绪 → nltk/celery/uwsgi/nginx 等约 17 分钟后 RUNNING。期间访问站点返回启动页：

curl -s http://localhost:8139/ | grep -oE '<title>[^<]+</title>'

• 启动中：<title>Docassemble is starting</title>
• 完成后：<title>Default interview</title>（出厂默认访谈页）

容器日志实测（docker logs --tail 8 docassemble-1.10.15-web，节选）：

2026-11-01 07:44:05,182 INFO success: rabbitmq entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
2026-11-01 07:44:05,278 INFO spawned: 'celery' with pid 3442
2026-11-01 07:44:05,281 INFO spawned: 'celerysingle' with pid 3443
2026-11-01 07:44:10,923 INFO success: celery entered RUNNING state, process has stayed up for > than 5 seconds (startsecs)
2026-11-01 07:44:11,063 INFO exited: reset (exit status 0; expected)

4.4 验证进程与端口

docker exec docassemble-1.10.15-web supervisorctl status

实测关键行（uptime 为取证时刻值）：

main:postgres  RUNNING   pid 177, uptime 1:57:33
main:redis     RUNNING   pid 234, uptime 1:57:27
rabbitmq       RUNNING   pid 3125, uptime 1:37:22
celery         RUNNING   pid 3442, uptime 1:37:20
nginx          RUNNING   pid 1569, uptime 1:40:57
uwsgi          RUNNING   pid 1510, uptime 1:41:02

HTTP 验收：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8139/
# 200

4.5 登录与改密（实测）

浏览器访问 http://localhost:8139/user/sign-in（注意：登录路径是 /user/sign-in，/users/signin 实测 404）。出厂账号 admin@example.com / password 首登成功，系统强制 302 到 /user/change-password。密码策略实测报错原文：

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

演示口令 q1w2e3r4 因缺大写被拒，改用 Q1w2e3r4 实测通过，登录后进入 Interviews 页（<title>Interviews</title>）。

五、数据持久化说明

5.1 唯一必挂卷：backup

实测 compose 只挂载 da-backup:/usr/share/docassemble/backup。安全关机（docker compose down / docker stop 留足 600s）时，节点把 config/、files/、日志、数据库备份（pg_dump -F c）rsync 进 backup；下次开机 initialize 从 backup 反向恢复。实测 backup 卷当前内容：

drwxr-xr-x 3 root     root     4096 Nov  1 21:17 .
drwxr-xr-x 7 www-data www-data 4096 Nov  1 22:07 files

（files/ 子目录即关机备份产物；每日 cron 还会生成 MM-DD 滚动备份目录，保留 backup days: 14 天。）

5.2 不安全关机保护（实测脚本逻辑）

initialize.sh 实测关键段：

RESTOREFROMBACKUP=true
if [ -f /var/run/docassemble/da_running ] || [ -f /var/run/docassemble/status-rabbitmq-running ]; then
    echo "initialize: unsafe shutdown detected; will not restore from backup" >&2
    RESTOREFROMBACKUP=false
fi

解读：开机时若发现上次遗留的 da_running 标记（说明被强杀），不会用 backup 覆盖现场，避免回滚掉最后一次安全备份之后的数据。因此生产停机务必走优雅停止，给足 600 秒。

5.3 数据落点速查

六、环境变量表

实测生效与官方文档对照（脚本源码实测 + 官方 Docker 文档）：

⚠️ 网络说明：查询 Docker Hub tag 列表时官方源直连超时（curl 无回显），已改用代理 192.168.1.72:7897 实测可用（HTTP 200）。镜像拉取本身走宿主 Docker 守护进程既有加速渠道，未发生降级。

七、配置参数说明

首启时 initialize 依据环境变量从模板 config.yml.dist 生成 /usr/share/docassemble/config/config.yml。实测关键项（全文 3976B）：

debug: true
enable playground: true
allow log viewing: true
allow demo: true
root owned: false
db:
  prefix: postgresql+psycopg2://
  name: docassemble
  user: docassemble
  password: abc123        # 出厂默认，生产必改
  host: null              # null=用内置 PG
secretkey: ZnIhpMKjXCYDudCjxCzXqOzBACHOWMUa   # 首启自动生成
backup days: 14
timezone: Asia/Shanghai
url root: http://localhost:8139
external hostname: localhost:8139
use https: false
web server: nginx
xsendfile: true
use nginx to serve files: true
update on start: true
allow updates: true
allow configuration editing: true
enable api: True
default interview: docassemble.base:data/questions/default-interview.yml
exitpage: https://docassemble.org
language: en
s3:
  enable: false
azure:
  enable: false
use minio: false

逐项要点：

• db.password: abc123：出厂默认口令，生产部署必须改为强口令并同步 PG；本文演示环境保留默认值以便复现。
• secretkey：首启随机生成的会话签名密钥，持久化在 config.yml 内，丢失会导致全部登录失效，备份时注意它含敏感信息。
• allow configuration editing: true：允许在 Web /config 页直接编辑本文件（实测页面 200）。
• enable playground: true：开启在线访谈编辑器（本文验收依赖它）。
• update on start: true + allow updates: true：开机检查 pip 更新（升级控制项，运维篇详解）。
• default interview：首页挂载的默认访谈；上线后应改挂自己的业务访谈。

八、配置文件挂载

若不想依赖 backup 卷的关机备份机制，可把配置目录直接 bind mount 到宿主：

    volumes:
      - /opt/docassemble/config:/usr/share/docassemble/config
      - /opt/docassemble/backup:/usr/share/docassemble/backup

⚠️ 注意：bind mount config/ 后，root owned: false（实测值）决定 config.yml 属主为 www-data；宿主侧目录需允许该 UID 写入，否则首启生成配置失败。同时开机恢复逻辑会用 backup 里的 config.yml 覆盖它，两处数据要保持一致。

九、等价 docker run

本文实测形态等价于官方推荐的单命令部署（官方 Docker 文档口径：docker run -d -p 80:80 -p 443:443 --restart always --stop-timeout 600 jhpyle/docassemble）。按本环境端口与变量展开：

docker run -d --name docassemble-1.10.15-web \
  --hostname da-server \
  --restart unless-stopped \
  --stop-timeout 600 \
  -p 8139:80 \
  -e DAHOSTNAME="localhost:8139" \
  -e TIMEZONE="Asia/Shanghai" \
  -e USEHTTPS="false" \
  -v docassemble_da-backup:/usr/share/docassemble/backup \
  --network docassemble-net \
  jhpyle/docassemble:latest

说明：--stop-timeout 600 对应 compose 的 stop_grace_period: 600s；卷名 docassemble_da-backup 为 compose 自动命名前缀（docker volume ls 可见），复用既有卷即可保留数据。

十、常用运维命令

# 查看服务状态
docker compose ps

# 跟踪启动日志（首启 17 分钟排障用）
docker logs -f docassemble-11015-stack-docassemble-1

# 优雅停止（触发安全备份，勿加 -t 1 强杀）
docker compose down

# 进入节点做进程级检查
docker exec -it docassemble-1.10.15-web supervisorctl status

# 重启 Web 应用（配置改动后）
docker exec docassemble-1.10.15-web supervisorctl restart uwsgi

# 重载数据库结构/缓存（官方 reset 流程）
docker exec docassemble-1.10.15-web supervisorctl start reset

# 查数据库（内置 PG）
docker exec -it docassemble-1.10.15-web psql -U docassemble -d docassemble -h localhost

# 查会话缓存
docker exec docassemble-1.10.15-web redis-cli -n 1 dbsize

实测回显示例——supervisorctl start reset 后 celery 状态变化（uwsgi/nginx 进程号不变，reset 走 touch-reload 热重载）：

reset: started
celery STARTING→RUNNING

psql 实测（SELECT version(); 节选）：

PostgreSQL 18.6 (Ubuntu 18.6-0ubuntu0.26.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 15.2.0-16ubuntu1) 15.2.0, 64-bit

十一、常见问题

Q1： 部署后访问 http://localhost:8139 一直显示 "Docassemble is starting"？ A： 首启正常现象。initialize 要跑 apt-get update、pip 依赖与 NLTK 词库下载，实测总时长约 17 分钟。用 docker logs -f 观察 supervisord 各进程进入 RUNNING 的时序即可判断进度，完成后标题自动变为 "Default interview"。

Q2： 登录页 404？ A： 正确路径是 /user/sign-in（实测 200）；/users/signin 是旧版路径写法，本版本实测 404。

Q3： 改密时提示密码不合规？ A： 策略要求至少 6 位且含大写、小写、数字等，实测报错原文见 4.5 节。q1w2e3r4 无大写被拒，Q1w2e3r4 通过。

Q4： docker compose down 后重新 up，访谈文件/配置丢失？ A： 检查两点：① backup 卷是否复用（docker compose down 不带 --volumes 即保留）；② 上次是否被强杀——开机日志出现 unsafe shutdown detected; will not restore from backup 说明上次未走 600 秒优雅停机，本次不会自动恢复备份，需手动从 backup 卷 files/ 目录找回。

Q5： 访谈打开就报 "Docassemble has finished executing all code blocks..."？ A： 新手最常见配置错误：question 块没标 mandatory: True 且无代码引用，拉取模型无事可做直接终止。给入口问题加 mandatory: True（写法见本文验收实测 YAML）。

十二、端到端验收：创建并运行访谈（实测）

部署完成的最终验收以「业务访谈跑通」为准。以下 YAML 为实测通过版本（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

实测运行序列（curl 驱动，Cookie 会话复用）：

# 1) 运行访谈
GET /interview?i=docassemble.playground1:g25final.yml
→ 200，首屏 <h1>请输入您的姓名</h1>（拉取模型：mandatory 块引用 person.name.first，自动先问姓名）

# 2) 提交答案「张三」
POST /interview?i=docassemble.playground1:g25final.yml
→ 200，<h1>您好，张三！这是 docassemble 实测访谈。</h1>
        当前服务器时间：November 1, 2026

# 3) 点 Exit 按钮（表单字段 _multiple_choice 的 value 是索引 "0"，不是字符串 "exit"）
POST → 302，Location: https://docassemble.org（config.yml 的 exitpage 生效）

三个实测踩坑（写 YAML 时务必注意）：

1. 插值必须 ${ var }，单花括号 { var } 不渲染、原样显示；
2. 1.10.15 已移除 today_datetime()，取当前时间用 current_datetime()，且函数需 modules: - docassemble.base.util 显式导入；
3. Individual 对象姓名写 person.name.first，只定义 person.name 会报 reference to a variable 'person.name.first' that could not be looked up。

更多平台认知与选型对比见 《docassemble 1.10.15 介绍与选型指南》。

十三、参考链接

• 官方 Docker 文档：https://docassemble.org/docs/docker.html
• 官方配置文档：https://docassemble.org/docs/config.html
• 官方 Compose 仓库：https://github.com/jhpyle/docassemble-compose
• GitHub 发布记录：https://github.com/jhpyle/docassemble/releases
• Hello World 教程：https://docassemble.org/docs/helloworld.html