如何快速上手ThothBlueprint:5分钟安装、运行并完成第一张数据库设计图的完整教程

原创2026-11-14 15:39:392,344 阅读

如何快速上手ThothBlueprint:5分钟安装、运行并完成第一张数据库设计图的完整教程

ThothBlueprint 是一款开源、可视化的数据库设计工具:用拖拽式画布创建数据库 Schema,支持导入现有 SQL、DBML 或 JSON 设计,一眼看清表关系,还能一键导出 SQL、DBML、JSON、SVG、PNG,并为 Laravel、TypeORM、Django 生成迁移文件。它离线优先、数据完全保存在本地浏览器中。本文将用约 5 分钟带你完成安装、运行,并画出你的第一张数据库设计图。

一、认识 ThothBlueprint:它能帮你做什么?

在动手之前,先了解它的核心能力,这样后面操作时你会更清楚"为什么要这么做":

功能 说明
🎨 可视化设计 拖拽表、列、关系线,所见即所得
📥 多格式导入 支持 MySQL / PostgreSQL / SQLite 的 DDL 和 DBML
📤 多格式导出 SQL、DBML、JSON、SVG、PNG
🚀 迁移生成 一键生成 Laravel、TypeORM、Django 迁移文件
🤖 AI 助手 支持 Gemini / OpenRouter,也可用 Ollama、LM Studio 本地模型
🔒 数据私有 离线优先,所有数据存在你自己的浏览器本地

💡 它的理念是 "Offline-first, local by default":不注册、不上传,你的数据库设计永远只属于你。

二、环境准备:安装 Node.js 20+ 与 pnpm

ThothBlueprint 是一个标准的 Vite + React 前端项目,准备工作只有两样:

  • Node.js 20 或更高版本(建议 20 LTS / 22 LTS)
  • pnpm(推荐)或 npm

验证是否安装成功,在终端执行:

node -v
pnpm -v

如果还没有 pnpm,可以用核心包管理器安装一次:

npm install -g pnpm

三、一键安装步骤:克隆、装依赖、启动

  1. 克隆代码仓库:
git clone https://gitcode.com/gh_mirrors/th/thoth-blueprint
cd thoth-blueprint
  1. 安装依赖:
pnpm install
  1. 启动开发服务器:
pnpm dev

看到终端输出本地地址(默认 http://localhost:5173)后,用浏览器打开,就会看到 ThothBlueprint 的图表面板首页。

⏱️ 依赖安装大约 1~2 分钟(取决于网络),启动开发服务器通常只需几秒。

完整的官方 Quick Start 说明见 README.md。

四、生产构建与 Docker 部署

如果你想在局域网或服务器上供团队使用,有两个选择:

方式一:本地构建预览

pnpm build
pnpm preview

方式二:Docker 部署

docker build -t thothblueprint .
docker run -d -p 8080:80 --name thothblueprint thothblueprint

或者直接使用 Docker Compose:

docker-compose up -d

启动后访问 http://localhost:8080 即可。相关配置见 Dockerfile 与 docker-compose.yml。

五、5 分钟完成第一张数据库设计图

下面是核心环节,跟着做,5 分钟后你就能得到一张完整的数据库设计图 🎉

第 1 步:新建一张数据库设计图

在首页点击 New Diagram 按钮,弹出创建对话框:

  • Diagram Name:给图起个名字,例如 my-shop-schema
  • Database Type:选择目标数据库类型——MySQL、PostgreSQL 或 SQLite(创建时可选,见 CreateDiagramDialog.tsx)

点击 Create,进入可视化编辑器。

ThothBlueprint 可视化数据库设计编辑器:拖拽表结构、关系线与分区画布

ThothBlueprint 编辑器全景:左侧边栏编辑列,画布上用色卡区分主外键,表与表之间用带箭头的关系线连接,并可用 Tenancy 分区和便签组织设计

第 2 步:添加表并定义列

  • 从左侧边栏拖出表组件,或在画布右键新建表
  • 点击表即可在侧边栏编辑列:列名、数据类型(BIGINT、VARCHAR、BOOLEAN、TIMESTAMP 等)、是否主键 / 唯一 / 索引

也可以直接用快捷键 Ctrl/Cmd + A 快速加表。

第 3 步:拖动连线,创建表关系

选中一张表的外键列,拖拽到目标表的主键列松手,一条带箭头的关系线就建立了。一眼就能看出"哪些表依赖谁",这是纯写 SQL 做不到的直观体验。

第 4 步:用分区和便签组织设计

  • Zones(分区):把相关的表圈进同一分区(如"Tenancy"、"User System"),支持锁定/解锁防止误改
  • Notes(便签):给设计决策留注释,例如"软删除统一用 deleted_at"

第 5 步:导出你的设计成果

通过导出功能,可以生成:

  • SQL / DBML / JSON:用于交接与版本管理
  • SVG / PNG:用于文档与汇报
  • 框架迁移文件:Laravel、TypeORM、Django 的 migration 源码

官方对整套使用流程的说明见 README.md,导出实现位于 src/lib/exporter/sql-dbml-json-exporter.ts,迁移生成器分别在 src/lib/codegen/laravel/、src/lib/codegen/typeorm/ 和 src/lib/codegen/django/。

六、进阶体验:DBML 编辑器与 AI Schema 助手

左侧:DBML 代码双向同步

编辑器下方有 DBML 标签页,可以用代码方式写 DBML,并与画布实时同步——改代码,图上变;改图,代码跟着变。解析实现见 src/lib/importer/dbml-parser.ts。

右侧:AI 助手帮你改表结构

打开右下角的 Schema Assistant,用自己的 Gemini 或 OpenRouter Key(也可连接本地 Ollama / LM Studio 模型,无需 Key)。你可以直接说"帮我给 forums 表加一个 is_active 列",AI 会生成结构化补丁、校验后原子提交到画布。相关代码见 src/lib/ai/diagramAssistantInstruction.ts 与 src/lib/ai/diagramPatchSchema.ts。

ThothBlueprint 数据库设计图:左侧 DBML 代码编辑,右侧 AI Schema 助手面板

深色主题下的 ThothBlueprint:左侧 DBML 标签页同步显示表结构代码,右侧 Schema Assistant 面板正通过对话修改表结构

七、常用快捷键速查表

熟练使用快捷键后,建图速度会快一倍(macOS 上 Ctrl 换成 Cmd):

操作 快捷键 操作 快捷键
添加表 Ctrl/Cmd + A 切换侧边栏 Ctrl/Cmd + B
撤销删除表 Ctrl/Cmd + Z 复制选中项 Ctrl/Cmd + C
粘贴 Ctrl/Cmd + V 多选节点 Ctrl/Cmd + 点击
平移画布(按住) Space 删除表/便签/分区 Delete
放大 Ctrl/Cmd + = 缩小 Ctrl/Cmd + -
重置缩放 Ctrl/Cmd + 0

完整列表可在应用内 Help Center → Keyboard Shortcuts 中查看,见 README.md。

八、项目关键路径导览

想进一步阅读源码?从这几个入口开始:

总结

回到开头那句话:ThothBlueprint 让你用"思考的方式"设计数据库。5 分钟回顾一遍全流程:

  1. ✅ 安装 Node.js 20+ 与 pnpm
  2. ✅ 克隆仓库 → pnpm install → pnpm dev
  3. ✅ New Diagram 选数据库类型
  4. ✅ 拖表、加列、拉关系线、用分区整理
  5. ✅ 导出 SQL / DBML / 迁移文件

现在打开终端,画你的第一张数据库设计图吧!🚀

登录后查看全文
thoth-blueprint