所有文章

2026-08-16

· Dylan Yu
Cloudflare D1SQLiteedgelocal-first

从桌面管理 Cloudflare D1（不用 Dashboard）

Cloudflare D1 是边缘的 SQLite，但网页 dashboard 做日常工作太慢了。这里讲怎么在本地管理 D1 数据库——用桌面应用查询、浏览和编辑数据，零云端往返。

我用 Cloudflare D1 差不多快一年了，几个副业项目加一个生产应用。每次我需要真正看我的数据——不是跑个一次性查询然后眯着眼睛看 JSON——我都会感到沮丧。网页 dashboard 在你第一次设置数据库时还行。但当你晚上十一点在调试 schema 迁移，只想翻 200 行数据而不想每翻一页等两秒的时候，它就不行了。

一直让我头疼的是：D1 就是 SQLite。它字面意思就是 SQLite。整个卖点就是你的数据存在一个 SQLite 文件里，复制到 Cloudflare 的边缘节点。那我为什么要把它当成什么需要浏览器和祈祷的异域云数据库？

这篇是我半年前希望有人写给我的指南。我会讲清楚 D1 到底是什么，为什么 dashboard 做日常工作很糟糕，以及三种真正在本地管理 D1 数据库的方法——包括我现在实际在用的那种。

Cloudflare D1 到底是什么

先把架构搞清楚，因为这影响你怎么跟 D1 打交道。

D1 是 Cloudflare 的 serverless SQLite 数据库。存储层是 SQLite——真正的文件格式、真正的查询引擎、真正的 B-tree 存储。你创建一个 D1 数据库时，Cloudflare 会创建一个 SQLite 数据库文件并复制到他们的边缘网络。当 Worker 执行查询时，它对最近的 SQLite 文件副本执行。

计算层是 Workers。你不会像连 Postgres 那样用 TCP 连接字符串连 D1。相反，你把 D1 数据库绑定到你的 Worker，在 Worker 里调用 env.DB.prepare("SELECT * FROM users").all() 这样的方法。Worker 跑在边缘，靠近用户，D1 副本也在那。

对于 Workers 之外的临时查询，Cloudflare 给你两条路：

  1. Wrangler CLI — wrangler d1 execute 和 wrangler d1 query 从终端通过 D1 API 运行查询。
  2. D1 REST API — 一个接受 SQL 返回 JSON 的 HTTP 端点。你可以用任何能发 HTTP 请求的东西访问它。

这两个都走 Cloudflare 的 API，不是直接连 SQLite 文件。没办法对生产 D1 数据库建立原始 SQLite 文件连接——这是 serverless 的代价。但查询语义就是 SQLite 语义。你懂 SQLite 就懂 D1。

这是应该决定你工具选择的关键洞察：D1 是通过 HTTP 访问的 SQLite。 这意味着任何能跟 D1 REST API 对话的工具都能给你类似 SQLite 的体验，你所有的 SQLite 知识直接迁移。

网页 Dashboard 的问题

Cloudflare 在管理面板里有一个 D1 的网页 dashboard。你登录，导航到你的数据库，得到一个查询框和结果表。它能用。我不会假装它不存在。但对于日常数据库工作——你构建或维护应用时做的那种——它有真正的问题。

每次查询都是一次网络往返。 你输入查询，点运行，等请求到 Cloudflare 的 API、执行、返回。网络好的时候 300-500ms。酒店 wifi 更久。当你在探索数据——跑个查询、看结果、改查询、再跑——延迟很快累积。我等 dashboard 查询返回的时间比真正思考数据的时间还多。

没有真正的浏览体验。 结果表是个基础 HTML 表格。你不能拖拽重排列。你不能调整列宽。你不能水平滚动时冻结第一列。你不能点一行看展开的详情。你不能点列头排序而不用写新的 ORDER BY 子句。这些听起来是小事，但它们是"我在探索数据"和"我在跟工具较劲"的区别。

除了扁平表格没有其他视图。 如果你的 D1 数据库有一张工单表，你可能想按状态分组看 kanban 看板。如果它有产品数据，你可能想要带图片的 gallery 视图。如果它有事件数据，你可能想要带图表的 dashboard。Dashboard 一个都不给你。要么是表格，要么什么都没有。

没有 AI 集成。 我用 AI 助手——Claude、Cursor、Windsurf——帮我写和调试 SQL。用网页 dashboard，AI 工具没法看我的 schema 或查询我的数据。我得手动把 schema 定义复制到聊天里，自己跑查询，再把结果复制回去。很烦。

不能离线。 Dashboard 是个网页应用。没网就没 dashboard。我坐过足够多的航班和火车，知道这很重要。

上下文切换。 Dashboard 活在浏览器标签页里，旁边还有 47 个其他标签页。当我在编辑器里做应用时，我得切到浏览器，找到对的标签页，导航回我的数据库。这是摩擦。

Dashboard 适合创建数据库、设置绑定、一个月跑一次查询。它不是日常工具。既然 D1 是 SQLite，你不应该将就一个比过去 15 年所有桌面 SQLite 浏览器都差的网页 UI。

方案 1：Wrangler CLI

在 Workers 之外跟 D1 交互的官方方式是 Wrangler，Cloudflare 的 CLI 工具。如果你部署过 Workers，你已经有了。没有的话，用 npm 安装：

npm install -g wrangler

用你的 Cloudflare 账号认证：

wrangler login

然后列出你的 D1 数据库：

wrangler d1 list

跑一个查询：

wrangler d1 execute my-database --command "SELECT * FROM users LIMIT 10"

或者跑一个 SQL 文件：

wrangler d1 execute my-database --file ./migration.sql

还有一个交互式查询模式：

wrangler d1 query my-database

这会进入一个 REPL，你可以输入查询并看结果。

Wrangler 在它擅长的方面很好：脚本、迁移、CI/CD 流水线、快速一次性查询。我用它在部署脚本里跑迁移。它可靠、可脚本化、不碍事。

Wrangler 的短板在浏览。输出是终端里的格式化文本。跑 SELECT COUNT(*) FROM users 还行。跑 SELECT * FROM users，当 users 有 12 列而你想真正读那些值时，就很痛苦了。没法可视化翻页，没法点进一行，没法内联编辑值。你在终端里。终端不适合表格数据。

如果你的工作流是"跑个查询，看个数字，继续"，Wrangler 完美。如果你的工作流是"探索一张表，理解数据形状，找到搞坏我应用的那行奇怪数据"，Wrangler 会让你不开心。

方案 2：D1 REST API

这里就有意思了。D1 暴露了 REST API，意味着你可以用任何能发 HTTP 请求的东西查询它。这比听起来重要得多。

端点格式是：

https://api.cloudflare.com/client/v4/accounts/{account_id}/d1/database/{database_id}/query

你用 Cloudflare API token 认证（在 dashboard 的 My Profile > API Tokens 里创建，带 D1 权限）。

一个 curl 示例：

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/d1/database/$DATABASE_ID/query" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM users LIMIT 10"}'

响应是 JSON：

{
  "result": [
    {
      "results": [
        { "id": 1, "email": "alice@example.com", "name": "Alice" },
        { "id": 2, "email": "bob@example.com", "name": "Bob" }
      ],
      "success": true,
      "meta": {
        "served_by": "d1-micro",
        "duration": 0.34,
        "changes": 0,
        "last_row_id": 0,
        "rows_read": 2,
        "rows_written": 0
      }
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

这就是解锁点。因为 D1 有 REST API，任何 HTTP 客户端都能查询它。桌面应用可以查询它。脚本能查询它。AI 工具能查询它。你不限于 Wrangler 或网页 dashboard——你可以构建或使用任何能说 HTTP 的界面。

REST API 支持 Wrangler 支持的一切：SELECT、INSERT、UPDATE、DELETE、CREATE TABLE、ALTER TABLE、通过 sqlite_master 做 schema 内省，全部。它就是 HTTP 上的 SQLite。

原始 API 本身不是好的日常界面——你不想写 curl 命令来浏览表。但它是更好工具的基础。这正是我接下来要给你看的。

方案 3：本地桌面管理面板

这是我日常实际在用的方案。我不通过网页 dashboard 查询 D1，而是把本地桌面应用连到 D1 的 REST API，得到一个正经的管理面板——SQLite 多年来用 DB Browser 这类工具有的那种，但通过 API 跑在我的 D1 数据库上。

我用的工具是 BaseVolt。它是一个本地优先的桌面应用，支持 macOS 和 Windows，给任何数据库一个完整的管理面板。它支持 SQLite、PostgreSQL、MySQL 和 Cloudflare D1。我会讲 D1 的工作流，因为这是这篇文的主题，但同一个应用也处理其他数据库。

这个领域还有其他选择——TablePlus 配置对了也支持 D1，你也可以用 REST API 和 HTTP 客户端自己搭。我用 BaseVolt 因为它给我视图（kanban、gallery、dashboard）并且有用于 AI 集成的 MCP 服务器，后面会讲。但通用方法——把桌面应用连到 D1 REST API——才是关键。选适合你工作流的工具。

第 1 步：获取你的 D1 API 凭据

你需要从 Cloudflare 获取三样东西：

  1. Account ID — 在 Cloudflare dashboard 里找。登录后在 URL 里，或在账号概览页面。是个十六进制字符串。
  2. Database ID — 你要连接的特定 D1 数据库的 ID。运行 wrangler d1 list 查看你的数据库及其 ID，或在 dashboard 里你的 D1 数据库设置中找。
  3. API Token — 在 My Profile > API Tokens 创建一个 token。要访问 D1，token 至少需要"D1 Edit"权限（或只要读访问就选"D1 Read"）。范围限定到你的账号。

把这些准备好。马上要用。

第 2 步：连接 BaseVolt

打开 BaseVolt，添加新数据源。选择"Cloudflare D1"作为类型。BaseVolt 会要上面三个凭据——account ID、database ID、API token。输入，点连接。

BaseVolt 用你的 account ID 和 database ID 构造 D1 REST 端点：

https://api.cloudflare.com/client/v4/accounts/{account_id}/d1/database/{database_id}/query

并把你的 API token 作为 bearer 认证头发送。就这样。没有中间服务器——BaseVolt 从你的机器直接跟 Cloudflare 的 API 对话。你的 API token 存在本地，不发给任何第三方服务。

连接后，BaseVolt 通过查询 sqlite_master 内省你的 schema，拉取你的表列表。几秒内你就能在侧边栏看到你的表。

第 3 步：浏览表、跑查询、构建视图

这是桌面应用发挥价值的地方。连接后，你得到：

正经的表浏览器。 点一张表，在网格里看它的行。列可调整大小、可重排。点列头排序。翻页结果不用重跑查询。点一行在详情面板看所有字段。双击单元格内联编辑值。这是基础数据库工具功能，但跟网页 dashboard 比是天壤之别。

SQL 编辑器。 一个真正的编辑器，有语法高亮、表名和列名自动补全、查询历史。跑个查询，在下面看结果。用调整后再跑同一个查询，看新结果。延迟是 D1 API 往返——跟 dashboard 一样——但界面不碍事，所以你等的只是延迟，不是 UI。

视图。 这是打动我的部分。BaseVolt 让你在任何表上构建不同视图：

  • Grid 视图 — 默认，类似电子表格的表格。
  • Gallery 视图 — 每行显示为卡片，适合有图片或文件的数据。
  • Kanban 视图 — 按状态字段分组行，适合工单、任务、任何有工作流的东西。
  • Dashboard 视图 — 从你的数据构建的图表和指标，适合监控。

对于我的 D1 工单表，我有一个按状态分组的 kanban 视图。对于我的事件表，我有一个 dashboard，显示今天的事件计数和按类型的事件柱状图。这些是网页 dashboard 永远给不了的视图。在那里根本不可能。

所有这些都跑在本地。查询通过 REST API 发到 D1，但界面——网格、kanban 看板、图表——全部在你的机器上渲染。没有云 SaaS 渲染你的 UI。

第 4 步：用 MCP 服务器做 AI 辅助的 schema 工作

这是让我意外的部分。BaseVolt 有一个内置的 MCP（Model Context Protocol）服务器。MCP 是让 Claude、Cursor 和 Windsurf 等 AI 助手连接外部工具的标准。BaseVolt 的 MCP 服务器运行时，你的 AI 助手可以看到你的数据库 schema 并对它运行查询。

实际操作是这样的。我在 Cursor 里做我的应用。我想给 users 表加一个新列。我跟 Cursor 说："给 users 表加一个 last_login_at 列，并更新我 Worker 代码里的相关查询。"Cursor 连接到 BaseVolt 的 MCP 服务器后，可以：

  1. 读取我当前的 schema（它看到 users 表和所有列）。
  2. 生成 ALTER TABLE 迁移。
  3. 通过 MCP 服务器对 D1 运行它。
  4. 更新我的 Worker 代码引用新列。

我不需要把 schema 复制到聊天里。我不需要手动跑迁移再报告结果。AI 助手做整个循环，因为它通过 BaseVolt 有到我数据库的实时连接。

这也适用于调试。"为什么这个用户的账户显示为非活跃？"AI 可以查询 users 表，看相关行，检查关联表，搞清楚——全部通过 MCP 连接。这种事手动查询要花我十分钟，在一个对话里搞定。

MCP 服务器作为 BaseVolt 的一部分在本地运行。你的 AI 助手在 localhost 上连接它。没有数据通过云服务来启用 AI 集成——AI 工具跟 BaseVolt 说话，BaseVolt 跟 D1 说话，循环中唯一的云是 Cloudflare 自己。

为什么本地优先对 D1 重要

我听过一个反对意见："你的 D1 数据已经在 Cloudflare 的云里了。你的数据库工具也是云 SaaS 有什么关系？"

有关系，因为中间有什么。当你用云托管的数据库管理工具——一个连接到你 D1 数据库的网页 SaaS——你的数据流经那个 SaaS 的服务器。你的查询从你的浏览器到他们的服务器，再到 Cloudflare，再通过他们的服务器回到你的浏览器。那个中间服务器能看到你的 SQL、你的结果、你的 schema。它设计上就是个中间人。

当你用本地优先的桌面应用，你的查询从你的机器直接到 Cloudflare 的 API。没有中间服务器。看到你数据的只有你和 Cloudflare，而 Cloudflare 本来就有你的数据因为是他们的数据库。

这不仅是信任问题——也是延迟和可靠性问题。本地应用没有会宕机的服务器。它没有会被限流或 DDoS 的后端。它没有会把你锁在外的登录系统。你打开应用，它连上 D1，你工作。唯一的依赖是 Cloudflare 的 API 在运行，而这本来就是你已有的依赖。

本地优先也意味着不需要网络的部分可以离线用。BaseVolt 在本地缓存你的 schema 和最近的查询结果。如果我断网了，我还能看 schema、回顾过去的查询结果、规划下一次迁移。我不能跑新查询，但我能思考——而很多数据库工作是思考，不是查询。

原则很简单：你的数据在云里是因为它需要全球可访问。你的工具不需要在云里，把它们放那只会给你一个中间人。

对比表

这是各方案的对比。这些是我用了全部四个之后的诚实评价。

Wrangler CLID1 REST API网页 DashboardBaseVolt
安装时间5 分钟（npm 安装 + 登录）10 分钟（创建 API token）0 分钟（已在 dashboard 里）5 分钟（安装 + 输入凭据）
浏览体验差（终端文本输出）无（原始 HTTP）基础（HTML 表格，无额外功能）完整（网格、详情视图、内联编辑）
查询速度快（直接 API 调用）快（直接 API 调用）慢（往返 + UI 渲染）快（直接 API 调用，本地 UI）
离线否否否部分（schema + 缓存结果）
AI 集成无手动（复制粘贴）无内置 MCP 服务器
视图/dashboard无无无Grid、gallery、kanban、dashboard
成本免费免费免费免费层（2 个源）；Pro $99/年
最适合脚本、迁移、CI/CD自定义集成偶尔管理任务日常数据库工作

关于这个表的几点说明：

Wrangler 和 REST API 底层速度相同，因为它们都打同一个 Cloudflare API。区别在界面——Wrangler 给你终端，REST API 什么都不给你（你自己建界面）。

网页 dashboard"慢"不是因为 Cloudflare 的 API 慢，而是因为网页应用在每次 API 调用之上加了渲染开销。每页结果需要一次往返和一次完整 UI 重渲染。

BaseVolt 的查询速度跟 Wrangler 一样——它打同一个 API。区别是结果在本地 UI 里渲染，不用等网页加载。

成本那行：Wrangler、REST API 和 dashboard 都免费因为是 Cloudflare 自己的工具。BaseVolt 有免费层覆盖最多 2 个数据源——所以如果 D1 是你唯一的数据库，或你有 D1 加一个 Postgres，你永远在免费层。Pro 是 $99/年，加了跨设备同步，我用它来保持笔记本和台式机之间的查询历史和保存的视图一致。

什么时候用什么

你不用选一个就定死。我根据在做什么用所有这些。这是我的决策指南：

用 Wrangler CLI 当：

  • 你在部署脚本里跑迁移。
  • 你在 CI/CD 流水线里需要编程方式执行 SQL。
  • 你需要从终端跑个快速一次性查询，而且你已经装了 Wrangler。
  • 你在创建或删除数据库。

用 D1 REST API 当：

  • 你在构建自定义集成（脚本、机器人、内部工具）。
  • 你想从没有 Wrangler 的语言或环境查询 D1。
  • 你在写自己的管理工具，需要原始 API。

用网页 Dashboard 当：

  • 你第一次设置新的 D1 数据库。
  • 你在配置 Workers 绑定。
  • 你在查看账单或使用指标。
  • 你在一台不是你的机器上，不能装任何东西。

用本地桌面管理面板（BaseVolt 或其他）当：

  • 你在做日常数据库工作——浏览表、探索数据、调试问题。
  • 你想在 D1 数据上有视图（kanban、gallery、dashboard）。
  • 你想通过 MCP 服务器做 AI 辅助的 schema 管理。
  • 你在离线或网络差的环境下工作，想要响应快的 UI。
  • 你在同时管理 D1 和其他数据库（Postgres、MySQL、本地 SQLite），想用一个工具搞定全部。

我最终稳定下来的模式：Wrangler 做迁移和脚本，网页 dashboard 做账号级管理，BaseVolt 做其他一切。我大概 80% 的 D1 时间在 BaseVolt，15% 在 Wrangler，5% 在 dashboard。

总结一下

Cloudflare D1 是边缘的 SQLite。这对你的应用是很好的架构。但 Cloudflare 给你管理它的工具——网页 dashboard 和 CLI——是为偶尔使用设计的，不是日常。如果你每天都在 D1 数据库里，你值得一个真正的界面。

好消息是 D1 的 REST API 意味着你不是只能用 Cloudflare 的工具。任何 HTTP 客户端都能查询你的数据库。而像 BaseVolt 这样的本地优先桌面应用可以把那个 API 变成完整的管理面板——网格视图、kanban 看板、dashboard、内联编辑、AI 集成——全部跑在你的机器上，查询直接发到 Cloudflare。

你不用只听我说。免费层覆盖两个数据源，足够试试 D1 看看适不适合你的工作流。

在 basevolt.app 试试 — 无需注册，无需信用卡。

如果你在边缘做东西，想聊聊数据库工具，在 X 上找我。

BasevoltBasevolt

试试 Basevolt —— 免费的本地优先数据库管理面板，支持 PostgreSQL、MySQL、SQLite 和 Cloudflare D1。

免费下载 Basevolt