drawDB v1.8.2 配置参数详解

目标：系统梳理 drawDB v1.8.2 的全部配置面，解决"配置项分散、生效时机不明、改了不生效"的排查问题：构建期环境变量（.env / VITE_*）、运行时配置（config.js）、官方镜像环境变量与内置 nginx 模板、自托管 nginx 站点配置、URL 查询参数、设置面板默认值。所有取值链路均对照 v1.8.2 源码（commit e4e696f）核实，部署形态差异同时覆盖源码构建与 Compose 两种方式。已在 Ubuntu 22.04.5 LTS（x86_64）环境实测通过。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• drawDB 版本：v1.8.2（commit e4e696f），官方镜像 ghcr.io/drawdb-io/drawdb:v1.8.2（nginx 1.30.3 stable-alpine3.23 基础，对外端口 80，Compose 映射宿主 3000）
• 源码自托管形态：Node.js 20 构建（node:20-alpine，NODE_OPTIONS=--max-old-space-size=4096），产物部署 /var/www/drawdb，nginx 监听 80
• 配置注入环境变量：VITE_BACKEND_URL、VITE_GIST_BACKEND_URL（VITE_ 前缀）
• 运行时配置端点：/config.js（window.__DRAWDB_CONFIG__）

二、配置体系总览

drawDB 是 React + Vite 纯前端应用，配置分三层，作用时机不同：

优先级关系（实测源码核实）：运行时 config.js > 构建期 VITE_* > 硬编码默认值。也就是说，镜像部署时环境变量通过 /config.js 注入后即覆盖构建期值。

2.1 后端地址解析链（核心源码）

src/config/index.js 全文（v1.8.2 原文）：

const runtime =
  (typeof window !== "undefined" && window.__DRAWDB_CONFIG__) || {};

const trimSlash = (url) => url.replace(/\/+$/, "");

export const backendUrl = trimSlash(
  runtime.backendUrl ||
    import.meta.env.VITE_BACKEND_URL ||
    "http://localhost:5000",
);

export const gistBackendUrl = trimSlash(
  runtime.gistBackendUrl ||
    runtime.backendUrl ||
    import.meta.env.VITE_GIST_BACKEND_URL ||
    import.meta.env.VITE_BACKEND_URL ||
    "http://localhost:5000",
);

读法：

• backendUrl：window.__DRAWDB_CONFIG__.backendUrl → VITE_BACKEND_URL → 默认 http://localhost:5000；
• gistBackendUrl：window.__DRAWDB_CONFIG__.gistBackendUrl → window.__DRAWDB_CONFIG__.backendUrl → VITE_GIST_BACKEND_URL → VITE_BACKEND_URL → 默认 http://localhost:5000；
• 末尾斜杠自动去除（trimSlash）；
• 两个地址只服务于「分享」「版本记录」功能（调用 drawdb-server 的 gists 接口），不配置不影响绘图/导出/模板等核心功能。

三、构建期环境变量

3.1 变量表

⚠️ 注意：只有 VITE_ 前缀的变量会被 Vite 暴露给前端代码，其余环境变量（如 NODE_OPTIONS）仅作用于构建进程本身，不会泄漏进产物。

3.2 .env 文件

官方仓库提供 .env.sample（原文）：

VITE_BACKEND_URL=http://backend.com

用法（源码自托管方式）：

cd /root/drawdb && cp .env.sample .env

编辑 .env 填入实际后端地址（示例值，按你的 drawdb-server 实际地址填写）：

VITE_BACKEND_URL=http://192.168.1.100:5000
VITE_GIST_BACKEND_URL=http://192.168.1.100:5000

然后重新构建并部署 dist/（构建流程见《drawDB v1.8.2 Ubuntu 22.04 安装指南》4.5 节）。

💡 技术拓展：.env 的加载优先级（Vite 规范）——.env.[mode].local > .env.[mode] > .env.local > .env；构建命令 npm run build 的 mode 为 production，因此生产构建读 .env.production.local > .env.production > .env.local > .env。临时覆盖时直接用 shell 环境变量优先级最高：VITE_BACKEND_URL=http://10.0.0.5:5000 npm run build。

3.3 构建期注入 vs 运行时注入的取舍

四、运行时配置 config.js

4.1 机制

• 构建产物根目录自带 public/config.js，内容固定为：

window.__DRAWDB_CONFIG__ = {};

• index.html 第 58 行通过 <script src="/config.js"></script> 在应用启动前加载它，所以浏览器执行到应用代码时 window.__DRAWDB_CONFIG__ 已就位；
• 部署方只需替换服务器上的 /config.js 文件内容即可完成配置注入。

4.2 源码自托管：手改 config.js

编辑 /var/www/drawdb/config.js（路径按实际部署目录）：

window.__DRAWDB_CONFIG__ = { backendUrl: "http://192.168.1.100:5000" };

实测验证（本文部署实例）：

curl -s http://localhost/config.js

实测回显：

window.__DRAWDB_CONFIG__ = {};

（默认部署未配分享后端，故为空对象；填入后刷新浏览器生效，无需重启 nginx。）

nginx 侧需保证该文件不被缓存（站点配置见 6.1 节 location = /config.js 的 no-store）。

4.3 Compose 镜像部署：环境变量注入

官方镜像把 /config.js 做成了一个动态端点：实例启动时由 nginx 用环境变量渲染模板生成（机制见第五章）。部署时在 docker-compose.yml 写：

    environment:
      VITE_BACKEND_URL: "http://192.168.1.100:5000"
      VITE_GIST_BACKEND_URL: "http://192.168.1.100:5000"

实测回显（默认空值时）：

curl -s http://localhost:3000/config.js

window.__DRAWDB_CONFIG__ = { backendUrl: "", gistBackendUrl: "" };

注意环境变量名仍叫 VITE_* 只是沿用命名习惯，此时它不经过构建，仅在实例启动时由 nginx 模板渲染（envsubst）生成响应内容，修改后 docker compose up -d 重建实例生效。

五、官方镜像内置配置

5.1 Dockerfile 关键配置（v1.8.2 原文）

# Stage 1: Build the app
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
ENV NODE_OPTIONS="--max-old-space-size=4096"
RUN npm run build

# Stage 2: Setup the Nginx Server to serve the app
FROM docker.io/library/nginx:stable-alpine3.23 AS production
COPY --from=build /app/dist /usr/share/nginx/html
ENV VITE_BACKEND_URL="" VITE_GIST_BACKEND_URL=""
RUN mkdir -p /etc/nginx/templates && echo 'server { listen 80; server_name _; root /usr/share/nginx/html; location = /config.js { default_type application/javascript; add_header Cache-Control "no-store"; return 200 "window.__DRAWDB_CONFIG__ = { backendUrl: \"${VITE_BACKEND_URL}\", gistBackendUrl: \"${VITE_GIST_BACKEND_URL}\" };"; } location / { try_files $uri /index.html; } }' > /etc/nginx/templates/default.conf.template
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

要点：

5.2 镜像内置 nginx 模板（渲染前原文）

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;

    location = /config.js {
        default_type application/javascript;
        add_header Cache-Control "no-store";
        return 200 "window.__DRAWDB_CONFIG__ = { backendUrl: \"${VITE_BACKEND_URL}\", gistBackendUrl: \"${VITE_GIST_BACKEND_URL}\" };";
    }

    location / {
        try_files $uri /index.html;
    }
}

解读：

• /config.js 不读磁盘文件，而是 return 200 直接吐出由 ${VITE_BACKEND_URL}/${VITE_GIST_BACKEND_URL} 渲染后的字符串（nginx 官方镜像的 entrypoint 在启动时对 templates/*.template 做 envsubst）；
• no-store 保证浏览器每次都取最新注入值；
• try_files $uri /index.html 提供 SPA 回退，直访 /editor、/templates 均返回入口页（实测 200）。

5.3 镜像配置的验证方法

docker exec drawdb cat /etc/nginx/templates/default.conf.template

对比渲染结果（实例运行时）：

curl -s http://localhost:3000/config.js

实测回显（空值注入）：

window.__DRAWDB_CONFIG__ = { backendUrl: "", gistBackendUrl: "" };

六、自托管 nginx 站点配置

源码自托管方式需要自己写 nginx 站点配置。本文实测验证过的完整配置：

server {
    listen 80;
    server_name _;
    root /var/www/drawdb;
    index index.html;

    location / {
        try_files $uri /index.html;
    }

    location = /config.js {
        default_type application/javascript;
        add_header Cache-Control "no-store";
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 7d;
        add_header Cache-Control "public";
    }

    gzip on;
    gzip_types text/plain text/css application/javascript application/json image/svg+xml;
    gzip_min_length 1024;
}

6.1 逐项参数说明

6.2 与官方镜像配置的差异

两者对 drawDB 功能均等价；迁移方向：镜像 → 自托管时记得补缓存与 gzip，自托管 → 镜像时后端地址改走环境变量。

6.3 配置生效与检查命令

nginx -t && service nginx reload

实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
 * Reloading nginx configuration nginx
   ...done.

systemd 环境用 systemctl reload nginx，语义相同。

七、URL 查询参数

src/utils/queryConfig.js 定义了 4 个受支持的 URL 参数（实测源码），多用于把编辑器嵌入到其他系统（iframe）或分享干净视图：

组合示例：

http://192.168.1.231:3000/editor?theme=dark&hideHeader=force&hideSidebar=true

嵌入 iframe 推荐三件套 hideHeader=force&hideSidebar=true&hideToolbar=true，只保留画布。另外分享链接形态为 /editor?shareId=<分享ID>（<分享ID> 为后端返回的 gist id，如 2a1b3c4d，依赖分享后端）。

八、设置面板与 localStorage

8.1 默认值表（v1.8.2 源码 defaultSettings 原值）

8.2 存储机制

• 持久化位置：浏览器 localStorage，key 为 settings（源码 SettingsContext.jsx 第 28/46 行，JSON.stringify 整存整取）；
• 图表数据本体在 IndexedDB，与设置分离；
• 用户改动设置即写入 localStorage，跨设备不跟随（无账号体系）。

排障：设置改不动或改完乱跳时，清一次 localStorage.removeItem("settings") 后刷新即回默认值。

九、配置速查

源码自托管：

1. 构建期后端地址 → .env（VITE_BACKEND_URL）或构建命令行环境变量 → 重新 npm run build；
2. 运行期换地址 → 改 /var/www/drawdb/config.js → 刷新浏览器；
3. 站点行为（缓存/压缩/HTTPS）→ nginx 站点配置（6.1 节表）。

Compose 镜像：

1. 后端地址 → docker-compose.yml 的 environment（VITE_BACKEND_URL/VITE_GIST_BACKEND_URL）→ docker compose up -d 重建；
2. 验证注入 → curl -s http://localhost:3000/config.js；
3. 自定义 nginx 行为 → 覆盖挂载 /etc/nginx/templates/default.conf.template → 重建实例。

通用：

1. 嵌入式展示 → URL 参数（第七章表）；
2. 个人偏好 → 设置面板（第八章表）；
3. 排查配置不生效 → 按"浏览器缓存 config.js → 是否重建实例/重新加载 → envsubst 是否渲染"三步走。

十、常见问题（FAQ）

Q1：VITE_BACKEND_URL 改了环境变量但分享功能仍连 localhost:5000？ Compose 场景：环境变量改后必须 docker compose up -d 重建实例（restart 不会重渲染 envsubst 模板），并在部署机上 curl -s http://localhost:3000/config.js 确认注入值（远程验证则把 localhost 换成部署机 IP）。自托管场景：确认改的是部署目录下的 config.js（root 指向的目录），而不是源码 public/ 里的模板文件。

Q2：构建期 .env 写了值但打包后没生效？ .env 只在构建时读取，构建完再改不会影响已有 dist/；且变量必须以 VITE_ 开头。重建后可用 grep -r "192.168.1.100" /var/www/drawdb/assets/ 在产物中搜索确认地址已打进 JS。

Q3：可以同时用构建期与运行时配置吗？ 可以，运行时优先（window.__DRAWDB_CONFIG__ 有值时构建期值被覆盖）。推荐做法：构建期留空，全部走运行时注入，产物环境无关。

Q4：HTTPS 部署后混合内容报错？ 后端地址若是 http:// 会被浏览器拦截。上 HTTPS 后把 backendUrl 一并换成 https://，或在 nginx 对后端做反向代理让前后端同源。

Q5：theme 参数不生效？ URL 参数只在编辑器路由生效且取值限定 light/dark（queryConfig.js 的 isValid 校验，其余值直接忽略）。检查拼写与所在路径。

Q6：镜像内 nginx 配置在哪、能否直接改？ 运行中实例内可直接改 /etc/nginx/templates/default.conf.template 后 docker exec drawdb nginx -s reload，但实例重建会丢失；持久化做法是挂载覆盖模板文件（见《drawDB v1.8.2 Docker Compose 部署指南》第七章）。

十一、参考链接

• drawDB 源码配置模块 src/config/index.js
• 官方 Dockerfile
• Vite 环境变量规范
• drawDB 官方在线实例