ChartDB 1.20.1 进阶实战与运维

目标：面向已跑通基础导入流程的读者，覆盖三块进阶内容——多数据库方言的 Smart Query 导入差异（MySQL 8.4.11 / PostgreSQL 16.15 / MariaDB 11.8.9 三方言实测）、跨方言 SQL 导出与 AI 配置实战、日常运维（版本升级与浏览器数据备份策略）。全部实测基于同一套 4 表演示 schema（customers / products / orders / order_items，3 条外键、18 列、9 索引），三方言 JSON 输出均通过合法性校验。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• ChartDB 版本与镜像：1.20.1（ghcr.io/chartdb/chartdb:1.20.1，Docker Compose 部署）
• 应用端口：容器内 80（nginx），宿主机映射 18090（访问 http://localhost:18090）
• 依赖数据库（导入实测用）：MySQL 8.4.11、MariaDB 11.8.9、PostgreSQL 16.15（库名 demo，4 表演示 schema：customers / products / orders / order_items）
• 数据卷路径：无服务端数据卷（ChartDB 服务端零业务数据，图表存于浏览器 IndexedDB）

二、多方言导入差异实测

2.1 方言支持矩阵

ChartDB 1.20.1 支持 9 种数据库类型（源码 DatabaseType 枚举）：PostgreSQL、MySQL、SQL Server、MariaDB、SQLite、CockroachDB、ClickHouse、Oracle、Generic。各方言的导入能力实测/源码核对如下：

2.2 Smart Query 三方言输出结构对比

同一套演示 schema 在三个方言下的 Smart Query 输出对比（实测 JSON 逐项核对）：

💡 技术拓展：为什么 PG 的脚本是 MySQL 版的近两倍长（267 行 vs 141 行）？PG 的元数据分散在多个系统目录——外键在 pg_constraint、约束在 information_schema.check_constraints、枚举等自定义类型在 pg_type，且要处理 schema（PG 的表按 schema 分组，MySQL/MariaDB 的 database 即 schema）。多出的 check_constraints 与 custom_types 两段 CTE 就是为这些额外元数据服务的，导入后对应 ChartDB 画布的 CHECK 约束与 Custom Types 面板。

2.3 各方言执行要点与差异实录

MySQL 8.4.11（实测通过）

mysql -uroot -pq1w2e3r4 demo -N < mysql8-smart-query.sql > output.json

• 执行前必须选中目标库（命令行用 demo 参数，或在脚本前加 USE demo;），因为脚本里的 DATABASE() 取当前库；
• MySQL 8 的 Smart Query 不含 SET SESSION group_concat_max_len 前缀（实测脚本首行即 WITH fk_info as (）。演示库规模输出 7,909 字节完整无截断，但 GROUP_CONCAT 默认上限 group_concat_max_len = 1024，大 schema（几十列宽表、长注释）会被静默截断，稳妥做法先执行 SET SESSION group_concat_max_len = 1000000; 再跑查询。

PostgreSQL 16.15（实测通过）

psql -U postgres -d demo -tA -f pg16-smart-query.sql > output.json

• PG 按 database 隔离，psql -d demo 连哪个库就导入哪个库的当前 schema；
• 输出的 database_name 为空串（实测），导入后图表名建议手动命名区分；
• PG 脚本首行是注释 /* PostgreSQL edition */，若脚本带 Supabase/TimescaleDB 等 edition 变体，注释会标注 edition 名称（源码按 edition 生成差异查询）。

MariaDB 11.8.9（实测通过）

mariadb -uroot -pq1w2e3r4 demo -N < mariadb-smart-query.sql > output.json

• MariaDB 官方脚本自带 SET SESSION group_concat_max_len = 10000000;（实测首行），无截断之忧；
• 外键定义里 ON UPDATE RESTRICT 显式出现（MySQL 版省略默认值），导入后关系线行为一致，仅 DBML 文本略不同。

2.4 跨方言导入内容差异

演示 schema 中 orders.status 在 MySQL/MariaDB 是 ENUM('pending','paid','shipped','done')，导入后：

• MySQL/MariaDB：字段类型显示 enum，在 DBML 面板显示为 enum 定义；
• PostgreSQL 版演示 schema 用 VARCHAR(20) + 默认值替代（PG 原生 ENUM 需先 CREATE TYPE），如源库真用 PG ENUM，会通过 custom_types 键导入并出现在 Custom Types 面板。

三、SQL 导出实战

3.1 确定性导出（无 AI）

同方言导出（PostgreSQL 图表 → PostgreSQL 脚本）不经过 AI，是内置转换器直接生成，结果稳定。跨方言导出中 PostgreSQL→MySQL 与 PostgreSQL→SQL Server 有专门的确定性类型映射（源码 cross-dialect/postgresql/type-mappings.ts），例如：

• PG BIGSERIAL → MySQL BIGINT AUTO_INCREMENT
• PG NUMERIC(10,2) → MySQL DECIMAL(10,2)
• PG TIMESTAMP → MySQL DATETIME

其余跨方言组合需 AI 参与（见 3.2）。操作路径：Actions → Export SQL → 选择目标方言（带 ✨ 的为 AI 路径），同方言与确定性路径即时出结果，AI 路径等待流式生成（官方提示约 30 秒内）。

3.2 AI 导出配置实操

自建推理服务（OpenAI 兼容协议）配置示例（Compose 环境变量，详见《ChartDB 1.20.1 配置参数详解》篇）：

    environment:
      OPENAI_API_ENDPOINT: "http://192.168.1.50:8000/v1"
      LLM_MODEL_NAME: "qwen2.5-coder-32b-instruct"

判定逻辑（源码 validateConfiguration）：端点 + 模型名成对配置即可，不要求 OpenAI key；只配 key 则走 OpenAI 官方 API。两者均缺失时点击 AI 导出报 Configuration Error: Either provide an OpenAI API key or both a custom endpoint and model name。

⚠️ 注意：AI 导出把图表结构（表/列/类型）发送到配置的推理服务，内网 schema 走外部 API 前确认数据合规边界；生产迁移用 AI 生成结果后务必人工比对并在测试库试运行。

3.3 导出产物落地到文件系统

导出对话框的脚本可复制或下载为 .sql 文件；配合 JSON 导出（Actions → Export as → JSON）可实现「图表源文件 + 建表脚本」双产物归档：

project-x/
├── schema.chartdb.json    ← Actions → Export as → JSON（图表源文件，可重新导入）
├── schema-postgresql.sql  ← Export SQL → PostgreSQL
└── schema-mysql.sql       ← Export SQL → MySQL（跨方言产出）

四、版本升级实战

4.1 镜像方式升级（推荐）

Compose 部署的升级三步：改 tag → 重建 → 清理旧镜像。以升级到未来版本 1.21.0 为例（tag 号以 ghcr.io 实际发布为准）：

    image: ghcr.io/chartdb/chartdb:1.21.0

docker compose up -d

compose 自动拉取新镜像并重建服务。回滚同理：把 tag 改回 1.20.1 再 docker compose up -d。升级前后确认服务：

curl -sI http://localhost:18090/ | head -1

HTTP/1.1 200 OK

💡 说明：用户数据在浏览器 IndexedDB，服务端镜像升级/回滚均不影响浏览器本地图表；新版本前端代码变更后浏览器需强刷加载新资源。

4.2 源码方式升级

拉取新 tag 重新构建（详见《ChartDB 1.20.1 Ubuntu 22.04 安装指南》第九节）：

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

覆盖部署后 reload nginx 即可。多版本并存用 nginx 多站点（不同端口指向不同 dist 目录）做灰度对比。

4.3 升级前检查清单

• 记录当前版本（docker compose images 或产物 /assets 文件名对比）
• 通知团队导出进行中的图表（JSON 归档，见第五节）
• 查看官方 CHANGELOG（https://github.com/chartdb/chartdb/blob/main/CHANGELOG.md）确认 Breaking Changes
• 升级后抽查：新建图表 → 导入 → 导出 全链路可用

五、数据备份策略

5.1 数据存储位置（实测结论）

ChartDB 服务端零业务数据（nginx 静态托管，无后端 API、无数据库），全部数据存放在每个使用者浏览器的 IndexedDB（库名 charts，表含 diagrams / tables / fields / relationships 等）与 localStorage（界面偏好）。备份对象因此是「浏览器数据」而非「服务器数据」。

5.2 备份方案对比

推荐实践：以 JSON 导出为主备份通道（完整可逆），DBML 为辅进版本库做 diff 审查；团队约定每周/每次重大变更后归档到文件服务器。

5.3 批量备份的现状与替代

ChartDB 1.20.1 界面暂无「一键导出全部图表」入口，图表多时的批量做法：在首页数据库列表（Actions → All Databases...）逐个打开 → Export as → JSON。若需要服务器侧定时归档，可在团队成员机器上用浏览器 DevTools 协议（CDP）自动化操作导出，但复杂度高，一般规模（几十个图表）手动归档更实际。

⚠️ 注意：清理浏览器站点数据（含 IndexedDB）会永久删除该浏览器里的所有 ChartDB 图表，清理前确认已归档；隐身/无痕模式产生的图表关闭窗口即消失。

六、故障排查实录

实录 1：MySQL 大 schema 导出 JSON 被截断，导入报错 现象：Smart Query 输出 JSON 粘贴回 ChartDB 后解析失败或表字段缺失。 根因：MySQL group_concat_max_len 默认 1024，GROUP_CONCAT 拼接的列信息超限被静默截断。 处理：查询前执行 SET SESSION group_concat_max_len = 1000000;（MariaDB 官方脚本已内置，实测值 10000000）。验证：SELECT @@group_concat_max_len; 确认会话值已调大。

实录 2：Smart Query 执行返回空 JSON（tables: []） 现象：查询成功但结果无表。 根因：脚本作用域是 DATABASE()（MySQL/MariaDB）或当前 database（PG），执行时未选中目标库。 处理：命令行加库名参数（mysql -uroot -pq1w2e3r4 demo）或脚本前加 USE demo;；PG 确认 psql -d 连的库正确。

实录 3：PG 导入后图表无名称 现象：PG 导入成功但图表标题为空。 根因：PG 输出的 database_name 为空串（实测，PG 无 DATABASE() 函数）。 处理：导入后手动命名图表；多处 PG 库导入时靠命名区分。

实录 4：升级镜像后浏览器打开还是旧界面 现象：docker compose up -d 换了新 tag，页面无变化。 根因：浏览器缓存了旧版带哈希文件名的 JS/CSS 与 index.html。 处理：强刷（Ctrl+Shift+R）；若 nginx 对 index.html 配置了激进缓存，改为 location = /index.html { add_header Cache-Control "no-cache"; }。

实录 5：AI 导出长时间无响应 现象：点击带 ✨ 的导出方言后一直转圈。 根因排查顺序：① DevTools Network 看请求是否发出；② /config.js 中 OPENAI_API_ENDPOINT 是否可达（curl -s <端点>/models 测试连通性）；③ 模型名是否与服务端部署一致。 处理：内网自建端点确认防火墙放行浏览器所在网段；模型名大小写与服务端注册名完全一致。

七、参考链接

• ChartDB 官方仓库：https://github.com/chartdb/chartdb
• CHANGELOG：https://github.com/chartdb/chartdb/blob/main/CHANGELOG.md
• 相关文档：《ChartDB 1.20.1 快速入门（导入 Schema 到生成 ER 图）》《ChartDB 1.20.1 配置参数详解》《ChartDB 1.20.1 Docker Compose 部署指南》