draw.io 32.5.5 常用 CLI 命令与工具详解

目标：draw.io 32.5.5 是纯 Web 应用、不自带服务器端 CLI，本文按「服务运维命令 + HTTP 探活验收 + 编辑器 URL 参数 + 无头批量导出工具」四条命令面组织：compose 服务全生命周期管理逐条实测、curl 验收命令逐条实测、官方 URL 参数精选速查、第三方无头导出工具 rlespinasse/drawio-export 的 .drawio → PNG/SVG/PDF/XML 批量导出逐格式实测。全部命令与回显真实可复现；部署背景见《draw.io 32.5.5 Docker Compose 部署指南》，配置参数见《draw.io 32.5.5 配置参数详解》，产品认知见《draw.io 介绍与选型指南》。

一、环境信息

项目	值
操作系统	Ubuntu 22.04（x86_64，IP 192.168.146.128）
draw.io 版本	32.5.5（官方最新稳定版，2026-10-18 发布）
服务端口	8139（HTTP 8080）、8150（HTTPS 8443）
编排目录	/opt/drawio/（项目名 drawio-32.5.5-stack）
Docker Compose	v5.5.1（`docker compose version` 实测）
无头导出工具	rlespinasse/drawio-export v4.60.0（2026-09-14 发布，Docker Hub tags 2026-10-22 查证）

二、工具概览

先说结论：draw.io 没有服务器端 CLI。编辑器是纯浏览器应用（绘图、渲染、导出都在浏览器端完成），服务端本质是一个由 Tomcat 承载的静态应用，官方也没有提供管理 REST API。因此运维 draw.io 的「命令面」由四部分构成：

命令面	工具	典型用途
服务运维	Docker Compose 命令（docker compose …）	启停、日志、健康检查、升级回滚
探活验收	curl	首页/静态资源/配置渲染产物/HTTPS 探测
会话级行为	编辑器 URL 参数	离线模式、语言、主题、灯箱等（官方参数清单）
批量导出	rlespinasse/drawio-export（第三方，基于无头 draw.io Desktop）	.drawio 文件批量转 PNG/SVG/PDF/XML，CI 流水线集成

💡 技术拓展：Web 应用的「命令行入口」常见三种形态——① 服务端自带 CLI（如 gitlab-rails、wp-cli）；② 管理 REST API（如 Jenkins、SonarQube）；③ 无 CLI 无 API、靠编排工具与 URL 参数驱动。draw.io 属于第三种，这是由其「编辑器在浏览器、服务端无状态」的架构决定的（详见配置篇 3.1 的固化行为表）。选择 draw.io 就选择了这个运维形态，需求是①②时应换目标软件。

三、前置条件

已按《draw.io 32.5.5 Docker Compose 部署指南》完成部署，docker compose ps 显示 healthy；
服务器已安装 Docker 与 Docker Compose v2 插件；
批量导出场景额外需要可访问 Docker Hub（导出工具以 Docker 方式交付，见第六章）。

四、服务运维命令详解（docker compose）

以下命令均在部署目录 /opt/drawio 下执行，回显全部实测。

4.1 启动与状态

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

查看状态与健康检查结果（--format 可精简输出）：

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

实测回显：

$ docker compose ps
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

$ docker compose ps --format "table {{.Name}}\t{{.Status}}"
NAME                STATUS
drawio-32.5.5-app   Up 12 seconds (healthy)

查看编排使用的镜像与占用：

docker compose images

实测回显：

CONTAINER           REPOSITORY          TAG                 PLATFORM            IMAGE ID            SIZE                CREATED
drawio-32.5.5-app   jgraph/drawio       32.5.5              linux/amd64         16296fe9fd09        1.26GB              2 days ago

4.2 日志查看

docker compose logs --tail 20        # 最近 20 行
docker compose logs -f               # 持续跟随（Ctrl+C 退出）

--tail 3 实测回显（出现 https-openssl-nio-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

配置变更排查时重点看两段：启动头部（Init PreConfig.js 渲染详情、JSON 非法 WARNING，见配置篇 5.2）与证书生成段（Generating Self-Signed certificate）。

4.3 重启、停止与完整生命周期

docker compose restart     # 重启（不重读环境变量）
docker compose down        # 停止并移除服务与网络
docker compose up -d       # 再次启动

restart 实测回显：

$ docker compose restart && sleep 8 && docker compose ps --format "table {{.Name}}\t{{.Status}}"
 Container drawio-32.5.5-app Restarting
 Container drawio-32.5.5-app Started
NAME                STATUS
drawio-32.5.5-app   Up 8 seconds

down → up 全周期实测回显（无数据卷，down 无数据风险）：

$ docker compose down
 Container drawio-32.5.5-app Stopping
 Container drawio-32.5.5-app Stopped
 Container drawio-32.5.5-app Removing
 Container drawio-32.5.5-app Removed
 Network drawio-3255-stack_drawio-net Removing
 Network drawio-3255-stack_drawio-net Removed

$ docker compose up -d
 Network drawio-3255-stack_drawio-net Creating
 Network drawio-3255-stack_drawio-net Created
 Container drawio-32.5.5-app Creating
 Container drawio-32.5.5-app Created
 Container drawio-32.5.5-app Starting
 Container drawio-32.5.5-app Started

4.4 版本切换（升级/回滚）

升级 = 改镜像 tag 重建，回滚同一条路径反向执行。实测从 32.5.5 切到 32.4.1（回滚演练同理）：

$ 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"     # 版本指纹变化
ETag: W/"4134-1791779596000"
Last-Modified: Mon, 12 Oct 2026 04:33:16 GMT

切回 32.5.5 后 Last-Modified 恢复为 Mon, 19 Oct 2026 04:25:32 GMT（HTTP 200）。首页的 ETag/Last-Modified 就是可用的版本指纹——不同 Release 构建产物时间戳不同，用它做升级后核对最直接。

五、HTTP 探活与服务验收命令（curl）

5.1 首页与响应头

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

5.2 HTTPS 自签证书探测

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

证书主体由 PUBLIC_DNS/ORGANISATION 等变量控制（实测见配置篇 5.4）。

5.3 关键静态资源与配置渲染产物验收

服务「活着」与「能用」要分开验：编辑器能跑起来的关键是三个大 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

其中 /js/viewer.min.js（6.85MB）是查看器，第三方网页嵌入 draw.io 图用的就是它（DRAWIO_VIEWER_URL 指向它，配置见配置篇 4 章）。配置生效核对接 5.4。

5.4 配置渲染产物核验（PreConfig.js / PostConfig.js）

curl -s http://192.168.146.128:8139/js/PreConfig.js | grep -E "DRAWIO_CONFIG|mxLanguage"
curl -s http://192.168.146.128:8139/js/PostConfig.js

这是所有 DRAWIO_* 配置的「生效确认口」——变量渲染结果全在这两个文件里（完整基线回显与逐项含义见配置篇 3.1）。

5.5 子路径部署的路径验收

若按配置篇 5.1 启用了子路径（DRAWIO_SERVER_URL=…/drawio/），验收口变为：

curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128:8139/drawio/    # 200
curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128:8139/           # 404（预期）

5.6 编辑器功能验收说明

浏览器端打开 http://192.168.146.128:8139/?offline=1 后的绘图、导出 PNG/SVG/XML 均为浏览器本地行为（导出不经过服务端，见配置篇 5.7 固化行为表）。服务器视角的端到端验收即 5.1–5.5 的资源可达性检查 + 浏览器人工确认可新建图形并导出；需要无人值守批量导出时用第六章的无头导出工具。

六、无头批量导出工具：rlespinasse/drawio-export

6.1 定位与选型

自托管 draw.io 当前没有官方导出服务：官方 docker README「Removed variables」节明确 jgraph/export-server 已停止构建（2026-10-22 查证），服务端导出能力被移除。批量导出（如把仓库里几十个 .drawio 自动转 PNG 进文档流水线）的事实标准是社区项目 rlespinasse/drawio-export：它以无头 draw.io Desktop（Electron）为引擎，把导出命令行封装成 Docker 工具，当前版本 v4.60.0（2026-09-14 发布，Docker Hub 2026-10-22 查证），支持递归目录导出、按 git 参考增量导出。

💡 技术拓展：.drawio 是 XML 格式，为什么不能直接用 XML 解析器转图片？因为 .drawio 存的是图形拓扑与样式描述，最终位图渲染依赖 mxGraph 布局引擎——只有真实跑起 draw.io 渲染管线（浏览器或无头桌面版）才能得到与编辑器一致的输出。因此「无头引擎 + 命令封装」是批量导出的唯一正解，这也解释了导出工具镜像为何较大。

6.2 工具参数速查（--help 全量）

docker run --rm rlespinasse/drawio-export:v4.60.0 --help

实测回显：

Command Line Client To Enhance Files Export Using Draw.io Application

Usage: drawio-exporter [OPTIONS] [PATH]

Arguments:
  [PATH]  Path to the drawio files to export [default: .]

Options:
  -A, --application <path>            Draw.io Desktop Application [default: /opt/drawio/drawio]
      --drawio-desktop-headless       Enable Draw.io Desktop headless mode
  -f, --format <format>               Exported format [default: pdf] [possible values: adoc, md, jpg, pdf, png, svg, xml]
  -o, --output <folder>               Exported folder name [default: export]
      --output-mode <mode>            Output mode: 'relative' exports next to each drawio file, 'absolute' exports under a single output folder mirroring the source tree [default: relative] [possible values: relative, absolute]
      --on-changes                    Export drawio files only if it's newer than exported files
      --git-ref <reference>           Any git reference (branch, tag, commit id, ...)
      --remove-page-suffix            Remove page suffix when possible (in case of single page file)
  -b, --border <border>               Sets the border width around the diagram [default: 0]
  -s, --scale <scale>                 Scales the diagram size
      --enable-plugins                Enable Plugins
      --width <width>                 Fits the generated image/pdf into the specified width, preserves aspect ratio
      --height <height>               Fits the generated image/pdf into the specified height, preserves aspect ratio
      --crop                          crops PDF to diagram size
  -a, --all-pages                     export all pages (for PDF format only)
  -t, --transparent                   Set transparent background for PNG
  -q, --quality <quality>             Output image quality for JPEG [default: 90]
  -u, --uncompressed                  Uncompressed XML output
      --embed-svg-fonts <true|false>  Embed Fonts in SVG file [default: true] [possible values: true, false]
      --embed-svg-images              Embed Images in SVG file
      --svg-theme <theme>             Theme of the exported SVG image [default: light] [possible values: dark, light]
      --svg-links-target <target>     Target of links in the exported SVG image [default: auto] [possible values: auto, new-win, same-win]
  -e, --embed-diagram                 Includes a copy of the diagram for PDF, PNG, or SVG
      --tui                           Enable TUI progress display instead of plain text output (experimental)
  -h, --help                          Print help
  -V, --version                       Print version

工具自身版本（--version 实测）：

drawio-exporter 1.6.0

关键默认值速记：格式默认 pdf、输出目录默认 export、JPEG 质量默认 90、SVG 字体内嵌默认 true、SVG 主题默认 light、PDF 裁剪默认关闭。

6.3 逐格式导出实测

准备一个多图形示例文件 demo.drawio（mxfile XML，含两个节点与一条连线），与导出命令同目录挂载执行。工具以 Docker 方式交付（用法源自其官方 README：挂载 /data 执行）：

PNG（2 倍缩放）：

docker run --rm -v /opt/drawio-export:/data rlespinasse/drawio-export:v4.60.0 -f png -s 2

实测回显：

+ export file : demo.drawio
- export page 1 : Page-1
\ generate png file

SVG：

docker run --rm -v /opt/drawio-export:/data rlespinasse/drawio-export:v4.60.0 -f svg

实测回显：

+ export file : demo.drawio
- export page 1 : Page-1
\ generate svg file

XML（未压缩原文）：

docker run --rm -v /opt/drawio-export:/data rlespinasse/drawio-export:v4.60.0 -f xml -u

实测回显：

+ export file : demo.drawio
- export all pages
\ generate xml file

PDF（裁剪到图形尺寸）：

docker run --rm -v /opt/drawio-export:/data rlespinasse/drawio-export:v4.60.0 -f pdf --crop

实测回显：

+ export file : demo.drawio
- export page 1 : Page-1
\ generate pdf file

产物核验（file 实测，文件名带页名后缀 demo-Page-1.*）：

$ file export/*
export/demo-Page-1.pdf: PDF document, version 1.7, 1 pages
export/demo-Page-1.png: PNG image data, 725 x 125, 8-bit/color RGB, non-interlaced
export/demo-Page-1.svg: SVG Scalable Vector Graphics image
export/demo.xml:        Unicode text, UTF-8 text

💡 说明：PNG 尺寸 725×125 即 -s 2 缩放后的实际像素（原图约 362×62 图形边界），导出结果与编辑器内「导出为」一致；-t 可得透明底 PNG，--remove-page-suffix 可在单页文件时去掉 -Page-1 后缀。

6.4 常用参数组合

场景	命令要点
文档流水线增量导出	`--on-changes`（只导比产物新的文件），配合 git 仓库可用 `--git-ref`
高清位图	`-f png -s 3`；透明底加 `-t`
论文/打印 PDF	`-f pdf --crop`（裁掉页边空白）；多页文件加 `-a` 全页导出
网页嵌入 SVG	`-f svg --embed-svg-fonts false`（减小体积）；暗色主题 `--svg-theme dark`
回收可编辑源	`-f xml -u`（未压缩 XML，便于 diff 与再编辑）

七、注意事项

配置变更一律「重建」而非重启：docker compose restart 不重读环境变量，改配置后用 docker compose up -d；生效确认用 5.4 的 PreConfig.js 核对；
导出链路分工：浏览器端导出（人工、单文件）与无头批量导出（CI、多文件）是两条链路，自托管服务端自身不参与任何导出计算——评估批量需求时把算力预算放在跑导出工具的机器上；
drawio-export 与 draw.io 版本解耦：导出工具内置自己的 draw.io Desktop 引擎，导出效果以工具版本为准，与服务器上运行的 32.5.5 无版本绑定关系；
URL 参数只影响当次会话：?offline=1 等不落库不生效到服务端配置，想要持久默认值用 DRAWIO_CONFIG（配置篇 5.2）；
/proxy 端点保持关闭：仅嵌入外链图片场景才需要 ENABLE_DRAWIO_PROXY=1（配置篇 5.6），避免引入 SSRF 面。

八、常见问题

Q1：draw.io 有没有类似 drawio-server --status 的管理命令？ 没有。服务端无 CLI 也无管理 API（工具概览表），服务状态一律走 docker compose ps + curl 探活（第五章）。

Q2：为什么导出 PDF 时没有「包含图形副本」选项？ 官方镜像已移除服务端导出（EXPORT_URL=null），PDF 走浏览器打印对话框，该选项只对内嵌副本的服务端导出有意义。需要带副本的 PDF/PNG/SVG 用第六章无头导出工具的 -e（--embed-diagram）。

Q3：draw.io Desktop 也能命令行导出吗？ 能——桌面版（Windows/macOS/Linux，get.diagrams.net 下载）支持 -x 导出参数，无头导出工具正是基于它的 Linux 无头运行封装。Linux 桌面机单机批量转换可直接用桌面版 CLI；服务器无人值守场景用第六章的 Docker 交付形态更省事。

Q4：批量导出中文标签出现方块/乱码？ 无头引擎依赖宿主字体渲染，默认仅含基础字体集。两条路：换用带所需字体包的基础镜像（rlespinasse/docker-drawio-desktop-headless 提供字体扩展能力），或在 .drawio 中改用导出工具已内置的字体。

Q5：docker compose ps 一直 unhealthy？ healthcheck 探测的是应用 8080 首页（部署篇编排文件），先 docker compose logs --tail 50 看启动是否报错（证书生成失败/JSON 非法告警都会拖慢或卡住启动），再进 5.1/5.3 逐项 curl 定位。

九、参考链接

官方 Docker 打包仓库（环境变量与运维口径）：https://github.com/jgraph/docker-drawio
官方 URL 参数清单：https://www.drawio.com/doc/faq/supported-url-parameters
draw.io Desktop 下载：https://get.diagrams.net
无头导出工具：https://github.com/rlespinasse/drawio-export（镜像：https://hub.docker.com/r/rlespinasse/drawio-export）
导出工具无头基座：https://github.com/rlespinasse/docker-drawio-desktop-headless
本文相关篇目：《draw.io 介绍与选型指南》、《draw.io 32.5.5 Docker Compose 部署指南》、《draw.io 32.5.5 配置参数详解》