企业官网建设流程全解析

• 数据库
• 前端
• 数据可视化
• AI 应用

ChartDB 是一个开源的、基于 Web 的数据库图表（ER Diagram）编辑器，它的核心亮点是"一次查询，即刻可视化"：在任意支持的数据库中运行一段"Smart Query"，即可把整个数据库 schema 以 JSON 形式抓取出来并粘贴进编辑器，瞬间生成可视化图表，全程不需要安装任何桌面客户端，也无需提供数据库密码。本指南将以仓库 README.md 为主线，结合源码带你掌握 ChartDB 的核心工作流（Smart Query 导入）、AI 驱动的跨方言 SQL 导出、以及本地开发、生产构建和 Docker 自托管部署的完整配置方法。

项目概览：一个面向"快速可视化与设计"的数据库图表编辑器

ChartDB 的目标用户画像非常清晰：需要快速理解现有数据库结构（文档化、团队评审）、需要把数据库从一个方言迁移到另一个方言（如 MySQL → PostgreSQL、SQLite → MariaDB）、或者需要在图形界面中微调与批注复杂表结构的开发者。从 package.json 可以看到，它基于React 18 + Vite 7 + TypeScript构建，图表画布使用@xyflow/react（React Flow），SQL 编辑与高亮使用 Monaco Editor，内置i18next支持 20 多种语言，并集成ai/@ai-sdk/openaiSDK 用于 AI 导出能力。

README 将它的三大核心能力概括为：

1. Instant Schema Import（即时 schema 导入）：在数据库中运行一条查询，即可将整个 schema 以 JSON 形式瞬间抓取回来，用于文档化、团队讨论或理解数据；
2. AI-Powered Export（AI 驱动导出）：借助 LLM 生成目标方言的 DDL 脚本，简化跨数据库迁移；
3. Interactive Editing（交互式编辑）：通过直观的编辑器对表、字段、关系进行细粒度调整与批注。

支持的数据库

README 明确列出以下数据库获得官方支持：

• ✅ PostgreSQL（含 Supabase、Timescale）
• ✅ MySQL
• ✅ SQL Server
• ✅ MariaDB
• ✅ SQLite（含 Cloudflare D1）
• ✅ CockroachDB
• ✅ ClickHouse

从源码看，支持范围比 README 列举的更宽：src/lib/databases.ts 的databaseTypeToLabelMap中共有 9 种类型（Generic、PostgreSQL、MySQL、SQL Server、MariaDB、SQLite、ClickHouse、CockroachDB、Oracle），其中Oracle 也拥有完整的 Smart Query 抓取脚本与 logo 资源（见 scripts.ts 中的oracleDBQuery），可以推断 Oracle 属于源码中已实现但 README 未列出的数据库类型。每种数据库在 src/assets 下都配有亮色/暗色两套 logo（*_logo.png/*_logo_dark.png），用于界面中区分显示。

核心工作流一：Smart Query 一键导入 Schema

这是 ChartDB 区别于传统"连接数据库读取元数据"方案的关键设计——你不需要把数据库账号、密码交给 ChartDB，而是由 ChartDB 给你一段查询脚本，你在自己的数据库客户端里执行，把返回的 JSON 结果粘贴回 ChartDB 即可。整个流程（README 的"Try it on our website"部分）是：

1. 打开 ChartDB，点击 "Go to app"；
2. 选择你正在使用的数据库类型；
3. 拿到对应的"magic query"并在你的数据库中执行；
4. 将查询返回的 JSON 结果复制粘贴到 ChartDB；
5. 开始查看与编辑图表。

底层实现：脚本注册表与动态加载

这个"magic query"并非写死的前端字符串，而是按数据库类型组织的脚本生成器。在 src/lib/data/import-metadata/scripts/scripts.ts 中，importMetadataScripts是一个以DatabaseType为键的注册表，每种数据库对应一个生成查询文本的函数：

export const importMetadataScripts: ImportMetadataScripts = { [DatabaseType.POSTGRESQL]: getPostgresQuery, [DatabaseType.MYSQL]: getMySQLQuery, [DatabaseType.SQLITE]: getSQLiteQuery, [DatabaseType.SQL_SERVER]: getSqlServerQuery, [DatabaseType.MARIADB]: () => mariaDBQuery, [DatabaseType.CLICKHOUSE]: () => clickhouseQuery, [DatabaseType.COCKROACHDB]: () => cockroachdbQuery, [DatabaseType.ORACLE]: () => oracleDBQuery, };

各个脚本生成器位于 src/lib/data/import-metadata/scripts 目录（postgres-script.ts、mysql-script.ts、sqlserver-script.ts等），通过 SQL 查询系统目录（如 information_schema 类视图）把表、字段、主键、外键、索引、Check 约束等信息一次性取出并序列化为 JSON。导入侧的元数据解析由 src/lib/data/import-metadata 完成，其子目录metadata-types/定义了完整的 JSON 元数据结构（table-info.ts、column-info.ts、foreign-key-info.ts、index-info.ts、check-constraint-info.ts等），import/下的tables.ts、fields.ts、relationships.ts、indexes.ts、dependencies.ts负责把 JSON 还原成 ChartDB 内部图表模型。

在 UI 层面，smart-query-instructions.tsx 是导入向导的核心：它会根据用户选中的databaseType与可选的databaseEdition（如 SQL Server 需要区分版本与 SSMS 客户端），动态import('@/lib/data/import-metadata/scripts/scripts')加载脚本生成器，并通过 CodeSnippet 组件展示带语法高亮的可复制代码。对于支持多种客户端的数据库（例如 PostgreSQL 的 psql、Supabase、Timescale），界面会提供DB Client 标签页切换，不同客户端生成对应的查询片段（minimizeQuery用于压缩空白以保持展示整洁，而codeToCopy保留完整可执行文本）。

核心工作流二：AI 驱动的跨方言 SQL 导出

README 强调的"AI-Powered Export"解决的是方言迁移场景：同一份图表，可以按需导出为 MySQL、PostgreSQL、SQL Server、SQLite 等任意受支持方言的 DDL。其核心实现位于 src/lib/data/sql-export/export-sql-script.ts，采用了"确定性生成 + LLM 转换"的两段式架构：

• exportBaseSQL()：完全不依赖 LLM，从图表模型确定性地产出基础 DDL——CREATE SCHEMA、CREATE TYPE ... AS ENUM（PostgreSQL 自定义类型）、CREATE SEQUENCE、CREATE TABLE（含字段类型/长度/精度、NOT NULL、UNIQUE、AUTO_INCREMENT、DEFAULT、主键与复合主键、CHECK约束、COMMENT ON）、排序后的CREATE INDEX，以及按基数规则决定外键落在哪一侧的ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY（多对多关系需要连接表，会被跳过）。
• exportSQL()：当目标方言与图表原始方言不同，且存在确定性的跨方言转换路径时优先走无 LLM 路径（如 PostgreSQL → MySQL/MariaDB 与 PostgreSQL → SQL Server，见 src/lib/data/sql-export/cross-dialect）；其余场景则调用 LLM，把exportBaseSQL生成的脚本连同generateSQLPrompt()的方言指令一起交给模型改写。

两种 AI 配置方式（不可混用）

exportSQL()在调用 LLM 前会执行validateConfiguration()（export-sql-script.ts），逻辑是：

• 若配置了自定义 endpoint + 模型名，则走自定义推理服务，不要求 OpenAI API Key；
• 若配置了OpenAI API Key，则使用 OpenAI 官方服务；
• 两者都未配置则直接抛出配置错误。

README 对此的表述是："你必须配置 Option 1（OpenAI API Key）或Option 2（自定义 endpoint 和 model name）两者之一，AI 能力才能生效，不要混用。"模型的默认值是gpt-4o-mini-2024-07-18（当未显式指定LLM_MODEL_NAME时）。LLM 转换结果还会以 schema 与 SQL 文本为键做缓存（export-sql-cache.ts），相同输入二次导出无需重复调用模型。

本地开发与生产构建

README 的"Getting Started"部分给出了最简路径。ChartDB 是标准 Vite 前端项目，无需后端服务即可运行：

npm install npm run dev

npm run dev对应vite（见 package.json 的 scripts 字段），默认启动本地开发服务器。生产构建则需先通过 lint 与 TypeScript 编译检查：

npm install npm run build

build脚本实际执行npm run lint && tsc -b && vite build，即ESLint（零警告门槛）→ TypeScript 项目编译 → Vite 产物打包三步串联。如果你的部署需要 AI 能力，README 给出的构建命令是在 build 时注入 OpenAI Key：

npm install VITE_OPENAI_API_KEY=<YOUR_OPEN_AI_KEY> npm run build

这里的VITE_前缀变量会被 Vite 在编译期写入产物，读取入口在 src/lib/env.ts：OPENAI_API_KEY对应import.meta.env.VITE_OPENAI_API_KEY，同理还有OPENAI_API_ENDPOINT、LLM_MODEL_NAME、HIDE_CHARTDB_CLOUD、DISABLE_ANALYTICS。需要说明的是：以VITE_前缀注入的变量是构建期固化进 JS 产物的，适合私有部署；而 Docker 方案（下文）额外提供了运行期注入的window.env机制。

Docker 部署：一行命令跑起来

ChartDB 官方发布 Docker 镜像，README 给出的最快方式是直接拉取运行：

docker run -e OPENAI_API_KEY=<YOUR_OPEN_AI_KEY> -p 8080:80 ghcr.io/chartdb/chartdb:latest

如果你希望本地构建自己的镜像：

docker build -t chartdb . docker run -e OPENAI_API_KEY=<YOUR_OPEN_AI_KEY> -p 8080:80 chartdb

构建完成后浏览器访问http://localhost:8080即可使用。这里有两个值得展开的细节：

1. 镜像的构建结构（多阶段）

Dockerfile 采用两阶段构建：

• builder 阶段：基于node:24-alpine，通过ARG声明VITE_OPENAI_API_KEY、VITE_OPENAI_API_ENDPOINT、VITE_LLM_MODEL_NAME、VITE_HIDE_CHARTDB_CLOUD、VITE_DISABLE_ANALYTICS五个构建参数，安装依赖（npm ci）后把参数写入.env再执行npm run build；
• production 阶段：基于nginx:stable-alpine，把构建产物复制到/usr/share/nginx/html，拷入 default.conf.template 与 entrypoint.sh，暴露 80 端口，以 entrypoint 启动。

2. 运行期环境变量：Nginx 动态注入

与构建期VITE_变量不同，docker run -e传入的同名（无 VITE_ 前缀）环境变量是在容器启动时由 entrypoint.sh 处理的：它用envsubst把 Nginx 模板里$OPENAI_API_KEY、$OPENAI_API_ENDPOINT、$LLM_MODEL_NAME、$HIDE_CHARTDB_CLOUD、$DISABLE_ANALYTICS等占位符替换成真实值，然后启动 Nginx。其中关键的机制是 default.conf.template 里的/config.js路由——它动态返回一段 JavaScript，把环境变量挂到window.env上：

window.env = { OPENAI_API_KEY: "<...>", OPENAI_API_ENDPOINT: "<...>", LLM_MODEL_NAME: "<...>", HIDE_CHARTDB_CLOUD: "<...>", DISABLE_ANALYTICS: "<...>" };

前端在 src/lib/env.ts 读取时优先取window?.env?.[key]（运行期注入），回退到import.meta.env.VITE_*（构建期注入）。同时 default.conf.template 中的try_files $uri $uri/ /index.html保证了前端路由在刷新时不会 404（SPA fallback）。仓库根目录的 public/config.js 是一个空占位文件，Docker 部署场景下实际生效的是 Nginx 动态生成的/config.js。

使用自定义推理服务器（本地 vLLM 等）

README 提供了完整的"自定义推理服务器"接入示例，适用于不想依赖 OpenAI 官方服务、希望在自托管环境中接入本地 LLM（如 vLLM、Ollama 等 OpenAI 兼容接口）的场景：

# Build docker build \ --build-arg VITE_OPENAI_API_ENDPOINT=<YOUR_ENDPOINT> \ --build-arg VITE_LLM_MODEL_NAME=<YOUR_MODEL_NAME> \ -t chartdb . # Run docker run \ -e OPENAI_API_ENDPOINT=<YOUR_ENDPOINT> \ -e LLM_MODEL_NAME=<YOUR_MODEL_NAME> \ -p 8080:80 chartdb

README 给出的本地 vLLM 服务器示例配置：

VITE_OPENAI_API_ENDPOINT=http://localhost:8000/v1 VITE_LLM_MODEL_NAME=Qwen/Qwen2.5-32B-Instruct-AWQ

结合源码中的validateConfiguration()逻辑，这条路径的生效条件是endpoint 与 model name 同时存在——满足后即走createOpenAI({ apiKey, baseUrl })的自定义 baseUrl 分支（export-sql-script.ts），此时不再强制要求 OpenAI API Key。

隐私与可观测性：Fathom Analytics 的开关

README 的隐私说明指出，ChartDB 内置了基于 Fathom Analytics 的隐私友好型分析（无 Cookie、不采集个人身份信息）。如果你不希望上报任何分析数据，有两种方式关闭：

• 运行容器时追加环境变量：-e DISABLE_ANALYTICS=true
• 构建镜像时传入构建参数：--build-arg VITE_DISABLE_ANALYTICS=true

在源码层面，src/lib/env.ts 中DISABLE_ANALYTICS同时兼容运行期window.env.DISABLE_ANALYTICS与构建期VITE_DISABLE_ANALYTICS两种来源（以'true'字符串判定）。与此类似的还有HIDE_CHARTDB_CLOUD，用于在自托管界面中隐藏指向 ChartDB 云服务的入口。

进阶：内置模板与示例

除了从零导入 schema，ChartDB 还内置了大量可直接加载的示例数据库模板，便于快速体验编辑器能力：模板数据位于 src/templates-data/templates，包含 50 个真实项目的数据库结构（如wordpress-db.ts、airbnb-db.ts、django-db.ts、pokemon-db.ts、twitter-db.ts等），对应页面实现见 src/pages/templates-page 与 src/pages/template-page；另有一组教学示例图在 src/pages/examples-page/examples-data（bike stores、dvd rental、employees 等），配套图片位于 src/assets/examples 与 src/assets/templates。

状态、社区与许可

README 声明 ChartDB 当前处于Public Beta阶段。项目欢迎社区贡献（PR 指南见 CONTRIBUTING.md，参与者行为准则见 CODE_OF_CONDUCT.md），并以GNU Affero General Public License v3.0（AGPL-3.0）开源，许可全文见 LICENSE。从 CHANGELOG.md 可以跟踪版本演进；当前仓库 package.json 标注版本为 1.20.1。

小结

ChartDB 用一条巧妙的"Smart Query"绕开了传统数据库图表工具"需要数据库直连与凭证"的痛点：抓取在用户侧完成、可视化在浏览器完成，兼顾了安全与便捷。其 SQL 导出采用"确定性引擎兜底 + LLM 方言改写增强"的设计，迁移路径可预测；部署方面同时支持npm直接构建和Docker自托管，且 AI 能力既可用 OpenAI 官方服务、也可通过自定义 endpoint 接入本地推理服务器，并提供了构建期（VITE_）与运行期（window.env）两套配置注入方式。无论你是想快速理解一个陌生库的表结构、给团队产出文档化 ER 图，还是规划一次跨方言数据库迁移，ChartDB 都提供了一条低摩擦的路径。

• 数据库
• 前端
• 数据可视化
• AI 应用