draw.io 32.5.5 Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上用 Docker Compose 从 0 到 1 部署 draw.io 32.5.5（官方镜像 jgraph/drawio），覆盖镜像选型、单服务编排、健康检查、HTTP/HTTPS 双通道验证、数据持久化说明、升级与回滚全流程，全部命令与回显均在真实环境实测通过。draw.io 的定位与选型背景见《draw.io 介绍与选型指南》，逐项配置见，运维命令全景见。

一、环境信息

项目	值
操作系统	Ubuntu 22.04（x86_64，IP 192.168.146.128）
draw.io 版本	32.5.5（官方最新稳定版，2026-10-18 发布；Releases 页 2026-10-22 查证）
容器化基座	Docker Compose v5.5.1（`docker compose version` 实测）
官方镜像	`jgraph/drawio:32.5.5`（Docker Hub，2026-10-19 推送）
部署目录	/opt/drawio/
服务端口	8139 → 应用 HTTP 8080；8150 → 应用 HTTPS 8443
应用内部	Tomcat 9（`tomcat:9.0-jdk11-temurin` 基座，Java 11.0.32.1），以非 root 用户 tomcat（UID 1001）运行
编排项目名	drawio-32.5.5-stack

💡 说明：draw.io 服务端是无状态静态应用（编辑器全部在浏览器端运行，图表默认存于浏览器本地），因此本方案不需要数据库、不需要数据卷，单服务编排即完整生产形态。宿主机端口 8139/8150 为本文实测端口，若 80/443 空闲可直接替换（"80:8080"、"443:8443"）。

二、镜像选型说明

2.1 为什么选 jgraph/drawio

draw.io 的官方容器化在独立仓库 jgraph/docker-drawio 维护，发布到 Docker Hub jgraph/drawio（来源：官方仓库 README「Running」节与 docker-drawio README，2026-10-22 查证）。选它而非社区分叉的理由：

官方出品、跟随 Release：每个 draw.io Release 对应一个镜像 tag，dev tag 跟随主干（Docker Hub tags 列表 2026-10-22 查证：32.5.5、32.4.1、32.3.0… 均有对应镜像）；
单一镜像策略：官方声明「Starting from version 16.5.3, alpine and debian images are no longer maintained. We changed to a single image that uses the tomcat image with the least security vulnerabilities.」——不存在 alpine/debian 变体可选，无选型歧义；
非 root 运行：镜像默认以专用用户 tomcat（UID 1001，GID 999）运行，无需额外配置即满足安全基线（docker-drawio README「Running as a non-root user」节）；
HTTPS 开箱即用：启动时自动生成自签名证书（有效期 3600 天），也可切换 Let's Encrypt 自动签发。

2.2 tag 选择对照表

tag	含义	适用场景
`32.5.5`	精确版本（与 GitHub Release v32.5.5 一致）	生产固定版本，升级可控（本文采用）
`latest`	跟随最新稳定 Release	想始终最新；升级不可控，不建议生产
`dev`	跟随开发主干	测试新特性，勿用于生产

⚠️ 注意：latest 与精确版本 tag 的更新时间可能相差一两天（Docker Hub 上 32.5.5 推送于 2026-10-19，latest 同日同步），生产环境一律固定精确版本号。

三、前置条件

Ubuntu 22.04 服务器已安装 Docker Engine 与 Docker Compose v2 插件（docker compose version 可用，本文实测 v5.5.1）；
服务器可访问 Docker Hub（离线环境可先在有网机器 docker pull + docker save 迁入）；
计划使用的宿主机端口空闲（本文 8139、8150），用 ss -ltn | grep -E '8139|8150' 确认无输出；
部署目录规划为 /opt/drawio/。

ss -ltn | grep -E '8139|8150'

实测回显（无输出即端口空闲）：

（无输出）

四、部署步骤

4.1 创建部署目录与编排文件

本节把官方镜像编排成带健康检查的单服务部署清单。创建目录并写入 docker-compose.yml：

mkdir -p /opt/drawio && cd /opt/drawio
vim docker-compose.yml

docker-compose.yml 完整内容：

name: drawio-32.5.5-stack

services:
  drawio:
    image: jgraph/drawio:32.5.5
    container_name: drawio-32.5.5-app
    restart: unless-stopped
    ports:
      - "8139:8080"
      - "8150:8443"
    healthcheck:
      test: ["CMD", "curl", "-f", "-o", "/dev/null", "-s", "http://localhost:8080/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s
    networks:
      - drawio-net

networks:
  drawio-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.73.0/24

逐项说明：

name: drawio-32.5.5-stack：显式编排项目名，避免与其他项目的 compose 栈重名冲突；
image：固定官方精确版本 tag（见 2.2 节）；
ports：8139 → 应用 HTTP 8080，8150 → 应用 HTTPS 8443（应用内置 Tomcat，8443 端口在启动时自动挂自签证书）；
healthcheck：镜像内置 curl（实测确认 /usr/bin/curl 存在），每 30 秒探测本地 8080 首页，start_period: 20s 给 Tomcat 启动留缓冲；
networks：显式指定网段，避免与服务器上其他部署网段冲突（内网部署多套服务时务必检查 docker network ls）；
restart: unless-stopped：开机自启、异常退出自动拉起。

4.2 启动服务

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

实测回显：

[+] Running 3/3
 ✔ Network drawio-3255-stack_drawio-net  Created
 ✔ Container drawio-32.5.5-app           Created
 ✔ Container drawio-32.5.5-app           Started

💡 说明：首次启动会自动生成自签名证书并渲染配置脚本（PreConfig.js/PostConfig.js），启动日志中可见「Generating Self-Signed certificate」，全程约 2 秒。Tomcat 完成启动实测 Server startup in [393] milliseconds。

4.3 验证服务状态

先看编排状态（等待健康检查转 healthy）：

cd /opt/drawio && docker compose ps

实测回显（启动约 35 秒后）：

NAME                IMAGE                  COMMAND                   SERVICE   CREATED          STATUS                    PORTS
drawio-32.5.5-app   jgraph/drawio:32.5.5   "/docker-entrypoint.…"   drawio    36 seconds ago   Up 35 seconds (healthy)   0.0.0.0:8139->8080/tcp, [::]:8139->8080/tcp, 0.0.0.0:8150->8443/tcp, [::]:8150->8443/tcp

HTTP 通道验证：

curl -s -o /dev/null -w 'HTTP %{http_code}  size=%{size_download}  time=%{time_total}s\n' http://192.168.146.128:8139/
curl -sI http://192.168.146.128:8139/ | head -8

实测回显：

HTTP 200  size=4134  time=0.044580s
HTTP/1.1 200
Accept-Ranges: bytes
ETag: W/"4134-1792383932000"
Last-Modified: Mon, 19 Oct 2026 04:25:32 GMT
Content-Type: text/html
Content-Length: 4134
Date: Wed, 21 Oct 2026 19:28:26 GMT

HTTPS 通道验证（自签证书需 -k）：

curl -sk -o /dev/null -w 'HTTPS %{http_code}\n' https://192.168.146.128:8150/
curl -skv https://192.168.146.128:8150/ 2>&1 | grep -E 'subject|issuer|SSL connection'

实测回显：

HTTPS 200
* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
*  subject: C=FR; ST=Paris; L=Paris; O=example inc; OU=Cloud Native Application; CN=draw.example.com
*  issuer: C=FR; ST=Paris; L=Paris; O=example inc; OU=Cloud Native Application; CN=draw.example.com

编辑器关键静态资源抽查（编辑器 JS、配置注入脚本）：

for p in "/" "/js/app.min.js" "/js/PreConfig.js" "/js/PostConfig.js" "/js/viewer.min.js" "/service-worker.js"; do printf "%-22s " "$p"; curl -s -o /dev/null -w '%{http_code} %{size_download}B\n' "http://192.168.146.128:8139$p"; done

实测回显：

/                     200 4134B
/js/app.min.js        200 10216662B
/js/PreConfig.js      200 1459B
/js/PostConfig.js     200 350B
/js/viewer.min.js     200 6852493B
/service-worker.js    200 33058B

4.4 浏览器验收

浏览器访问 http://192.168.146.128:8139/?offline=1（内网部署推荐带 offline=1，禁用云存储入口），应看到 draw.io 编辑器首页并可直接绘图、导出。?offline=1 是官方容器 README 声明的安全特性：禁用对云存储（Google Drive/OneDrive 等）的支持。

⚠️ 注意：HTTPS 通道使用自签证书，浏览器会弹「不安全」告警，属预期行为；替换为 Let's Encrypt 或反向代理证书的方案见第六章与常见问题 Q3。

五、数据持久化说明

draw.io 服务端无状态，这是它与其他协作平台最大的架构差异，部署前必须理解：

图表数据不落服务器：图表默认保存在浏览器本地存储（localStorage/IndexedDB），服务端无数据库、无数据目录；容器重建不丢「服务」，但用户浏览器清缓存会丢「未另存的图」；
集中存储走外部集成：需要团队级集中存储时，配置 Google Drive / OneDrive / 自建 GitLab 集成（OAuth 凭据经环境变量注入，详见），图表文件存网盘/Git 仓库；
唯一有价值的挂载是自定义字体：官方 README「Custom fonts」节说明，编辑器在浏览器端渲染文字，向容器挂字体文件不会直接生效于编辑器字体选择器，正确做法是「DRAWIO_CONFIG 声明 defaultFonts/customFonts + 把字体文件挂到 webapp 目录随 HTTP 提供」：

    volumes:
      - /opt/drawio/fonts:/usr/local/tomcat/webapps/draw/fonts:ro

对应在 DRAWIO_CONFIG 中声明（示意，完整参数见配置篇）：

{"defaultFonts":["Helvetica",{"fontFamily":"My Font","fontUrl":"https://drawio.example.com/fonts/MyFont.woff2"}]}

需要备份的只有配置：/opt/drawio/docker-compose.yml（编排）与 .env（若有）——图表数据本体不在服务器，无数据备份负担。

六、HTTPS 与反向代理注意点

6.1 应用内置 HTTPS（自签证书）

镜像内置 Tomcat 的 HTTPS 连接器（8443，TLSv1.2），证书主体等参数可用环境变量定制（实测章节见）：

    environment:
      PUBLIC_DNS: "draw.example.com"     # 证书 CN
      ORGANISATION: "example inc"        # 证书 O
      KEYSTORE_PASS: "changeit"          # keystore 口令（默认 V3ry1nS3cur3P4ssw0rd，务必改）

6.2 Let's Encrypt 自动签发

官方 README 给出的内置 certbot 方案要求宿主机 80 端口可达且域名已解析（standalone 模式）：

docker run -it -m1g \
  -v "/opt/drawio/letsencrypt-log:/var/log/letsencrypt/" \
  -v "/opt/drawio/letsencrypt-etc:/etc/letsencrypt/" \
  -v "/opt/drawio/letsencrypt-lib:/var/lib/letsencrypt" \
  -e LETS_ENCRYPT_ENABLED=true -e PUBLIC_DNS=drawio.example.com \
  --rm -p 80:80 -p 443:8443 jgraph/drawio

要点：宿主 80 → 容器 80 供 certbot 验证，宿主 443 → 容器 8443 由 Tomcat 直接服务 HTTPS；三个 letsencrypt 挂载目录让证书持久化。

6.3 前置 Nginx 反向代理（推荐生产形态）

生产更常见的形态是 Nginx 统一终止 TLS、draw.io 只暴露内网端口。最小可用 server 块：

server {
    listen 443 ssl;
    server_name drawio.example.com;
    # ssl_certificate / ssl_certificate_key 按实际路径配置

    location / {
        proxy_pass http://127.0.0.1:8139;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto https;
    }
}

三个官方特别提醒（来源：docker-drawio README，2026-10-22 查证）：

DRAWIO_SERVER_URL 要写成对外完整 URL（含尾斜杠），如 https://drawio.example.com/，编辑器据此生成分享链接；
子路径部署：DRAWIO_SERVER_URL=https://www.example.com/drawio/ 时应用自动把 Tomcat context 切到 /drawio（实测验证见部署 URL 分域一节）；反向代理若映射的公开路径与子路径不同，需改写 Cookie path（nginx：proxy_cookie_path /drawio/ /tools/drawio/;），否则登录集成返回 401；
OAuth 回调：启用网盘/GitLab 集成后，回调 URI 按 DRAWIO_SERVER_URL 注册（如 https://drawio.example.com/gitlab）。

七、环境变量表

draw.io 镜像的全部行为由环境变量驱动（启动时渲染进 PreConfig.js/PostConfig.js）。按域分组概览（逐项含义/默认值/实测行为见）：

分域	变量	作用
部署 URL	`DRAWIO_SERVER_URL` / `DRAWIO_BASE_URL` / `DRAWIO_VIEWER_URL` / `DRAWIO_LIGHTBOX_URL`	对外地址、分享链接、查看器/灯箱地址
编辑器配置	`DRAWIO_CONFIG` / `DRAWIO_CONFIG_FILE` / `DRAWIO_LANG`	JSON 配置对象（字体/AI 等）、配置文件、默认语言
存储集成	`DRAWIO_GOOGLE_CLIENT_ID(+SECRET/APP_ID)`、`DRAWIO_MSGRAPH_CLIENT_ID(+SECRET/TENANT_ID)`、`DRAWIO_GITLAB_ID(+SECRET/URL)`	三类外部存储 OAuth 凭据，未配置即禁用
证书	`LETS_ENCRYPT_ENABLED`、`PUBLIC_DNS`、`ORGANISATION(UNIT)`、`CITY`、`STATE`、`COUNTRY_CODE`、`KEYSTORE_PASS`、`KEY_PASS`	自签/Let's Encrypt 证书参数
安全	`DRAWIO_CSP_HEADER`、`ENABLE_DRAWIO_PROXY`、`DRAWIO_USE_HTTP`	CSP 策略、/proxy 端点开关、显式允许 HTTP

八、配置文件挂载

DRAWIO_CONFIG 走环境变量适合短配置；配置项多时用文件挂载 + DRAWIO_CONFIG_FILE（优先级高于环境变量值）：

    environment:
      DRAWIO_CONFIG_FILE: /config/drawio-config.json
    volumes:
      - /opt/drawio/drawio-config.json:/config/drawio-config.json:ro

/opt/drawio/drawio-config.json 示例（关闭开始页 + 预设默认字体）：

{
  "showStartScreen": false,
  "defaultFonts": ["Helvetica"]
}

⚠️ 注意：JSON 文件内容必须是合法 JSON 对象（以 { 开头），否则启动日志会给出 WARNING，且浏览器端整个 PreConfig.js 加载失败、所有配置失效——实测复现与排障见。

九、等价 docker run 参考

本编排等价于一条 docker run 命令（调试/临时验证用，生产建议 compose）：

docker run -d \
  --name drawio-32.5.5-app \
  --restart unless-stopped \
  -p 8139:8080 \
  -p 8150:8443 \
  jgraph/drawio:32.5.5

官方 README 的最小试跑形态（临时、退出即删）：

docker run -it --rm --name="draw" -p 8080:8080 -p 8443:8443 jgraph/drawio

十、常用运维命令

均在 /opt/drawio 目录下执行，回显实测：

cd /opt/drawio
docker compose ps                 # 状态（含健康检查结果）
docker compose logs --tail 20     # 最近 20 行日志
docker compose restart            # 重启服务
docker compose down               # 停止并移除（无数据卷，无数据风险）
docker compose up -d              # 启动/重建

docker compose logs --tail 3 实测回显（启动完成的标志是 8443 协议器启动与 Server startup 行）：

drawio-32.5.5-app  | 21-Oct-2026 19:36:12.718 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-8080"]
drawio-32.5.5-app  | 21-Oct-2026 19:36:12.724 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["https-openssl-nio-8443"]
drawio-32.5.5-app  | 21-Oct-2026 19:36:12.726 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [393] milliseconds

重启韧性实测（restart 后服务自动恢复）：

$ docker compose restart && sleep 8 && docker compose ps --format "table {{.Name}}\t{{.Status}}" && curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128:8139/
 Container drawio-32.5.5-app Restarting
 Container drawio-32.5.5-app Started
NAME                STATUS
drawio-32.5.5-app   Up 8 seconds
200

资源占用实测（空载）：

$ docker stats drawio-32.5.5-app --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}"
NAME                CPU %     MEM USAGE / LIMIT    MEM %
drawio-32.5.5-app   0.26%     242.5MiB / 31.3GiB   0.76%

十一、升级与回滚

draw.io 无数据库、无数据卷，升级就是「换镜像 tag 重建」，全程秒级、无数据迁移负担。

11.1 升级流程

cd /opt/drawio
# 1. 备份编排文件
cp docker-compose.yml docker-compose.yml.bak
# 2. 修改 image tag 为新版本（如 32.5.5 → 新版本号）
sed -i 's/jgraph\/drawio:32.5.5/jgraph\/drawio:<新版本>/' docker-compose.yml
# 3. 拉取新镜像并重建
docker compose pull && docker compose up -d
# 4. 验证
docker compose ps && curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128:8139/

11.2 版本切换实测（升级/回滚同一条路径）

实测把 32.5.5 切到 32.4.1 再切回，重建即生效，首页构建标识随之变化：

$ curl -sI http://192.168.146.128:8139/ | grep -E "ETag|Last-Modified"   # 32.5.5
ETag: W/"4134-1792383932000"
Last-Modified: Mon, 19 Oct 2026 04:25:32 GMT

$ sed -i 's#jgraph/drawio:32.5.5#jgraph/drawio:32.4.1#' docker-compose.yml && docker compose up -d
 Container drawio-32.5.5-app Recreate
 Container drawio-32.5.5-app Recreated
 Container drawio-32.5.5-app Starting
 Container drawio-32.5.5-app Started

$ curl -sI http://192.168.146.128:8139/ | grep -E "ETag|Last-Modified"   # 32.4.1
ETag: W/"4134-1791779596000"
Last-Modified: Mon, 12 Oct 2026 04:33:16 GMT

切回 32.5.5（即回滚操作，同样 sed 改回 + docker compose up -d），Last-Modified 恢复为 10-19，HTTP 200。

💡 技术拓展：容器镜像的版本策略常见三种——固定精确 tag（本文采用，升级显式可控）、latest 跟随（配合 watchtower 类工具自动更新，风险是不可控变更）、digest 固定（image@sha256:...，最强可复现性但可读性差）。draw.io 发布节奏快（2026-10 单月多个稳定版），建议固定精确 tag 并按月评估升级。

十二、常见问题

Q1：浏览器打不开编辑器，curl 返回 200 正常？ 先确认访问 URL 带了参数与端口：http://<IP>:8139/?offline=1。若 curl 200 但浏览器白屏，多为浏览器版本低于官方支持矩阵（Chrome 123+/Firefox 120+/Safari 17.5+，来源官方 README），换现代浏览器验证；另确认企业代理未拦截 app.min.js（11MB 大文件）加载。

Q2：HTTPS 访问提示证书不受信任？ 默认自签证书（CN 默认 draw.example.com，有效期 3600 天），浏览器告警属预期。三选一：改证书主体变量重新生成、切 Let's Encrypt（6.2 节）、前置 Nginx 终止 TLS（6.3 节，生产推荐）。

Q3：为什么导出 PDF 菜单行为和官方在线版不一样？ 当前官方镜像已移除服务端导出服务：docker-drawio README「Removed variables」节明确 EXPORT_URL/DRAWIO_SELF_CONTAINED 失效、jgraph/export-server 停止构建（2026-10-22 查证）。浏览器端渲染的 PNG/JPEG/SVG 导出不受影响；「Export as PDF」走浏览器打印对话框。服务器端批量导出需求走第三方无头导出工具，见。

Q4：改了环境变量/配置不生效？ 配置在启动时渲染，docker compose up -d 重建才生效（restart 不重读环境变量）。验证注入结果的可靠手段：curl -s http://<IP>:8139/js/PreConfig.js，查看 window.DRAWIO_* 行是否为目标值。

Q5：服务数据会丢吗？ 服务端无状态，容器/服务重建无数据概念；用户图表在浏览器本地或已配置的外部存储（网盘/GitLab）中。提醒团队养成「文件→另存为/保存到网盘」习惯即可。

十三、卸载与清理

cd /opt/drawio
docker compose down            # 停止并移除容器与网络
docker rmi jgraph/drawio:32.5.5  # 移除镜像（可选）
rm -rf /opt/drawio             # 移除部署目录（可选）

十四、参考链接

官方容器仓库：https://github.com/jgraph/docker-drawio（README 含环境变量总表与非 root 运行说明）
官方镜像：https://hub.docker.com/r/jgraph/drawio
编辑器源码仓库：https://github.com/jgraph/drawio（Releases：https://github.com/jgraph/drawio/releases）
官方文档站：https://www.drawio.com
本文相关篇目：《draw.io 介绍与选型指南》、、