ChartDB 1.20.1 Ubuntu 22.04 安装指南

在 Ubuntu 22.04 上从零源码构建并部署 ChartDB 1.20.1 数据库图表编辑器，覆盖 Node.js 24 环境、双源码获取方案、npm 构建与 nginx 托管验证，实测构建耗时 49.51 秒。

ChartDBChartDBUbuntuUbuntu 22.04Linuxnginx2026/10/17

ChartDB 1.20.1 Ubuntu 22.04 安装指南

目标：在 Ubuntu 22.04 服务器上从零完成 ChartDB 1.20.1 的源码获取、依赖安装、生产构建与 nginx 托管，构建出可对外提供服务的数据库图表编辑器站点。本文所有命令与输出均在 Ubuntu 22.04.5 LTS（x86_64）实测通过，构建耗时约 50 秒，产物体积 84MB，最终经 nginx 提供 HTTP 200 服务并验证 SPA 路由回退与 gzip 压缩生效。

一、环境信息

本文实测环境与关键信息如下，读者可按自身环境对应替换 IP 与端口（端口沿用本文取值可直接复现）：

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • ChartDB 版本：1.20.1（2026-04-07 发布，当前最新稳定版）
  • Node.js 版本：v24.22.0（构建期要求，ChartDB 使用 Vite 7 构建）
  • npm 版本：11.19.1（随 Node.js 24 捆绑）
  • Web 服务器：nginx/1.18.0 (Ubuntu)（apt 官方仓库版）
  • 源码目录：/opt/chartdb
  • 静态产物目录：/var/www/chartdb
  • 服务监听端口：8080（nginx 站点配置自定义）
  • 构建产物体积：84M（dist/ 目录）

确认系统版本的实测输出：

cat /etc/os-release | head -2

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"

二、前置条件

2.1 硬件与网络要求

ChartDB 是纯前端单页应用（React + TypeScript，Vite 构建），运行时本身不占用服务端计算资源，nginx 静态托管即可，因此对服务器要求很低：

  • CPU：1 核即可运行；构建期建议 2 核以上（Vite 构建与 TypeScript 编译并行）
  • 内存：运行 512MB 足够；构建期实测 2GB 可完成
  • 磁盘：源码与依赖约 500MB，构建产物 84MB，建议预留 2GB
  • 网络：构建期需从 npm 官方源下载 776 个包；国内网络环境如下载缓慢，可为 npm 配置代理或镜像源（见 4.3 节 ⚠️ 说明）

2.2 安装基础依赖

构建过程需要 curl（下载 Node.js 安装脚本与源码包）、git（克隆源码）、nginx（托管产物）。一条命令安装：

apt-get update -qq && apt-get install -y -qq curl ca-certificates gnupg git nginx

实测输出（节选尾行，-qq 静默模式仅显示关键进度）：

Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

验证三项核心工具版本：

nginx -v && git --version && curl --version | head -1

nginx version: nginx/1.18.0 (Ubuntu)
git version: 2.34.1
curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 zlib/1.2.11 brotli/1.0.9 zstd/1.4.8 libidn2/2.3.2 libpsl/0.21.0 libssh/0.9.6/openssl/zlib nghttp2/1.43.0 librtmp/1.43.0 librtmp/2.3 OpenLDAP/2.5.20

nginx 1.18.0 来自 Ubuntu 22.04 官方仓库，直接满足静态站点托管需求，无需额外编译安装。

三、版本选型说明

ChartDB 遵循语义化版本，当前 1.x 主线。选型前先了解版本与获取渠道的对应关系：

项目版本/取值说明
ChartDB 最新稳定版v1.20.12026-04-07 发布，GitHub tag 与 npm 源码一致
前一版本v1.20.02026-03-04 发布，新增 check 约束/GIN 索引/跨方言导出
Node.js 构建要求24.x官方构建链为 node:24-alpine，实测 v24.22.0 可用
运行时依赖无产物为纯静态文件，nginx 托管即可
镜像发布渠道ghcr.io/chartdb/chartdb官方镜像仅发布在 GitHub Container Registry

💡 技术拓展：schema 可视化工具不止 ChartDB 一家，选型时可横向对比——

工具形态数据存储核心差异
ChartDB开源自托管 Web浏览器 IndexedDB（本地）Smart Query 反向解析、AI 跨方言导出、免账号
dbdiagram.io在线 SaaS云端账号DBML 文本驱动，免费版图表数量受限
DrawSQL在线 SaaS云端团队协作面向团队协作与分享，闭源收费
DBeaver ER 视图桌面客户端直连数据库随查询实时生成，不可离线编辑分享
Navicat 模型桌面客户端本地文件商业授权，模型与逆向工程一体

本文选择 ChartDB 自托管方案，理由：开源（AGPL-3.0）、数据不出浏览器、支持 7 种数据库方言导入，且部署成本仅为一组静态文件。

版本号获取方法（避免硬编码过期版本，发布新版本时用以下命令查询最新 tag）：

git ls-remote --tags --sort=-v:refname https://github.com/chartdb/chartdb.git | head -3

实测输出：

deed63abfb2dac53b3352b8f89b08cceca296685        refs/tags/v1.20.1
8ae8bca9286c619865ab1fd010c378a2a843ef4a        refs/tags/v1.20.0
e24d260c4392b264fec12beaa5d3ff7b4665f5c4        refs/tags/v1.19.0

💡 说明：本文以实测时最新版 v1.20.1 为基准撰写，后续版本升级时将文中 v1.20.1 替换为查询到的最新 tag 即可，构建流程不变。

四、方案 A：Git 源码构建安装（推荐，可联网）

本方案通过 git 克隆官方仓库指定 tag，完整走 npm 依赖安装与生产构建流程，适合可联网的服务器，也是升级最方便的方式（后续版本只需 git fetch 切换 tag 重新构建）。

4.1 安装 Node.js 24 构建环境

Ubuntu 22.04 官方仓库的 Node.js 为 12.x，版本过低无法运行 Vite 7 构建，必须安装 Node.js 24。使用 NodeSource 官方脚本配置仓库：

curl -fsSL https://deb.nodesource.com/setup_24.x -o /tmp/nodesource_setup.sh && bash /tmp/nodesource_setup.sh

实测输出（节选配置成功后的关键提示，apt update 的标准输出在前）：

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

💡 说明：脚本会写入 NodeSource 仓库配置（/etc/apt/sources.list.d/nodesource.list）并完成 apt update，随后按提示安装即可。

安装 Node.js：

apt-get install -y nodejs

实测输出（节选关键行）：

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

验证版本：

node --version && npm --version

v24.22.0
11.19.1

4.2 克隆 ChartDB 源码

克隆 v1.20.1 tag 到 /opt/chartdb（--depth 1 只取该 tag 的单次提交，下载量约 50MB）：

git clone --depth 1 --branch v1.20.1 https://github.com/chartdb/chartdb.git /opt/chartdb

实测输出：

Cloning into '/opt/chartdb'...
remote: Enumerating objects: 972, done.
remote: Counting objects: 100% (972/972), done.
remote: Compressing objects: 100% (782/782), done.
remote: Total 972 (delta 155), reused 705 (delta 116), pack-reused 0 (from 0)
Receiving objects: 100% (972/972), 50.06 MiB | 5.26 MiB/s, done.
Resolving deltas: 100% (155/155), done.
Note: switching to 'refs/tags/v1.20.1'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

确认源码版本：

grep '"version"' /opt/chartdb/package.json

    "version": "1.20.1",

4.3 安装 npm 依赖

进入源码目录安装依赖（npm ci 与 npm install 均可，官方 Dockerfile 使用 npm ci 严格按 lock 文件安装）：

cd /opt/chartdb && npm install

实测输出（完整尾段，共安装 775 个包、审计 776 个依赖关系）：

added 775 packages in 8s

258 packages are looking for funding
  run `npm fund` for details
npm warn install-scripts 1 package has install scripts not yet covered by allowScripts:
npm warn install-scripts   esbuild@0.27.2 (postinstall: node install.js)
npm warn install-scripts
npm warn install-scripts Run `npm install-scripts ls` to review, or `npm install-scripts approve <pkg>` to allow.

💡 说明：in 8s 是依赖已有本地缓存时的耗时，全新机器首次下载约需 1～3 分钟；esbuild 的 install-scripts 警告是 npm 12 的脚本白名单提示，esbuild 为 Vite 构建必需组件，其 postinstall 安装平台二进制属正常行为，无需处理。

⚠️ 网络提示：npm 官方源在国外，国内服务器安装缓慢或超时时，配置代理后再执行：export http_proxy=http://<代理地址>:<端口> https_proxy=http://<代理地址>:<端口>；或临时使用国内镜像源 npm install --registry=https://registry.npmmirror.com。安装成功后重跑 npm install 的实测回显为 up to date, audited 776 packages in 13s，即依赖已装齐。

4.4 执行生产构建

构建命令执行 ESLint 检查、TypeScript 编译、Vite 打包三个阶段：

npm run build

实测输出（节选末段资源清单与耗时）：

dist/assets/index-BeKb5V4p.js                          66.47 kB │ gzip:  15.90 kB
dist/assets/index-D3WTWywk.js                         101.36 kB │ gzip:  28.57 kB
dist/assets/scripts-CDxmbJw9.js                       109.39 kB │ gzip:  17.28 kB
dist/assets/create-relationship-node-OY11LIFp.js      345.20 kB │ gzip: 111.45 kB
dist/assets/menu-BKgay9r_.js                          363.47 kB │ gzip:  93.17 kB
dist/assets/canvas-CAvOuv1V.js                        554.53 kB │ gzip: 170.60 kB
dist/assets/index-4Qp1uO99.js                         799.71 kB │ gzip: 213.94 kB
dist/assets/templates-data-DJMUPvFQ.js              1,604.46 kB │ gzip: 302.21 kB
dist/assets/index-CsSlt-10.js                       2,609.60 kB │ gzip: 513.50 kB
dist/assets/code-editor-DjxaV-BP.js                15,251.92 kB │ gzip: 2,787.04 kB

(!) Some chunks are larger than 500 kB after minification. Consider:
- Using dynamic import() to code-split the application
- Use build.rollupOptions.output.manualChunks to improve chunking: https://rollupjs.org/configuration-options/#output-manualchunks
- Adjust chunk size limit for this warning via build.chunkSizeWarningLimit.
✓ built in 49.51s

💡 说明：末尾的 chunk 体积警告是 Vite 对超大代码块（Monaco 代码编辑器 15MB、模板库 1.6MB）的正常提示，不影响功能，无需处理。构建产物在 dist/ 目录，共 84MB：

du -sh /opt/chartdb/dist && ls /opt/chartdb/dist

84M     /opt/chartdb/dist
50x.html
ChartDB.gif
assets
buckle-animated.gif
buckle.png
chartdb.png
config.js
favicon.ico
index.html
load-new-db-instructions.gif
robots.txt
sitemap.xml

4.5 部署产物到 Web 目录

把 dist/ 内容复制到 nginx 托管目录：

mkdir -p /var/www/chartdb && cp -r /opt/chartdb/dist/* /var/www/chartdb/

该命令无输出即成功，确认目录内容：

ls /var/www/chartdb | head -8

50x.html
ChartDB.gif
assets
buckle-animated.gif
buckle.png
chartdb.png
config.js
favicon.ico

五、方案 B：源码离线包构建安装（断网服务器）

对于无法访问 GitHub 的内网服务器，可在一台联网机器上把源码与 npm 依赖打成离线包，传输到目标服务器后直接构建，全程无需外网。构建步骤与方案 A 的 4.4～4.5 完全一致，仅源码与依赖的获取方式不同。

5.1 联网机准备源码与依赖离线包

在可访问 GitHub 与 npm 源的联网机器上，先克隆 v1.20.1 源码并安装依赖（命令与实测输出同 4.2/4.3 节），随后把源码连同 node_modules 打成一个 tar 包：

tar czf /opt/chartdb-1.20.1-with-deps.tar.gz -C /opt chartdb

确认包体积（实测 229MB，含全部 775 个依赖包）：

du -sh /opt/chartdb-1.20.1-with-deps.tar.gz

229M    /opt/chartdb-1.20.1-with-deps.tar.gz

把离线包传输到内网服务器，scp、rsync、U 盘均可（以下按 scp 演示，192.168.1.100 替换为目标服务器地址）：

scp /opt/chartdb-1.20.1-with-deps.tar.gz root@192.168.1.100:/opt/

⚠️ 注意：scp 需要目标服务器开启 sshd（22 端口）；传输耗时取决于内网带宽，229MB 的包在千兆内网约 3～5 秒完成。若目标服务器禁用 SSH 密码登录，先执行 ssh-copy-id root@192.168.1.100 分发公钥。

5.2 内网服务器解压并构建

目标服务器只需 Node.js 环境（离线安装包可从 nodesource.com 下载 deb 包传输）。解压离线包后，依赖已随包携带，直接执行构建：

tar xzf /opt/chartdb-1.20.1-with-deps.tar.gz -C /opt && cd /opt/chartdb && npm run build

构建完成后按 4.5 节部署产物、按第七节配置 nginx，输出与方案 A 完全一致（✓ built in 49.51s）。

六、方案对比与选择建议

维度方案 A：Git 克隆方案 B：Release 包
网络要求服务器需访问 GitHub + npm 源仅需一次文件传输
版本切换git fetch 后切 tag，最便捷重新下载对应版本包
源码完整性完整 git 历史（浅克隆仅当前提交）仅该 tag 快照
依赖安装服务器在线 npm install可随包离线携带 node_modules
适用场景可联网服务器、需频繁升级内网隔离、审计要求严格的离线环境

选择建议：能联网优先方案 A（升级成本最低）；内网服务器用方案 B 并随包携带依赖；两者产物完全一致。

七、nginx 托管配置

ChartDB 产物是单页应用（SPA），nginx 配置的核心是把所有未知路径回退到 index.html（前端路由接管），并对静态资源开启缓存与压缩。

7.1 编写站点配置

创建站点配置文件 /etc/nginx/sites-available/chartdb.conf：

cat > /etc/nginx/sites-available/chartdb.conf << 'EOF'
server {
    listen 8080;
    server_name _;

    root /var/www/chartdb;
    index index.html;

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

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

    location = /config.js {
        default_type application/javascript;
    }

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

配置项逐项说明：

配置项取值作用
listen8080服务监听端口，可按需改为 80 或其他
root/var/www/chartdb静态产物目录（4.5 节部署位置）
try_files$uri $uri/ /index.htmlSPA 核心：文件不存在时回退 index.html，由前端路由处理
gzip_typesjs/css/json/svg压缩类型；ChartDB 主 JS 包 gzip 后从 15MB 降到 2.8MB
location = /config.js精确匹配运行时配置入口（见《配置参数详解》篇），保持默认类型
expires 7d静态资源缓存assets 文件名带内容哈希，缓存 7 天安全

启用站点并移除默认站点（避免默认配置抢占 80 端口日志混淆）：

ln -sf /etc/nginx/sites-available/chartdb.conf /etc/nginx/sites-enabled/chartdb.conf && rm -f /etc/nginx/sites-enabled/default

7.2 语法检查与服务启动

先做配置语法检查，再启动服务：

nginx -t

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

启动 nginx 服务（Ubuntu 22.04 使用 systemd 托管，service 命令是等价的转发入口）：

systemctl enable nginx
systemctl start nginx
systemctl is-active nginx

systemctl enable nginx 在全新安装后执行会创建开机自启链接；is-active 返回 active 即服务运行中。也可用 service 命令操作，实测回显：

service nginx start
service nginx status

 * Starting nginx nginx
   ...done.

 * nginx is running

⚠️ 注意：systemctl 与 service 二选一即可，效果相同；若 8080 端口被占用，启动会失败，用 ss -tlnp | grep 8080 排查占用进程。

7.3 服务验证

请求首页确认 HTTP 200：

curl -sI http://localhost:8080/

HTTP/1.1 200 OK
Server: nginx/1.18.0 (Ubuntu)
Date: Sat, 17 Oct 2026 02:20:34 GMT
Content-Type: text/html
Content-Length: 2124
Last-Modified: Tue, 07 Apr 2026 14:47:11 GMT
Connection: keep-alive
ETag: "69d518ef-84c"
Accept-Ranges: bytes

验证 SPA 路由回退（请求一个不存在的深层路径，应返回 ChartDB 页面而非 404）：

curl -s http://localhost:8080/some/deep/route | grep -oE '<title>[^<]*</title>'

<title>ChartDB - Create & Visualize Database Schema Diagrams</title>

验证 gzip 压缩生效：

curl -sI -H "Accept-Encoding: gzip" http://localhost:8080/assets/index-4Qp1uO99.js | grep -iE "content-encoding|content-type"

Content-Type: application/javascript
Content-Encoding: gzip

三项验证全部通过后，在浏览器访问 http://<服务器IP>:8080 即可打开 ChartDB 编辑器（数据存储在浏览器本地，无需任何服务端配置）。

八、安装验证与功能自检

8.1 页面资源完整性检查

确认页面引用的关键资源都可访问（/config.js 是运行时配置入口，index.html 强引用它）：

curl -s -o /dev/null -w "%{http_code} %{content_type}\n" http://localhost:8080/config.js

200 application/javascript

8.2 产物与源码一致性

nginx 托管的文件应与构建产物一致，抽查文件数与体积：

find /var/www/chartdb -type f | wc -l && du -sh /var/www/chartdb

实测输出：

30
84M     /var/www/chartdb

九、升级与多版本管理

9.1 源码方式升级

方案 A 安装的升级流程：拉取新 tag → 重新构建 → 覆盖产物。以升级到未来 v1.21.0 为例（版本号以 git ls-remote 查询结果为准）：

cd /opt/chartdb && git fetch --depth 1 origin tag v1.21.0 && git checkout v1.21.0

随后重新安装依赖（lock 文件可能变化）并构建：

npm install && npm run build

构建完成后覆盖部署：

rm -rf /var/www/chartdb/* && cp -r /opt/chartdb/dist/* /var/www/chartdb/

💡 说明：ChartDB 的用户数据（图表、连接信息）全部存储在浏览器 IndexedDB 中，服务端产物升级不影响浏览器本地数据；升级后浏览器需强刷（Ctrl+Shift+R）加载新版本资源。

9.2 多版本并存

多版本并存通过 nginx 多站点实现：每个版本部署到独立目录（如 /var/www/chartdb-1.20.1、/var/www/chartdb-1.21.0），分别配置不同 listen 端口（如 8080、8081）即可，互不干扰。

十、常见问题（FAQ）

Q1：npm install 卡在依赖下载或报网络超时？ npm 官方源在国外。按 4.3 节 ⚠️ 提示配置代理（export http_proxy=... https_proxy=...）或换国内镜像源（--registry=https://registry.npmmirror.com）后重跑。判断是否配置生效：重跑 npm install 出现 up to date, audited 776 packages in 13s 即为已装齐。

Q2：npm run build 报 Node.js 版本错误（SyntaxError 或 engine 不兼容）？ ChartDB 1.20.1 使用 Vite 7，要求 Node.js 20.19+ / 22.12+ / 24+。Ubuntu 22.04 仓库自带 Node.js 12.x 过低，必须按 4.1 节通过 NodeSource 安装 Node.js 24。检查当前版本：node --version（实测应为 v24.22.0）。

Q3：构建成功但页面白屏？ 大概率是 nginx 未配置 SPA 回退（try_files ... /index.html），直接访问首页正常、刷新子路由 404 或白屏。核对 7.1 节配置中 location / 块后 systemctl reload nginx。

Q4：访问页面 403 Forbidden？ 检查 /var/www/chartdb 目录权限，nginx worker 用户（Ubuntu 默认 www-data）需具备读取权限：chmod -R o+r /var/www/chartdb。

Q5：/config.js 请求 404？ config.js 是构建产物的一部分（位于 dist/ 根），确认 4.5 节复制完整（cp -r dist/*）。该文件是运行时配置入口，缺失不影响主功能但 AI 能力与 Cloud 开关不生效。

Q6：构建警告 "Some chunks are larger than 500 kB" 需要处理吗？ 不需要。这是 Monaco 代码编辑器与模板数据体积的常规提示，ChartDB 官方镜像同样带着这些大块发布，功能不受影响。

十一、卸载与清理

完整卸载包含四部分：nginx 站点配置、静态产物、源码与构建缓存、Node.js（可选）。

删除 nginx 站点配置并重载：

rm -f /etc/nginx/sites-enabled/chartdb.conf /etc/nginx/sites-available/chartdb.conf && systemctl reload nginx

删除静态产物与源码：

rm -rf /var/www/chartdb /opt/chartdb

如需彻底移除 Node.js：

apt-get remove -y nodejs && rm -f /etc/apt/sources.list.d/nodesource.list

如连 nginx 一并卸载：

apt-get remove -y --purge nginx nginx-common && apt-get autoremove -y

十二、参考链接