本文由 Huifer 撰写,我是 TanStack Ship 的独立开发者兼维护者。我在 8 个生产环境 SaaS 应用中运行了 D1——包括一个每天约 14 万次请求的多租户分析工具、一个 B2B 计费平台、一个开发者仪表板、两个 B2B 市场以及三个较小的应用——在过去的 18 个月里,我不断地发布、破坏并重新发布那些让 D1 在边缘计算环境中存活下来的模式。本文将这些模式整合为一份参考指南。没有任何供应商赞助;下文所有的内容都是已上线的代码,而非幻灯片。入门材料请参阅 D1 生产环境指南;进阶查询调优请参阅 D1 优化解析。本文介于两者之间——探讨的是决定你的应用能否挺过第一季度的架构与运维模式。
验证来源:Cloudflare D1 documentation · D1 best practices · D1 query API · D1 read replicas · SQLite query planner · Wrangler D1 migrations · TanStack Ship D1 reference repo
最后更新:2026-07-10 · 更新日志
太长不看 (TL;DR): D1 是边缘环境下的 SQLite,具有 HTTP 驱动的访问模式、区域复制以及 Workers 原生绑定。它的优势是真实的:亚毫秒级读取、无需连接池、按行计费。但陷阱也是真实的:在 Postgres 中行之有效的模式在 D1 中并不适用,且故障模式只有在负载压力下才会显现。以下 8 种模式是我的部署中经受住真实生产流量考验的经验结晶:多租户模式设计、热路径查询塑造、写入路径批处理与幂等性、可观测性、日常备份运维、读副本、基于阴影表的迁移,以及使用 miniflare 的兼容性测试。如果你正在进行技术栈选型,请参考 TanStack Ship 功能页面;若需更广泛的架构背景,请查阅 SaaS 架构指南。
D1 的“生产就绪”到底意味着什么
边缘 SQLite 的承诺与其破灭之处
根据 Cloudflare D1 documentation,D1 是通过 Workers 绑定暴露的 SQLite,它跨 Cloudflare 网络进行复制,并按行读取和写入计费。对于独立开发者而言,它的吸引力显而易见:无需连接池、无需驱动程序、无需独立服务器,且能从最近的副本中以个位数毫秒级返回读取结果。我曾发布过一些应用,其整个持久层仅仅是 env.DB.prepare(...).all(),该应用在每个区域都能支撑每秒数百个请求。
这个承诺在两个地方会破灭。首先,D1 不是 Postgres。 任何依赖 Postgres 特定功能(如 JSONB 操作符、LISTEN/NOTIFY、咨询锁)的内容,都必须用 SQLite 方言重新表达或直接放弃。其次,写入竞争是真实存在的。 每一次 D1 写入都会在事务期间获取数据库级别的写锁;在突发负载下,请求会被序列化排队,p99 延迟攀升,且 Workers 绑定会开始超时。这两点在文档中都有明确说明,但在你自己看到仪表板上的数据之前,很容易被抛诸脑后。关于更广泛的技术栈背景,SaaS 架构指南 详细介绍了围绕 D1 的运行时决策。
每个 D1 应用最终都会遇到的 4 种故障模式
在 8 个生产应用中,同样的 4 种故障模式反复出现。提前将它们指出来,能为你省下未来的调试时间。
- 突发负载下的写锁竞争 (Write-lock contention)。两个请求同时写入同一个数据库;第二个请求必须等待第一个请求提交。在稳定负载下这没问题;但在 10 倍突发情况下,它就会变成一个长队列。
- 区域间的写后读不一致 (Read-after-write inconsistency)。对
ENAM主节点的写入,在几秒钟内无法被WEU副本的读取操作看到。任何需要强一致性的操作都必须路由到主节点。 - 本应通过单次
db.batch()完成的繁琐事务 (Chatty transactions)。串行发送的 5 条INSERT语句会付出 5 次网络往返的代价。 - 缺乏阴影表策略、触及大表的模式迁移 (Schema migrations)。对一个 500 万行的表执行简单的
ALTER TABLE是能运行的,但它会在执行期间锁定全部写入。
本文剩余部分就是解决每一个问题的模式。
撑得住多租户负载的模式设计
基于组合键的行级租户隔离
模式设计的第一个决策是如何隔离租户。D1 支持每个账户拥有多个数据库,这听起来很诱人,直到你发现每一个额外的数据库都意味着另一个绑定、另一套复制拓扑和另一笔计费条目。对于大多数多租户 SaaS 应用来说,使用单一数据库并进行行级租户隔离会更简单、更便宜。这种模式的做法是将 tenant_id 作为每一个组合索引的第一列,并在每个查询中强制使用它。
-- 每一个业务表都以 tenant_id 作为前置列
CREATE TABLE projects (
id TEXT PRIMARY KEY,
tenant_id TEXT NOT NULL,
name TEXT NOT NULL,
created_at INTEGER NOT NULL DEFAULT (unixepoch()),
archived_at INTEGER,
FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
);
-- 每个索引都是组合索引,并将 tenant_id 放在首位
CREATE INDEX idx_projects_tenant_created
ON projects(tenant_id, created_at DESC);
CREATE INDEX idx_projects_tenant_active
ON projects(tenant_id, archived_at)
WHERE archived_at IS NULL;
基于 archived_at IS NULL 的部分索引,正是 D1 的 SQLite 方言中能为习惯 Postgres 的开发者提供他们所怀念特性的地方:一个仅包含活动行的部分索引,这使得即使表不断增大,索引也能保持较小。根据 SQLite query planner documentation,查询规划器会在主要查询中使用此索引,而在扫描归档数据时忽略它——这恰好是你想要的效果。
带有审计跟踪的软删除
在多租户 SaaS 中进行硬删除是在给自己挖坑。用户点击“删除项目”,这一行数据随之消失,而下一个账单周期的发票依然引用了该项目的 ID,于是你的生产环境就出现了外键违规报错。解决办法是软删除结合审计表。
ALTER TABLE projects ADD COLUMN deleted_at INTEGER;
CREATE TABLE project_deletions (
id TEXT PRIMARY KEY,
project_id TEXT NOT NULL,
tenant_id TEXT NOT NULL,
deleted_by TEXT NOT NULL,
deleted_at INTEGER NOT NULL DEFAULT (unixepoch()),
reason TEXT
);
CREATE INDEX idx_deletions_tenant ON project_deletions(tenant_id, deleted_at DESC);
所有的删除路径都通过一次 db.batch() 事务,向 project_deletions 插入记录并更新 projects.deleted_at。读取操作则通过过滤 deleted_at IS NULL 来实现。一个每晚执行的定时任务 (cron) 会在将数据导出至 R2 后,对超过 90 天的旧数据执行硬删除。
面向大容量事件的时间分桶表 (Time-bucketed tables)
对于分析型工作负载——请求日志、审计事件、遥测数据——单一的 events 表增长极快,而且查询变慢得更快。解决方法是使用时间分桶表,按天或按周划分,并创建一个将它们进行联合查询的视图 (View)。
CREATE TABLE events_2026_07_10 (
id TEXT PRIMARY KEY,
tenant_id TEXT NOT NULL,
kind TEXT NOT NULL,
payload TEXT NOT NULL,
created_at INTEGER NOT NULL DEFAULT (unixepoch())
) WITHOUT ROWID;
CREATE INDEX idx_events_2026_07_10_tenant_kind
ON events_2026_07_10(tenant_id, kind, created_at DESC);
CREATE VIEW events AS
SELECT * FROM events_2026_07_10
UNION ALL
SELECT * FROM events_2026_07_09
UNION ALL
SELECT * FROM events_2026_07_08;
一个定时任务在 00:05 UTC 运行,创建明天的分桶表,并更新该视图。针对 events 的读取请求仍然能透明地工作。旧的分桶可以被分离出去(直接删除表,并移除视图条目),而无需触碰活动数据。WITHOUT ROWID 子句是针对主键已是有效标识符的表的 SQLite 特有优化——对于事件表而言,这可以省去隐式的 rowid 索引,进而缩减约 30% 的存储空间。
超越基础的查询模式
预处理语句与热路径
在 Workers 处理函数中,每次调用 db.prepare() 都会在冷路径上重新解析 SQL。对于热路径来说,节省的开销是真切但有上限的;但对于每天命中数据库数百万次的温路径来说,这些节省的开销就会积少成多。我所采用的模式是一个以 SQL 文本为键的模块级语句缓存。
// src/server/db.ts
const stmtCache = new Map<string, ReturnType<D1Database['prepare']>>()
export function prep(sql: string) {
let stmt = stmtCache.get(sql)
if (!stmt) {
stmt = env.DB.prepare(sql)
stmtCache.set(sql, stmt)
}
return stmt
}
// 在处理程序中的用法
const user = await prep('SELECT id, email FROM users WHERE id = ?')
.bind(userId)
.first<User>()
该缓存存活于单一 Isolate 的生命周期内;冷 Isolate 会从头开始重建它,这就是你为了保持绑定无状态所付出的代价。根据 D1 query API documentation,预处理语句不会跨 Isolate 共享,因此这个缓存是单个 Isolate 级别的,而非全局的——但这已足以消除热路径上的解析成本。
主节点路由实现写后读一致性
我发布过的最常见的单一 D1 生产环境 bug 就是区域间的写后读不一致情况。这种场景是:一个在 WEU 区域的用户创建了一个项目,立即导航到项目详情页,接着碰到了一个 404 错误,因为该次读取请求是从尚未完成同步的 WEU 副本中返回的。解决模式是通过使用绑定的 resolve: "primary" 选项,将所有写入后的读取请求路由到主节点。
// src/server/projects.ts
export async function createProject(input: CreateProjectInput) {
const id = crypto.randomUUID()
await env.DB.prepare(
'INSERT INTO projects (id, tenant_id, name) VALUES (?, ?, ?)'
).bind(id, input.tenantId, input.name).run()
// 写入后的读取请求 MUST 发往主节点
return await env.DB.prepare(
'SELECT * FROM projects WHERE id = ?'
).bind(id).first({ resolve: 'primary' } as any)
}
resolve: "primary" 标志告知 D1 跳过副本来读取权威数据的副本。这么做有延迟上的代价(你损失了就近区域带来的速度优势),所以你仅应在写入后的关键路径上使用它——绝不能将其作为所有查询的默认选项。根据 D1 read replicas documentation,复制延迟往往在 5 秒以内;将首次写后读取路由至主节点,能确定性地消除这一间隙。
分页:永远使用 cursor (游标) 替代 OFFSET
每一次加载,OFFSET 1000 都会使得 D1 扫描并丢弃 1000 行。对于一个有着数百万行数据的表来说,即便你有完美的索引,第 1000 页的查询速度也会明显变慢。使用基于带索引键值的游标 (cursor) 分页是唯一正确的做法。
// src/server/projects.ts
export async function listProjects(
tenantId: string,
cursor: string | null,
limit = 50,
) {
const rows = await env.DB.prepare(
cursor
? `SELECT id, name, created_at FROM projects
WHERE tenant_id = ? AND created_at < ?
ORDER BY created_at DESC LIMIT ?`
: `SELECT id, name, created_at FROM projects
WHERE tenant_id = ?
ORDER BY created_at DESC LIMIT ?`
).bind(...(cursor ? [tenantId, cursor, limit] : [tenantId, limit]))
.all()
const nextCursor = rows.length === limit
? rows[rows.length - 1].created_at.toString()
: null
return { rows, nextCursor }
}
游标就是上一页最后一行记录的 created_at 的值;下一页将在复用同个组合索引的基础上通过 created_at < cursor 进行过滤。无论用户分页翻得多么深,此时生成的查询计划都是相同的。若想了解更深入的查询调优细节,请参考 D1 优化解析,里面详细介绍了 EXPLAIN 计划。
边缘计算的写入路径模式
db.batch() 适用于事务,而非繁琐的写请求
db.batch() API 是 D1 中最常被误用的功能。它不是一种“更快速”发送 N 条语句的方式;它是一种将 N 条语句进行原子化发送的方式。在一个 batch 中,要么所有语句全部提交成功,要么不提交任何语句。该模式的做法是将触及多张表的任何一组逻辑操作包裹进一个 batch 里。
// src/server/billing.ts
export async function recordInvoicePayment(invoiceId: string, amount: number) {
const results = await env.DB.batch([
env.DB.prepare(
'UPDATE invoices SET status = ?, paid_at = unixepoch() WHERE id = ?'
).bind('paid', invoiceId),
env.DB.prepare(
'INSERT INTO payments (id, invoice_id, amount, created_at)
VALUES (?, ?, ?, unixepoch())'
).bind(crypto.randomUUID(), invoiceId, amount),
env.DB.prepare(
'UPDATE tenants SET balance_cents = balance_cents - ?
WHERE id = (SELECT tenant_id FROM invoices WHERE id = ?)'
).bind(amount, invoiceId),
])
return results
}
相反的模式——连续三次分开发送 await env.DB.prepare(...).run()——会带来三次网络往返,且没有原子性保证。如果第二条语句失败,而第一条语句已经提交,你将会留在一个带有部分状态的数据中。根据 D1 best practices,这种同步且“逐句执行”的模式被记载为反模式。
借助队列实现扇出型写入 (write fan-out)
对于非必须同步进行的写入负载——Webhook 递送、电子邮件发送、审计日志记录、扇出通知——Cloudflare Queues 是最合适的基元。这种模式的做法是:在一个 Worker 处理程序中入队,再由一个队列消费者以更大的批次将它们写入 D1。
// 生产者模块(请求路径)
await env.WRITE_QUEUE.send({
type: 'audit',
tenantId,
payload: { action: 'project.delete', projectId },
})
// 消费者模块(队列 worker,src/workers/queue-consumer.ts)
export default {
async batch(batch: MessageBatch<AuditEvent>, env: Env) {
const stmts = batch.messages.map((msg) =>
env.DB.prepare(
'INSERT INTO audit_log (id, tenant_id, kind, payload, created_at)
VALUES (?, ?, ?, ?, ?)'
).bind(crypto.randomUUID(), msg.body.tenantId, msg.body.type,
JSON.stringify(msg.body.payload), unixepoch())
)
await env.DB.batch(stmts)
await Promise.all(batch.messages.map((m) => m.ack()))
},
}
该消费者一次最多可接收 100 条消息,并将它们作为一个批次一次性全部写入。这就是我避免让审计日志写入与面对用户的业务数据库写入争夺同一把锁的方式。此外,队列的重试语意也能吸收 D1 的瞬时错误——失败的消息会自动退避重试,而不是直接向用户返回 5xx 状态码。
Stripe 等 Webhooks 的幂等键机制
任何能够两次递送相同事件的外部系统——Stripe webhooks、GitHub hooks、第三方的 OAuth 回调——都需要一层幂等层。在 D1 中的模式,是设计一张微小的 idempotency_keys 表,并把它放在需要产生逻辑效果的同一个处理批次内进行检查。
// src/server/webhooks/stripe.ts
export async function handleStripeEvent(event: Stripe.Event) {
const result = await env.DB.batch([
env.DB.prepare(
'INSERT OR IGNORE INTO idempotency_keys (key, processed_at)
VALUES (?, unixepoch())'
).bind(event.id),
env.DB.prepare(
'INSERT INTO payments (id, stripe_event_id, amount_cents, created_at)
VALUES (?, ?, ?, unixepoch())'
).bind(crypto.randomUUID(), event.id, event.data.object.amount),
])
const inserted = result[0].meta.changes === 1
if (!inserted) {
console.log(`Duplicate Stripe event ${event.id}, skipping`)
return
}
// ... 此处继续处理下游的副作用
}
INSERT OR IGNORE 发挥了锁的作用:倘若相同事件的另一次递送已经占用了该键,那么这次插入便成了空操作 (no-op),并且第二条执行语句绝不会运行。更详尽的 Webhook 故障复盘——这也是教会我运用此模式的真实生产环境事故——可在 Stripe webhook postmortem 文章中查阅。
可观测性与运维模式
利用 Workers Analytics 的查询时间遥测
D1 服务器并未内置 APM (应用性能管理)。我采用的模式是对 env.DB.prepare(...).all() 附上一层极薄的封装函数,将查询文本经过哈希后的字符串和执行耗时一同记录到 Workers Analytics Engine。
// src/server/db.ts
export async function timedAll<T>(
sql: string,
binds: unknown[],
env: Env,
): Promise<D1Result<T>> {
const start = performance.now()
const result = await env.DB.prepare(sql).bind(...binds).all<T>()
const elapsedMs = performance.now() - start
env.ANALYTICS.writeDataPoint({
indexes: [hashString(sql)],
blobs: [sql.slice(0, 200), elapsedMs],
doubles: [elapsedMs],
})
return result
}
Workers Analytics Engine 是一处理想的归宿,因为它价格低廉(按写入的数据点计费而非按查询),支持通过 SQL 查询,而且与其余部分的 Worker 日志排布在相同的仪表板上。哈希 SQL 的方法提供了基数有界的索引;原始 SQL 二进制对象则提供了一个便于人阅读的标签。当你积累了一周的数据后,SELECT blob1, percentile(doubles[1], 99) FROM ... GROUP BY blob1 ORDER BY 2 DESC 就能即刻生成你需要的前 N 个最慢查询报表。
视为一等运维任务的备份与恢复机制
在发生事故期间,你绝对不会想第一次手忙脚乱地在那现场赶写一份系统恢复指南。最好的模式是将每日夜间通过 wrangler d1 export 导出至 R2 标准化,并配有成文规定的日常恢复演练过程。
# scripts/backup.sh — 每晚 03:00 UTC 运行
wrangler d1 export production-db \
--output "backups/d1-$(date +%Y%m%d-%H%M).sql" \
--output-bucket="r2://tanstack-ship-backups"
# scripts/restore-drill.sh — 每周运行,恢复到一个临时数据库进行测试
wrangler d1 create scratch-restore-target
wrangler d1 execute scratch-restore-target \
--file "backups/d1-$(date +%Y%m%d - 7 days).sql"
这种导出生成的是一份包含了模式与数据的 SQL dump。而恢复演练才是那个能证明其真正可以还原复苏系统的唯一方法——要是省去了这步,你只会在实打实的事故现场才发觉那种导出格式居然带有让你大跌眼镜却束手无策的隐性问题。全套攻略走查可进入 D1 备份和恢复指南。
读副本与时间旅行查询
针对读取密集的负载——例如各种仪表板面板、搜索查询及数据导出作业——D1 读副本在此刻正是不可多得的底层基石。这种模式是将这类绑定在代码中直接标识成只读配置,而且去把一切并不要求必须是写级强一致性特供的事务操作尽数流转输送到它那执行处理。
// wrangler.toml
// [[d1_databases]]
// binding = "DB"
// database_name = "production-db"
// database_id = "..."
//
// [[d1_databases]]
// binding = "DB_READ"
// database_name = "production-db-readonly"
// database_id = "..."
// read_only = true
// src/server/dashboards.ts
export async function getDashboardStats(tenantId: string) {
return await env.DB_READ.prepare(
`SELECT date(created_at) AS day, COUNT(*) AS count
FROM events
WHERE tenant_id = ? AND created_at > ?
GROUP BY day ORDER BY day`
).bind(tenantId, unixepoch() - 30 * 86400).all()
}
针对监控大屏仪表面板的获取读取可谓是最经典的读副本范例:它完全容忍哪怕出现那么点几秒时间的迟滞陈旧现象,自身充斥读取密集操作的同时也不存在任何回写操作。根据 D1 read replicas documentation 的指引显示,读副本将最终总会不断与主节点追平同步,并且在应对每一行数据读取时所收取计费的价格费率也更低。有关这一更为复杂的副属副本架构的指南可见于 D1 读副本扩展指南。
迁移策略:从本地 SQLite 到多区域 D1
基于阴影表策略的 Wrangler 数据库迁移
用 ALTER TABLE ADD COLUMN 迁移 D1 表是一种简单粗暴的想当然做法,因为在含有百万级别行数的表上,它会强行抓取保持写锁,并在运行的这段周期内把整整一张大表完完全全改写一番。正确的路径便是走向 阴影表模式 (shadow-table pattern):新创建一张贴合你梦想预期的完美结构全新表结构,并且指挥部署应用代码使之达成同步两端的“双写”,经由批量的机制进行数据慢慢回充倒填,等到万事俱备最终才实行那招在原子层面上执行置换的交换替代。
-- 步骤 1:创建阴影表
CREATE TABLE projects_v2 (
id TEXT PRIMARY KEY,
tenant_id TEXT NOT NULL,
name TEXT NOT NULL,
description TEXT, -- 新列
created_at INTEGER NOT NULL DEFAULT (unixepoch()),
archived_at INTEGER
);
-- 步骤 2:应用代码现在将其同时写入 projects 与 projects_v2
-- 步骤 3:定时任务执行批量回填(每批 1 万行,中间进行休眠)
INSERT INTO projects_v2
SELECT id, tenant_id, name, NULL, created_at, archived_at
FROM projects
WHERE id > ? ORDER BY id LIMIT 10000;
-- 步骤 4:回填彻底完成并经确认无误后以拥有原子性的方式:
DROP TABLE projects;
ALTER TABLE projects_v2 RENAME TO projects;
-- 重新建立各种索引
阴影表的模式虽慢但在安全方面滴水不漏。而简单粗暴直接的 ALTER TABLE 尽管操作指令干脆极速却会让那些等待操作的并发写入业务彻底在此阶段因为上锁遭遇了阻断甚至崩溃停顿。针对承接着线上用户直接交互活水的实战型 SaaS 产品,它究竟该做何选择答案其实极其直白了。更深一层的指点操作可以在查阅官方的 Wrangler migrations documentation 取用。
使用 miniflare 进行兼容性测试
每一次数据迁移最终都要向真实部署的生产库发起动作。在那之前通过 miniflare 将整个大迁移动作完全实施跑一遍至那个设在本地的独立的 D1 拟态引擎库中执行极为必要。借由其可以去检测所有的那些 SQL 是否做到了完美运行不留坑、相关配置索引用否都已经实实在在创建存留完尽、以及真到了迫不得已其回溯倒退操作它退不退得回。
// src/server/__tests__/migrations.test.ts
import { applyD1Migrations, env } from 'cloudflare:test'
beforeEach(async () => {
await applyD1Migrations(env.DB, env.TEST_MIGRATIONS)
})
test('migration 0042 adds description column without locking writes', async () => {
const result = await env.DB.prepare(
"PRAGMA table_info('projects')"
).all()
expect(result.results.map((r) => r.name)).toContain('description')
})
代码中的 cloudflare:test 核心模块功能,正是 Vitest 为了在执行每次测试文档所针对开启并让其能够孵化驱动运作隔离出一尊完整 D1 单体应用。它通过 miniflare 去跑,所面对验证的完全是一尊最为真实的 SQLite 进行推算抗压试验出来的而非随手糊来空用伪装打发事的模拟造件,借此这批经手检测在 SQL 操作端也才配拥有保证确实可行的一套保障。
割接清单 (The cutover checklist)
无论遇到任何一项基于生产环境实施的数据库变更迁移前阵,这份确认待核检列表都是这雷打不动的 5 项大检查事项:
- 在使用比生产环境更大数据集的 miniflare 环境中,数据迁移能够干净利落地完美运行。
- 回滚脚本已在相同的 miniflare 数据集中通过了测试。
- 阴影表的双写机制已经过端到端的验证。
- 数据回填定时任务已经执行,并确认新旧表之间的行数匹配。
- 最近一晚导出的备份已经成功通过了恢复演练。
如果这 5 项中有任何一项未被勾选,那么迁移工作就不得上线。这种模式在 8 个生产应用中针对几十次的迁移始终保持一致;为了跑完这一确认清单而延迟 24 小时进行数据库的迁移工作,这从来都不是一个错误的决定。
结语
在 2026 年,D1 对于个人 SaaS 开发者而言是绝佳的基础组件——但前提是你的架构必须为它量身设计。上述的各项模式都是在真实的负载下身经百战存活下来的经验总结:基于行的租户隔离、部分索引、游标分页、路由至主节点的写后读取、批量事务、基于队列的扇出写入、处理处理幂等键、查询时长遥测、包含每周恢复演练的夜间备份、服务于仪表板的读副本架构以及基于阴影表的无缝迁移。这些都不是奇淫技巧;全都是生产必须。
如果你正在从零开始,请参阅 TanStack Ship 功能页面、D1 生产环境指南 与 SaaS 架构指南。关于更深层次的调查排错,D1 写入锁问题复盘 和 D1 优化解析 涵盖了来自事故本身与查询调优面的全面解析。D1 备份和恢复指南 与 D1 读副本扩展指南 则补全了这一个闭环的运维回路。