draw.io 32.5.5 配置参数详解

目标：系统梳理 draw.io 32.5.5 官方服务端的全量配置参数——DRAWIO_* 环境变量族与编辑器配置对象 DRAWIO_CONFIG，逐项给出官方默认值与实测行为，并交付一份内网生产配置模板。本文默认值口径取自官方 docker-drawio 仓库 README 与 docker-entrypoint.sh（dev 分支，2026-10-22 查证），标注「实测」的行为均在 Ubuntu 22.04 + draw.io 32.5.5 实例上验证通过（部署过程见 《draw.io 32.5.5 Docker Compose 部署指南》）；产品定位见 《draw.io 介绍与选型指南》，运维命令见 。

一、环境信息

二、前置条件

1. 已按 《draw.io 32.5.5 Docker Compose 部署指南》完成部署且 docker compose ps 状态为 healthy；
2. 理解 draw.io 的配置渲染模型：环境变量在实例启动时由 docker-entrypoint.sh 渲染成两个 JS 文件——PreConfig.js（编辑器加载前执行：CSP、部署 URL、配置对象、集成开关）与 PostConfig.js（编辑器加载后执行：行为覆盖），改配置必须重建实例才生效；
3. 每项参数的验证手段统一为「启动日志 + curl 对应 JS 文件 + 端点行为」。

三、参数查看与修改方式

3.1 查看当前生效配置（curl 渲染产物）

这是 draw.io 独有的便利：所有环境变量的渲染结果都固化在两个可 HTTP 访问的 JS 文件里，改完配置后可直接核对：

curl -s http://192.168.146.128:8139/js/PreConfig.js
curl -s http://192.168.146.128:8139/js/PostConfig.js

基线（全部参数未配置时）实测回显——PreConfig.js：

(function() {
  try {
	    var s = document.createElement('meta');
	    s.setAttribute('content', 'default-src 'self'; script-src 'self' https://storage.googleapis.com https://apis.google.com https://docs.google.com https://code.jquery.com 'unsafe-inline'; connect-src 'self' https://*.dropboxapi.com https://api.trello.com https://api.github.com https://raw.githubusercontent.com https://*.googleapis.com https://*.googleusercontent.com https://graph.microsoft.com https://*.1drv.com https://*.sharepoint.com https://gitlab.com https://*.google.com https://fonts.gstatic.com https://fonts.googleapis.com; img-src * data:; media-src * data:; font-src * about:; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; frame-src 'self' https://*.google.com;');
	    s.setAttribute('http-equiv', 'Content-Security-Policy');
 	    var t = document.getElementsByTagName('meta')[0];
      t.parentNode.insertBefore(s, t);
  } catch (e) {} // ignore
})();
window.DRAWIO_SERVER_URL = '';
window.DRAWIO_BASE_URL = 'http://localhost:8080';
window.DRAWIO_VIEWER_URL = '';
window.DRAWIO_LIGHTBOX_URL = '';
window.DRAW_MATH_URL = 'math4/es5';
window.EXPORT_URL = null;
window.DRAWIO_CONFIG = null;
urlParams['sync'] = 'manual'; //Disable Real-Time
urlParams['db'] = '0'; //dropbox
urlParams['gh'] = '0'; //github
urlParams['tr'] = '0'; //trello
urlParams['gapi'] = '0'; //Google Drive
urlParams['od'] = '0'; //OneDrive
urlParams['gl'] = '0'; //Gitlab

基线实测回显——PostConfig.js：

window.ICONSEARCH_PATH = null;
window.ICON_SERVICE_PATH = null;
window.ICONSEARCH_PATH = null;
EditorUi.enableLogging = false; //Disable logging
App.prototype.isDriveDomain = function() { return true; }

💡 说明：基线回显里有几行没有环境变量可控的固化行为，排查「为什么功能和官方在线版不一样」时先看这里：EXPORT_URL = null（服务端导出已移除）、sync = 'manual'（实时协同关闭）、db/gh/tr = 0（Dropbox/GitHub/Trello 集成禁用）、EditorUi.enableLogging = false（服务端日志关闭）。这些是 docker-entrypoint.sh 硬编码，不受任何变量影响。

3.2 修改方式与优先级

⚠️ 注意：DRAWIO_LANG 的默认语言决策链为「URL 的 lang 参数 → 用户在编辑器里保存过的语言（localStorage）→ DRAWIO_LANG → 英语」，前两者优先于服务端配置；URL 参数与用户选择在官方 entrypoint 注释中有明确定义（2026-10-22 查证）。

四、参数总览

按分域汇总全量参数（默认值全部来自官方 docker-entrypoint.sh / README，2026-10-22 查证）：

💡 说明：官方 README 明确两组参数已移除、配置无效——EXPORT_URL 与 DRAWIO_SELF_CONTAINED（指向的官方导出服务 jgraph/export-server 已停止构建，2026-10-22 查证）。老部署清单里若还留着它们，可安全删除。

五、核心参数分类详解

5.1 部署 URL 域：DRAWIO_SERVER_URL 与子路径部署

DRAWIO_SERVER_URL 是最重要的一个参数：编辑器生成的分享链接、嵌入代码都以它为准，官方要求带尾斜杠。设为子路径形式时，entrypoint 还会同步改写 Tomcat 的 context path，应用从 /drawio/ 提供服务。

实测配置（部署清单 environment 段）：

    environment:
      DRAWIO_SERVER_URL: "http://192.168.146.128:8139/drawio/"

重建实例后启动日志实测回显：

Updating Tomcat context path to '/drawio'
window.DRAWIO_SERVER_URL = 'http://192.168.146.128:8139/drawio/';

路径行为实测：

$ curl -s -o /dev/null -w 'GET /drawio/        -> %{http_code}\n' http://192.168.146.128:8139/drawio/
GET /drawio/        -> 200
$ curl -s -o /dev/null -w 'GET /（根路径）      -> %{http_code}\n' http://192.168.146.128:8139/
GET /（根路径）      -> 404

PreConfig.js 中两个 URL 变量的渲染结果实测：

window.DRAWIO_SERVER_URL = 'http://192.168.146.128:8139/drawio/';
window.DRAWIO_BASE_URL = 'http://192.168.146.128:8139/drawio';

两条结论：① context 切到 /drawio 后根路径直接 404，访问入口变成 /drawio/；② 未显式设置的 DRAWIO_BASE_URL 自动派生为 SERVER_URL 去掉尾斜杠，与官方文档「Either may be set on its own; the other is derived from it」一致。

5.2 编辑器配置域：DRAWIO_CONFIG（JSON 配置对象）

DRAWIO_CONFIG 是编辑器行为的总开关（默认字体、开始页、AI、占位符等），值必须是合法 JSON 对象。实测注入关闭开始页 + 预设字体：

    environment:
      DRAWIO_LANG: "zh"
      DRAWIO_CONFIG: '{"defaultFonts":["Helvetica"],"showStartScreen":false}'

重建后 PreConfig.js 实测回显（两行均为目标值，注入成功）：

window.DRAWIO_CONFIG = {"defaultFonts":["Helvetica"],"showStartScreen":false};
        window.mxLanguage = 'zh'; //DRAWIO_LANG default

⚠️ 注意（排障实录）：把配置写成非法 JSON（如 '{"defaultFonts":["Helvetica"' 缺右括号）后重建，启动日志会给出带原因的告警，但值仍被原样写入 PreConfig.js——浏览器端整个脚本加载失败，所有 DRAWIO_* 配置一起失效且页面无提示。实测告警回显：

WARNING: DRAWIO_CONFIG is not valid JSON (Expecting ',' delimiter: line 1 column 29 (char 28)). If the browser cannot parse it, PreConfig.js fails to load and ALL DRAWIO_* settings are ignored.

配置项多时改用文件挂载（官方 README 推荐的 DRAWIO_CONFIG_FILE）：

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

💡 说明：compose 里 DRAWIO_CONFIG 要用 map 语法（DRAWIO_CONFIG: '{"a":1}'）；官方 README 特别警告 list 语法（- DRAWIO_CONFIG='{...}'）会把外层单引号带进值里，编辑器静默忽略（entrypoint 检测到后只打印一条剥离引号的 NOTICE）。可配置的键以官方 FAQ「configure-diagram-editor」为准（https://www.drawio.com/doc/faq/configure-diagram-editor），AI 相关的 enableAi、claudeApiKey 等也在这里配置而非独立环境变量。

5.3 编辑器配置域：DRAWIO_LANG（默认语言）

语法校验：值须匹配 ^[A-Za-z]{2,3}(-[A-Za-z]{2})?$（如 zh、en、pt-br），非法值启动日志 WARNING 且被忽略。实测 DRAWIO_LANG: "zh" 渲染出条件覆盖逻辑（见 5.2 回显第二行）——它只在「URL 无 lang 参数且用户未在编辑器里选过语言」时生效（entrypoint 注释，2026-10-22 查证）。自托管部署不会跟随浏览器语言，这也是很多人以为「语言配置不生效」的原因。

5.4 证书域：自签证书主体与口令

未配置时默认自签证书（CN=draw.example.com，有效期 3600 天，TLSv1.2，见部署篇 4.3 实测）。实测改写证书主体与口令：

    environment:
      PUBLIC_DNS: "draw.quzuo.net"
      ORGANISATION: "Quzuo Lab"
      CITY: "Hangzhou"
      STATE: "Zhejiang"
      COUNTRY_CODE: "CN"
      KEYSTORE_PASS: "q1w2e3r4"

重建后 HTTPS 探测实测回显（subject 五段全部生效，服务正常）：

$ curl -skv https://192.168.146.128:8150/ 2>&1 | grep -E 'subject|expire'
*  subject: C=CN; ST=Zhejiang; L=Hangzhou; O=Quzuo Lab; OU=Cloud Native Application; CN=draw.quzuo.net
*  expire date: Aug 29 19:35:44 2036 GMT
$ curl -sk -o /dev/null -w '%{http_code}\n' https://192.168.146.128:8150/
200

⚠️ 注意：默认 KEYSTORE_PASS 是公开写在官方 README 里的（V3ry1nS3cur3P4ssw0rd），直暴 8443 端口的部署务必修改。LETS_ENCRYPT_ENABLED=true 切换 Let's Encrypt 时需要宿主 80 端口与域名解析（standalone 验证模式），流程见部署篇第六章。

5.5 存储集成域：Google Drive / OneDrive / GitLab

三类集成共享同一模式：对应 CLIENT_ID 未设置 → 集成禁用（urlParams 置 0）；设置 → 写入凭据文件并开启。基线（未配置）的禁用回显见 3.1。以 GitLab 为例（凭据从 GitLab「Settings → Applications」创建，Redirect URI 填 https://<部署地址>/gitlab，Scopes 勾选 api、read_repository、write_repository）：

    environment:
      DRAWIO_GITLAB_ID: "your-app-id"
      DRAWIO_GITLAB_SECRET: "${DRAWIO_GITLAB_SECRET}"
      DRAWIO_GITLAB_URL: "https://gitlab.example.com"

三个官方行为要点（来源：docker-drawio README，2026-10-22 查证）：

1. DRAWIO_GITLAB_URL 必须是不带路径的基址，entrypoint 自己拼接 /oauth/token，手工带路径会打断认证；
2. 自建 GitLab（URL 不是 gitlab.com）时 entrypoint 会额外写入 Editor.enableCustomGitLabUrl = true; 到 PostConfig.js——缺了它客户端直接弹 access denied；
3. 设置 GitLab 集成后默认 CSP 的 connect-src 会自动追加该 GitLab 域名（entrypoint 分支逻辑），无需手改 CSP。

Google Drive 需 DRAWIO_GOOGLE_CLIENT_ID + _SECRET + _APP_ID（App ID 是 client_id 第一个连字符前的数字段）；OneDrive 需 DRAWIO_MSGRAPH_CLIENT_ID + _SECRET，单租户 Azure 应用再加 _TENANT_ID。

5.6 安全域：CSP、/proxy 端点与 HTTP 声明

DRAWIO_CSP_HEADER：默认值即 3.1 回显里那段长策略（script-src 限定到 Google/图床等白名单、img-src/media-src 放开、font-src 放开）。内网隔离部署可整体收紧，例如：

      DRAWIO_CSP_HEADER: "default-src 'self'; script-src 'self' 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; font-src 'self';"

⚠️ 注意：官方建议在默认策略基础上改而不是从零写（README：'start from that policy when customising'）；收紧后若启用了任何网盘集成，记得把对应域名加回 connect-src，否则前端请求被 CSP 拦截。

ENABLE_DRAWIO_PROXY=1：启用 /proxy 端点（编辑器嵌入外链图片时经服务端代理拉取）。实测对比：

$ curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128:8139/proxy    # 未启用（基线）
404
$ curl -s -o /dev/null -w '%{http_code}\n' http://192.168.146.128:8139/proxy    # ENABLE_DRAWIO_PROXY=1
400

404 → 400 的变化说明端点已激活（400 是空参数请求被拒）。该端点可被滥用为 SSRF 跳板，纯内网部署保持默认关闭。

DRAWIO_USE_HTTP=1：官方 README 标注 INSECURE，仅在明确接受 HTTP 风险（如 OAuth 令牌明文传输）的隔离网内使用。

5.7 与配置无关的固化行为（排障必读）

以下行为在 docker-entrypoint.sh 中硬编码（基线回显见 3.1），不要试图用环境变量翻转：

六、生产配置模板

适用场景：内网隔离的团队绘图平台（4GB 内存以上任意规格；无外部 OAuth 依赖；中文界面；HTTPS 由前置 Nginx 终止，本模板只开 HTTP 内网口）：

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:
      - "127.0.0.1:8139:8080"        # 只绑本机回环，由前置 Nginx 对外
    environment:
      DRAWIO_SERVER_URL: "https://drawio.example.com/"
      DRAWIO_LANG: "zh"
      DRAWIO_CONFIG: '{"showStartScreen":false,"defaultFonts":["Helvetica"]}'
      DRAWIO_CSP_HEADER: "default-src 'self'; script-src 'self' 'unsafe-inline'; connect-src 'self' https://gitlab.example.com; img-src 'self' data:; style-src 'self' 'unsafe-inline'; font-src 'self';"
      PUBLIC_DNS: "drawio.example.com"
      ORGANISATION: "Quzuo Lab"
      CITY: "Hangzhou"
      STATE: "Zhejiang"
      COUNTRY_CODE: "CN"
      KEYSTORE_PASS: "q1w2e3r4"
      DRAWIO_GITLAB_ID: "your-app-id"
      DRAWIO_GITLAB_SECRET: "${DRAWIO_GITLAB_SECRET}"
      DRAWIO_GITLAB_URL: "https://gitlab.example.com"
    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

模板要点解读：

• DRAWIO_SERVER_URL 写对外 HTTPS 域名（Nginx 之后用户实际访问的地址），分享链接才正确；
• ports 绑 127.0.0.1，应用不直接暴露；CSP 的 connect-src 放开了 GitLab 域名以配合 GitLab 存储集成；
• 证书变量虽在纯 HTTP 口下不参与服务，但保留可让 8443 备用通道的证书主体正确；
• ${DRAWIO_GITLAB_SECRET} 经 .env 文件注入（compose 同目录建 .env 并 chmod 600 .env），凭据不落清单正文；
• 内存水位实测约 240MiB（部署篇第十章），4GB 规格绰绰有余；无需任何持久卷。

七、常见问题

Q1：改了环境变量为什么没生效？ 配置是启动时渲染的：docker compose restart 不会重读 environment，必须 docker compose up -d 重建。验证生效用 3.1 节的 curl 核对法。

Q2：配置了 DRAWIO_LANG=zh 但界面还是英文？ 按 3.2 节决策链排查：URL 是否带了 lang 参数、该浏览器此前是否保存过语言选择（localStorage 的 .drawio-config）。两者优先级都高于服务端默认；换个无痕窗口验证最快。

Q3：DRAWIO_CONFIG 明明写了，编辑器里一个配置都没生效？ 大概率 JSON 非法导致浏览器端 PreConfig.js 整体加载失败（复现与告警见 5.2 排障实录）。先本地 python3 -m json.tool 校验 JSON，再看启动日志有无 WARNING，最后 curl /js/PreConfig.js 确认写入值。

Q4：子路径部署后根路径 404 是故障吗？ 不是，是 context 切换的预期行为（实测见 5.1）。入口变为 /drawio/；若 Nginx 公开路径与子路径不一致，还需按官方说明改写 Cookie path。

Q5：EXPORT_URL、DRAWIO_SELF_CONTAINED 写了没反应？ 这两个参数已在 32.5.5 时代移除（官方 README「Removed variables」节），对应导出服务 jgraph/export-server 已 EOL，从部署清单删除即可。

八、参考链接

• 官方环境变量文档（docker-drawio README）：https://github.com/jgraph/docker-drawio#environment-variables
• 配置渲染脚本（docker-entrypoint.sh）：https://github.com/jgraph/docker-drawio/blob/dev/main/docker-entrypoint.sh
• 编辑器配置项官方 FAQ：https://www.drawio.com/doc/faq/configure-diagram-editor
• AI 生成图表配置：https://www.drawio.com/doc/faq/configure-ai-options
• URL 参数官方清单：https://www.drawio.com/doc/faq/supported-url-parameters
• 本文相关篇目：《draw.io 介绍与选型指南》、《draw.io 32.5.5 Docker Compose 部署指南》、