drawDB v1.8.2 Ubuntu 22.04 安装指南

目标：在 Ubuntu 22.04 服务器上从零完成 drawDB v1.8.2（git tag v1.8.2，commit e4e696f2d2b1a17ac99ad1d062927582ff994a3c）的安装部署：安装 Node.js 20 构建环境 → 获取源码 → 安装依赖 → 构建静态资源 → nginx 托管 → 浏览器访问验证 → 卸载清理。已在 Ubuntu 22.04.5 LTS（x86_64）环境全程实测通过。

一、环境信息

本文所有命令与回显均在以下环境实测采集：

• 操作系统：Ubuntu 22.04.5 LTS（PRETTY_NAME="Ubuntu 22.04.5 LTS"），x86_64
• drawDB：v1.8.2（git tag，commit e4e696f2d2b1a17ac99ad1d062927582ff994a3c，2026-09-29）
• Node.js：v20.20.2（NodeSource 仓库安装），npm 10.8.2
• nginx：1.18.0（Ubuntu 22.04 官方仓库 nginx/1.18.0-6ubuntu14.21）
• 部署路径：源码 /root/drawdb，静态资源 /var/www/drawdb，nginx 站点配置 /etc/nginx/sites-available/drawdb
• 监听端口：80（HTTP）
• 内存：构建期峰值约 2 GB（已通过 NODE_OPTIONS=--max-old-space-size=4096 预留上限 4 GB）

drawDB 是一个浏览器端数据库实体关系图（ERD）编辑器与 SQL 生成器，前端为 React + Vite 构建的纯静态单页应用（SPA），核心功能（绘图、导出 SQL、模板、反向解析）全部在浏览器内完成，服务端只需托管静态文件；可选的分享/版本功能需要另配 drawdb-server 后端（见 7.2 节）。

💡 技术拓展：ER 图（Entity-Relationship Diagram，实体关系图）工具不止 drawDB 一家，常见同类对比如下——

工具	形态	特点	适用场景
drawDB	浏览器 Web 应用	免注册、多方言 SQL 导出、SQL 反向解析、模板库，纯前端可自托管	快速建模 + 生成 DDL
MySQL Workbench	桌面客户端	MySQL 官方，正向/反向工程强，仅 MySQL 系	MySQL 深度建模
DBeaver ER	桌面客户端	连接真实库反向出图，编辑能力弱	已有库的可视化
dbdiagram.io	浏览器 Web 应用	DBML 文本驱动，协作方便，闭源 SaaS	文本化建模
PlantUML/Mermaid	文本渲染	版本库友好，无交互式编辑	文档内嵌示意图

本文选择 drawDB 的理由：开源（AGPL-3.0）、免账号、支持 6 种数据库方言导出与 SQL 反向解析，且可完全自托管离线使用。

二、前置条件

2.1 系统与网络要求

• 一台 Ubuntu 22.04 服务器，具备 sudo/root 权限；
• 2 GB 以上空闲内存（构建 Vite 项目需要，构建命令同时把 Node 堆上限调到 4 GB 以内安全）；
• 磁盘空间：依赖目录 node_modules 约 400 MB，构建产物 dist/ 约 19 MB；
• 网络：能访问 GitHub（拉源码）与 npm registry（拉依赖）。内网隔离环境请直接使用第四章「方案 B：离线构建交付」。

2.2 安装基础依赖

安装 git（拉源码）、curl/ca-certificates/gnupg（NodeSource 源配置用）、nginx（托管用）：

apt-get update

实测回显（节选末尾）：

Get:18 http://security.ubuntu.com/ubuntu jammy-security/restricted amd64 Packages [7955 kB]
Fetched 49.0 MB in 19s (2578 kB/s)
Reading package lists...

apt-get install -y curl ca-certificates gnupg git nginx

实测回显（节选末尾）：

Setting up nginx (1.18.0-6ubuntu14.21) ...
Processing triggers for man-db (2.10.2-1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...
0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

验证基础依赖就位：

git --version && nginx -v

实测回显：

git version 2.34.1
nginx version: nginx/1.18.0

三、版本选型说明

3.1 drawDB 版本对照

drawDB 的 package.json 中 version 恒为 0.0.0（private 项目，不做语义化发版），实际版本以 git tag 与 ghcr.io 镜像 tag 为准。实测 ghcr.io/drawdb-io/drawdb 全部可用 tag 如下：

关键差异：生产部署务必锁定 v1.8.2 这类正式 tag 而非 latest，保证多环境构建产物一致。核对源码版本的方法：

git -C /root/drawdb log -1 --format='%H %ci'

实测回显：

e4e696f2d2b1a17ac99ad1d062927582ff994a3c 2026-09-29 00:54:28 +0400

该 commit 即 v1.8.2 tag 指向的提交，与 ghcr.io/drawdb-io/drawdb:v1.8.2 镜像构建时间 2026-09-29T21:53:44Z 对应。

3.2 Node.js 版本选择

官方 Dockerfile 明确使用 node:20-alpine 构建，因此服务器构建环境选择 Node.js 20 LTS：

四、方案 A：NodeSource 仓库在线安装构建部署

4.1 方案说明

方案 A 是标准的在线安装路径：Ubuntu 官方仓库的 Node.js 版本过旧，通过 NodeSource 的 apt 仓库安装 Node.js 20.x，随后拉取 drawDB 源码、安装依赖、构建静态资源并交给 nginx 托管。全程需要服务器可访问公网。

4.2 安装 Node.js 20

添加 NodeSource 的 Node 20.x apt 源：

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -

实测回显（节选末尾）：

2026-10-17 02:07:58 - Repository configured successfully.
2026-10-17 02:07:58 - To install Node.js, run: apt install nodejs -y
2026-10-17 02:07:58 - You can use N|solid Runtime as a node.js alternative
2026-10-17 02:07:58 - To install N|solid Runtime, run: apt install nsolid -y

安装 Node.js：

apt-get install -y nodejs

实测回显（节选末尾）：

Setting up nodejs (20.20.2-1nodesource1) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

验证版本：

node -v && npm -v

实测回显：

v20.20.2
10.8.2

⚠️ 注意：若 apt-get install nodejs 安装的是 Ubuntu 自带的 12.x 版本（apt show nodejs 查看），说明 NodeSource 源未生效，请检查 4.2 第一步是否成功执行后再重试。

4.3 获取 drawDB 源码

克隆 v1.8.2 tag（--depth 1 只取该 tag 的最新一次提交，减少下载量）：

git clone -b v1.8.2 --depth 1 https://github.com/drawdb-io/drawdb.git /root/drawdb

实测回显（节选）：

Cloning into '/root/drawdb'...
remote: Enumerating objects: 937, done.
Turn off this advice by setting config variable advice.detachedHead to false

克隆完成后检出的是 detached HEAD（tag 本身不可变，属正常现象）。验证源码版本：

git -C /root/drawdb log -1 --format='%H %ci'

实测回显：

e4e696f2d2b1a17ac99ad1d062927582ff994a3c 2026-09-29 00:54:28 +0400

⚠️ 排障实录：直连 GitHub 时网络抖动会报以下两类错误（均为实测原文）——

fatal: unable to access 'https://github.com/drawdb-io/drawdb.git/': GnuTLS recv error (-54): Error in the pull function.
fatal: unable to access 'https://github.com/drawdb-io/drawdb.git/': Failed to connect to github.com port 443 after 21035 ms: Connection refused

处理方法：原命令直接重试即可（GnuTLS 报错多为瞬时中断）；持续连不上时改走 HTTP 代理克隆：

git -c http.proxy=http://192.168.1.62:7897 clone -b v1.8.2 --depth 1 https://github.com/drawdb-io/drawdb.git /root/drawdb

代理地址请换成自己环境实际可用的代理。若走代理出现 gnutls_handshake() failed: The TLS connection was non-properly terminated.（实测原文），说明代理链路对该域名不稳定，改回直连重试。

4.4 安装项目依赖

在源码目录执行 npm ci（严格按 package-lock.json 锁定版本安装，与官方构建流程一致）：

cd /root/drawdb && npm ci

实测回显（节选）：

npm warn deprecated inflight@1.0.6: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
npm warn deprecated rimraf@3.0.2: Rimraf versions prior to v4 are no longer supported
added 544 packages, and audited 545 packages in 10s

npm warn deprecated 为上游依赖的弃用提示，不影响构建。确认依赖目录规模：

ls /root/drawdb/node_modules | wc -l

实测回显：

469

4.5 构建静态资源

执行 Vite 生产构建。官方构建同样设置了 4 GB 的 Node 堆上限（ENV NODE_OPTIONS="--max-old-space-size=4096"），服务器内存充足时照抄即可：

cd /root/drawdb && NODE_OPTIONS=--max-old-space-size=4096 npm run build

实测回显（节选，中间为两条可忽略的构建警告）：

[plugin builtin:vite-reporter]
(!) Some chunks are larger than 500 kB after minification. Consider:
- Using dynamic import() to code-split the application
- Use build.rolldownOptions.output.codeSplitting to improve chunking: https://rolldown.rs/reference/OutputOptions.codeSplitting
- Adjust chunk size limit for this warning via build.chunkSizeWarningLimit.
✓ built in 3.03s

⚠️ 说明：构建输出中的 Use of direct eval（来自依赖 lottie-web）与 chunks are larger than 500 kB 两条是警告不是错误，官方镜像构建同样存在，可忽略。末尾 ✓ built in 3.03s 表示构建成功。

检查构建产物：

ls /root/drawdb/dist/ && du -sh /root/drawdb/dist/

实测回显：

assets
config.js
favicon.ico
hero_ss.png
index.html
robots.txt
19M     /root/drawdb/dist/

其中 index.html 为入口，assets/ 内含带内容哈希的 JS/CSS（本文实测主包为 assets/index-T7tB5J9p.js，17160378 字节；文件名哈希随构建环境可能不同），config.js 为运行时配置文件（见《drawDB v1.8.2 配置参数详解》）。

4.6 安装与配置 nginx 托管

把构建产物复制到托管目录：

mkdir -p /var/www/drawdb && cp -r /root/drawdb/dist/* /var/www/drawdb/

编写 nginx 站点配置（drawDB 是 SPA，必须配 history 路由回退）：

tee /etc/nginx/sites-available/drawdb > /dev/null <<'EOF'
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;
}
EOF
ln -sf /etc/nginx/sites-available/drawdb /etc/nginx/sites-enabled/drawdb && rm -f /etc/nginx/sites-enabled/default

💡 技术拓展：SPA 路由回退策略不止 try_files 一种，常见方案对比——

方案	原理	适用
try_files $uri /index.html	文件不存在就回退入口页	drawDB 等无服务端路由的前端（本文采用）
error_page 404 /index.html;	404 时回退	效果类似但会污染 404 状态码语义
hash 路由（/#/path）	前端改用 hash，无需回退	drawDB 用的是 history 路由，不适用

drawDB 前端使用 history 路由（/editor、/templates 等路径直接可访问），所以必须用 try_files 回退，实测不加时刷新 /editor 会 404。

检查配置并启动 nginx：

nginx -t && service nginx start

实测回显：

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

⚠️ 注意：Ubuntu 服务器上推荐用 systemd 管理：systemctl enable --now nginx。本文实测环境无 systemd，故用 service 命令，两者效果一致（service nginx start 内部同样调用 init 脚本启动守护进程）。

4.7 验证

HTTP 层验证首页与响应头：

curl -sI http://localhost/

实测回显：

HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Date: Sat, 17 Oct 2026 02:10:45 GMT
Content-Type: text/html
Content-Length: 2292
Last-Modified: Sat, 17 Oct 2026 02:10:40 GMT

验证 SPA 入口内容（标题行）：

curl -s http://localhost/ | grep -o '<title>[^<]*</title>'

实测回显：

<title>drawDB | Online database diagram editor and SQL generator</title>

验证运行时配置文件与带哈希的静态资源可访问：

curl -s http://localhost/config.js && curl -s -o /dev/null -w 'js: %{http_code} %{size_download}B\n' http://localhost/assets/index-T7tB5J9p.js

实测回显：

window.__DRAWDB_CONFIG__ = {};
js: 200 17160378B

验证 SPA 路由回退（直接访问子路径应返回入口页而非 404）：

curl -s -o /dev/null -w '/editor -> %{http_code}\n' http://localhost/editor

实测回显：

/editor -> 200

验证静态资源缓存头（7 天）：

curl -sI http://localhost/assets/index-T7tB5J9p.js | grep -iE 'cache-control|expires'

实测回显：

Expires: Sat, 24 Oct 2026 02:10:52 GMT
Cache-Control: max-age=604800
Cache-Control: public

最后用浏览器访问 http://192.168.1.231/（示例地址，换成部署服务器的实际 IP），应看到 drawDB 首页，点击「Open Editor」进入编辑器即可开始绘图。

五、方案 B：离线构建交付部署（无外网服务器）

5.1 方案说明

目标服务器无法访问 GitHub/npm 时，在一台可联网的同架构机器（x86_64，同样装好 Node.js 20）上完成源码获取、依赖安装与构建，只把最终静态产物 dist/ 打包传输到服务器托管。构建在联网机、托管在服务器，服务器零公网依赖。

⚠️ 注意：打包产物不含任何服务端程序，传输前无需在服务器上装 Node.js，只需 nginx。

5.2 联网机上构建

在联网机上按第四章 4.2～4.5 节完成 Node.js 安装、源码克隆、npm ci 与 npm run build，得到 /root/drawdb/dist/。

5.3 打包与传输

在联网机上打包 dist 并计算校验值：

cd /root/drawdb && tar -czf /tmp/drawdb-dist-v1.8.2.tar.gz -C dist . && sha256sum /tmp/drawdb-dist-v1.8.2.tar.gz

实测回显：

0cb243d9bed51770cfb4adfb3c4fb0b1fcdee06488fe52033d5837dfee6013c1  /tmp/drawdb-dist-v1.8.2.tar.gz

用 U 盘/内网文件服务把 drawdb-dist-v1.8.2.tar.gz 传到服务器（如 /tmp/）。

5.4 服务器上托管验证

服务器上解压到托管目录并校验：

mkdir -p /var/www/drawdb && tar -xzf /tmp/drawdb-dist-v1.8.2.tar.gz -C /var/www/drawdb && ls /var/www/drawdb

实测回显（离线解压实测）：

assets
config.js
favicon.ico
hero_ss.png
index.html
robots.txt

nginx 站点配置与第四章 4.6 节完全相同（root 仍指向 /var/www/drawdb）。配置后检查并重载：

nginx -t && service nginx reload

实测回显（独立 8081 端口离线站点实测）：

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.

curl -s -o /dev/null -w 'offline -> %{http_code}\n' http://localhost:8081/

实测回显：

offline -> 200

六、方案对比与选择建议

选择建议：服务器能出网就用方案 A（流程最短）；内网或需要审计构建产物的环境用方案 B。两种方案的最终产物相同（同一份 dist/），nginx 配置也完全一致。

七、配置说明

7.1 nginx 站点配置逐项

/etc/nginx/sites-available/drawdb 各指令含义：

7.2 可选：分享功能后端地址

drawDB 的「分享/版本」功能需要独立部署 drawdb-server 后端（GitHub 仓库 drawdb-io/drawdb-server）。自建后端后，把地址写入构建期环境变量 VITE_BACKEND_URL（如 export VITE_BACKEND_URL=http://192.168.1.100:5000 后重新构建），或运行期改 /var/www/drawdb/config.js：

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

不部署后端时保持默认空值，绘图、导出 SQL、模板等核心功能完全不受影响。完整参数链见《drawDB v1.8.2 配置参数详解》。

八、常见问题（FAQ）

Q1：git clone 报 GnuTLS recv error (-54) / Connection refused / gnutls_handshake() failed 怎么办？ 三类均为实测原文（见 4.3 节 ⚠️）。GnuTLS 系列多为网络瞬断，直接重试；持续 Connection refused 说明出口被墙或防火墙拦截，改用代理克隆（http://192.168.1.62:7897 为本文实测可用的代理地址，换成你环境实际可用的代理）：

git -c http.proxy=http://192.168.1.62:7897 clone -b v1.8.2 --depth 1 https://github.com/drawdb-io/drawdb.git /root/drawdb

走代理再报 TLS 中断则换回直连重试，多试几次通常可成功。

Q2：npm ci 阶段长时间卡住或报 ETIMEDOUT？ npm 默认源在国外。可临时换国内源安装（lock 文件版本不变）：npm ci --registry=https://registry.npmmirror.com。构建完成后恢复默认配置即可，产物与官方源一致。

Q3：构建时报 JavaScript heap out of memory？ 给构建命令带上堆上限（本文 4.5 节已带）：NODE_OPTIONS=--max-old-space-size=4096 npm run build。内存小于 4 GB 的服务器将该值降到 2048，并确保构建时没有其他大内存进程。

Q4：浏览器打开首页空白？ 按顺序排查：① curl -I http://localhost/assets/index-T7tB5J9p.js 是否 200（资源文件名以你实际构建产物为准，404 多是 root 路径配错）；② 浏览器控制台（F12）看是否有资源加载失败；③ 检查是否漏配 try_files 回退导致 /editor 404；④ 确认 /var/www/drawdb/config.js 存在且内容为 window.__DRAWDB_CONFIG__ = {};。

Q5：刷新 /editor 或 /templates 页面 404？ SPA 回退未生效。确认站点配置中 location / { try_files $uri /index.html; } 存在，改完执行 nginx -t && service nginx reload。

Q6：改了 config.js 不生效？ 该文件被浏览器缓存。本文 nginx 配置已对 location = /config.js 加 Cache-Control: no-store；若你的配置没有该项，加上后 nginx -t && service nginx reload，再强制刷新（Ctrl+F5）。

九、升级与多版本管理

升级到新版本 tag（下文以 vX.Y.Z 指代新版本 tag，替换为你实际要升级到的 tag 号，如 v1.8.3；当前最新以 drawDB 仓库 Releases 页为准）：

cd /root/drawdb && git fetch --tags --depth 1 && git checkout vX.Y.Z

然后重跑依赖安装与构建（lock 文件随 tag 更新）：

npm ci && NODE_OPTIONS=--max-old-space-size=4096 npm run build

把新的 dist/ 覆盖到托管目录（旧文件中带哈希的 assets 可一并清理）：

rm -rf /var/www/drawdb/* && cp -r /root/drawdb/dist/* /var/www/drawdb/

验证：curl -s http://localhost/ | grep -o '<title>[^<]*</title>' 应仍返回 drawDB 标题，且浏览器无控制台报错。回滚即重新 git checkout 旧 tag 并重跑构建覆盖。

多版本并存：给每个版本建独立目录（如 /var/www/drawdb-1.8.2）+ 独立 nginx server 块（不同端口或域名），互不影响。

十、卸载与清理

以下步骤在全新环境按本文流程安装后实测（Ubuntu 22.04）。

删除站点配置与静态资源：

rm -f /etc/nginx/sites-enabled/drawdb /etc/nginx/sites-available/drawdb && rm -rf /var/www/drawdb

卸载 nginx 与 Node.js（保留系统其他组件）：

apt-get purge -y nodejs nginx nginx-common

实测回显（节选）：

Removing nginx (1.18.0-6ubuntu14.21) ...
Removing nginx-core (1.18.0-6ubuntu14.21) ...
Removing libnginx-mod-http-geoip2 (1.18.0-6ubuntu14.21) ...
Removing libnginx-mod-http-image-filter (1.18.0-6ubuntu14.21) ...
Removing libnginx-mod-http-xslt-filter (1.18.0-6ubuntu14.21) ...
Removing libnginx-mod-mail (1.18.0-6ubuntu14.21) ...
Removing libnginx-mod-stream-geoip2 (1.18.0-6ubuntu14.21) ...
Removing libnginx-mod-stream (1.18.0-6ubuntu14.21) ...
Removing ucf (3.0043) ...

清理不再需要的依赖包与源码：

apt-get autoremove -y && rm -rf /root/drawdb

卸载验证（两条命令均应无输出）：

which node nginx && dpkg -l | grep -E 'nodejs|nginx '

实测回显：无任何输出（which 找不到 node 与 nginx，dpkg -l 已无相关包），卸载干净。

十一、参考链接

• drawDB 官方仓库：https://github.com/drawdb-io/drawdb
• v1.8.2 tag：https://github.com/drawdb-io/drawdb/releases/tag/v1.8.2
• 官方 Dockerfile（Node 20 + nginx 构建基线）：https://github.com/drawdb-io/drawdb/blob/main/Dockerfile
• NodeSource 安装脚本说明：https://github.com/nodesource/distributions
• 可选分享后端 drawdb-server：https://github.com/drawdb-io/drawdb-server
• 官方在线实例：https://drawdb.app/