如何快速上手ThothBlueprint:5分钟安装、运行并完成第一张数据库设计图的完整教程
如何快速上手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
三、一键安装步骤:克隆、装依赖、启动
- 克隆代码仓库:
git clone https://gitcode.com/gh_mirrors/th/thoth-blueprint
cd thoth-blueprint
- 安装依赖:
pnpm install
- 启动开发服务器:
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 编辑器全景:左侧边栏编辑列,画布上用色卡区分主外键,表与表之间用带箭头的关系线连接,并可用 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 标签页同步显示表结构代码,右侧 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。
八、项目关键路径导览
想进一步阅读源码?从这几个入口开始:
- 主界面与图表面板:src/pages/Index.tsx
- 编辑器画布:src/components/DiagramEditor.tsx
- 表节点 / 关系线:src/components/TableNode.tsx、src/components/CustomEdge.tsx
- 导入解析(SQL/DBML):src/lib/importer/
- AI 助手:src/lib/ai/
- 项目文档:docs/VERSIONING.md
总结
回到开头那句话:ThothBlueprint 让你用"思考的方式"设计数据库。5 分钟回顾一遍全流程:
- ✅ 安装 Node.js 20+ 与 pnpm
- ✅ 克隆仓库 →
pnpm install→pnpm dev - ✅ New Diagram 选数据库类型
- ✅ 拖表、加列、拉关系线、用分区整理
- ✅ 导出 SQL / DBML / 迁移文件
现在打开终端,画你的第一张数据库设计图吧!🚀

