D1 Implementation for Multi-Tenant SaaS: 生产环境实现指南

如何在 Cloudflare D1 上交付多租户 SaaS 架构?本文探索三大租户隔离模式的利弊、tenant_id 在表与复合索引中的核心设计,以及达到约 250 req/s 需要面对的 D1 写入上限和迁移方案。

Huifer
Huifer
August 23, 202611 min read
其他语言:Deutsch · English

本文由 Huifer 撰写,我是独立开发者兼 TanStack Ship 的维护者。我已经将 D1 作为主数据库应用于三个多租户 SaaS 产品中——一个服务于 480 个租户、平均每天处理 14 万次请求的 B2B 分析工具,一个基于用量的计费平台,以及一个内部开发者仪表盘。以下模式都是在付费客户的真实场景中经受住考验沉淀下来的,而不是那些只在初期看起来很完美的代码。

来源验证:Cloudflare D1 documentation · D1 best practices · D1 query API reference · SQLite query planner · Cloudflare Queues · TanStack Ship D1 reference repo · D1 pricing and limits · D1 migrations

最后更新:2026-08-23 · Changelog


太长不看(TL;DR): 对于 Cloudflare D1 上的大多数多租户 SaaS 产品而言,正确的模式是共享数据库、共享 Schema、每张表保留 tenant_id 字段——并在查询层通过一个带类型的辅助函数来自动注入断言以强制执行。当你将其与以 tenant_id 开头的复合索引结合使用时,可以获得极简的运维体验(单一 Schema、单次迁移运行、单一读副本拓扑结构),同时又不会牺牲租户隔离性。官方文档中没有强调的两件事是写入吞吐量上限(在由于 SQLite 全局写锁排队之前,热路径上的持续写入上限约为 250 req/s)和迁移成本(在拥有 5000 万行的 events 表上每增加一列,就会导致 D1 的写入暂停几分钟)。在你签下第一个企业客户之前,请务必为这两种情况做好预案。


D1 上的三种多租户模式

在 D1 上构建多租户 SaaS 有三种可行的模式。每种模式都有其真实的成本。我将列举它们,并告诉你我默认选择并交付的是哪一种。

共享数据库和 Schema,并带有 tenant_id

每张表都有一个 tenant_id 字段。每次查​​询都根据 tenant_id 进行过滤。虽然应用层负责确保数据绝不会跨租户泄露,但借助一个带类型的查询辅助函数,能让它成为编译期的约束,而不是运行时的检查。

适用场景: 租户数量少于约 5000 个,且单租户数据能放进单一 Schema 中的 B2B SaaS 产品的默认选择。这就是我在 TanStack Ship starter 中所交付的模式。(Cloudflare D1 best practices 也将其作为推荐的起始方案。)

共享数据库,每租户独立 Schema

使用单一 D1 数据库,但每个租户拥有自己的 SQLite Schema(如 tenant_acme.users,tenant_globex.users 等)。在部署时,迁移工具会扇出(fan out)到每一个 Schema 进行更新。

适用场景: 在 D1 上非常罕见。对于几乎所有人来说,这带来的运维负担(每次发布需运行 N 次迁移、运行时 Schema 发现、过于庞大的 SQL 表面积)都抵消了隔离带来的好处。我曾在某个新租户注册原型上尝试过一次,但在不到一周内就回滚了。

每租户独立数据库

每个租户获得一个专属的 D1 数据库,通过动态分发与 Worker 绑定(Cloudflare Workers bindings)。

适用场景: 具有合同约束的数据隔离要求的大型企业租户,或是其单个工作负载就会超过单个数据库写入上限的租户。这非常真实,但代价高昂:你需要为每个租户单独编排迁移、为每个租户做数据汇总分析,并且还要在每个请求前加一个路由层。

对于 95% 的多租户 SaaS 产品而言,第一种模式才是最正确的。本文后续讨论均基于该首选模式。


Schema 设计:永远将 tenant_id 放首位

最重要且唯一的一条规则是:每个租户作用域的表在所有复合索引中都必须将 tenant_id 作为第一个字段。 不能是第二列。也不能仅仅是“加了索引”。必须是第一列。SQLite 的查询优化器每次引用表时只能使用一个索引,如果 tenant_id 不是该索引的前导列,你的“租户作用域”查询会默默退化为全表扫描。

sql
-- 租户表 —— 它自身绝不是租户作用域的
CREATE TABLE tenants (
  id          TEXT PRIMARY KEY,           -- ULID,例如 01HZX5K4...
  slug        TEXT NOT NULL UNIQUE,        -- 'acme', 'globex'
  plan        TEXT NOT NULL DEFAULT 'free', -- 'free' | 'pro' | 'enterprise'
  created_at  INTEGER NOT NULL DEFAULT (unixepoch())
);

-- 一个典型的租户作用域表
CREATE TABLE projects (
  id          TEXT PRIMARY KEY,
  tenant_id   TEXT NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
  name        TEXT NOT NULL,
  created_at  INTEGER NOT NULL DEFAULT (unixepoch())
);

-- 能够让租户作用域查询变得极快的复合索引
CREATE INDEX idx_projects_tenant_created
  ON projects(tenant_id, created_at DESC);

-- 该索引专门用于服务以下查询
SELECT id, name FROM projects
WHERE tenant_id = ?
ORDER BY created_at DESC
LIMIT 50;

复合索引 tenant_id, created_at DESC 对于该查询而言也是一个覆盖索引(covering index)——SQLite 直接返回已经排好序的行,无需执行单独的排序步骤。这与我在 D1 advanced optimization guide 中记录的索引结构完全相同,它是你在多租户 Schema 中所能撬动的最大性能杠杆。

一个让你不会遗忘的查询辅助函数

在多租户应用中,最常见的跨租户数据泄露就是开发者写了类似 db.prepare("SELECT * FROM projects WHERE id = ?") 的代码,却漏掉了 tenant_id = ? 条件。解决这个问题的办法是使用一个带类型的包装器,在类型约束层面强制要求传入租户上下文。以下是我在 Cloudflare Workers 上使用 TypeScript 的实现形式:

ts
// src/server/db/tenant-query.ts
import type { D1Database } from "@cloudflare/workers-types";

export type TenantContext = { tenantId: string };

export function tenantDb(db: D1Database, ctx: TenantContext) {
  return {
    async getProject(id: string) {
      return db
        .prepare("SELECT * FROM projects WHERE id = ? AND tenant_id = ?")
        .bind(id, ctx.tenantId)
        .first();
    },
    async listProjects(limit = 50) {
      return db
        .prepare(
          "SELECT * FROM projects WHERE tenant_id = ? ORDER BY created_at DESC LIMIT ?"
        )
        .bind(ctx.tenantId, limit)
        .all();
    },
    async createProject(name: string) {
      return db
        .prepare(
          "INSERT INTO projects (id, tenant_id, name) VALUES (?, ?, ?)"
        )
        .bind(crypto.randomUUID(), ctx.tenantId, name)
        .run();
    },
  };
}

这并不是完美的保证——开发者仍然可以绕回包装器直接调用 db.prepare。但它在常规路径周围建起了一堵防护墙。要解决残留风险,靠的是集成测试,而不是更多的抽象。


写入吞吐量上限

这正是 D1 多租户设计中最出乎所有人意料的部分。

D1 基于 SQLite 构建。SQLite 在每个数据库上都有一个全局写锁——同一时间只能有一个写入者,绝无例外。(SQLite locking docs)。D1 通过批处理操作和极快的 WAL 模式实现掩盖了这种锁带来的大部分延迟开销,但写锁依然是全局的。

在我的 B2B 分析工具的生产部署中,480 个租户的自然写入负载平均约为 45 req/s。在这个速率下,锁队列深度维持在 0-2 之间,p99 写入延迟低于 10ms。当我第一次看到 p99 飙升到 8000ms 时,持续的负载正处于大约 250 req/s,当时是因为计费 webhook 的重试风暴使得实际有效负载翻了两倍。我在 D1 Write Lock Contention at 200 req/s 一文中详细记录了完整的故障复盘;简单来说,是因为一条热路径(hot path)在每次请求时执行了 4 次连续写入,而 SQLite 将其全部串行化了。

这个上限并不是一个绝对的硬性数字——D1 的存储层很快,且 Workers 运行时每次请求都有 30 秒 CPU 预算——但应当将约 200–300 req/s 的持续写入量作为你的余量预估,而不是幻想 10000。如果你的路线图中的写入量超过这个数值,你需要从以下三种缓解措施中选择一种:

  1. 通过 db.batch() 执行批量写入 —— 将相关的多个写入操作分组放在单个事务中。锁只会在这一批处理中持有,而不是分成 N 次。(D1 query API reference)
  2. 将热路径转移到 Cloudflare Queues —— webhook 处理程序将任务排队入栈,队列消费者以 D1 能够承受的速率进行消费。(Cloudflare Queues docs)
  3. 检测热门租户并拆分(shard) —— 单个租户的分析数据写入如果霸占了锁,这就不是所谓的“D1 扩展性问题”,而是“这个租户需要自己专属的独立数据库”。

在 TanStack Ship 的计费与事件收集模块中,我默认选择了交付方案 1 和方案 2。仅仅当单个租户的负载超过了你数据库写入上限的约 30% 时,才需要人工介入采取方案 3。


读副本、热读取以及 resolve 提示

D1 通过 D1 read replication API 提供了跨区域的读副本机制。对于多租户 SaaS 而言,这一点非常重要,原因有两方面:

  • 一位位于新加坡的租户在查看他们的仪表盘时,应该命中离他们最近的副本,而不是访问位于 enam(北美东部)的主库。
  • 热门租户——也就是那些仪表盘占用了 40% 读取流量的租户——不应该挤占其他较小租户的副本容量。

默认的 db.prepare(...).first() 调用会被路由到最近的读副本。first() method 接受一个 resolve 选项,当你需要保证写后读(read-your-writes)一致性时,可以强制将请求路由到主库:

ts
// 写入操作后,强制下一次读取命中主库
await db
  .prepare("INSERT INTO projects (id, tenant_id, name) VALUES (?, ?, ?)")
  .bind(crypto.randomUUID(), ctx.tenantId, name)
  .run();

const fresh = await db
  .prepare("SELECT * FROM projects WHERE id = ?")
  .bind(newId)
  .first({ resolve: "primary" }); // 绕过读副本,查看我们刚才的写入结果

请谨慎使用这一点。每一次被强制导向主库的读取,都会命中那个加了写锁的同一区域;如果你在代码库的各个地方都散布着 resolve: "primary",你就会失去读副本原本带来的延迟红利。正确的使用场景应该是:(a) 在同一个请求中紧接在写入操作之后;以及 (b) 显示“刚刚创建”指示标的仪表盘组件。


跨越千万行租户表的迁移策略

D1 的数据迁移是通过 Wrangler's d1 migrations command 来运行的。每个迁移操作就是一个或多个按顺序执行的 SQL 文件。对于多租户 SaaS 来说,有两种迁移模式常常让大家踩坑:

带有默认值的 NOT NULL 字段追加

SQLite 支持以 O(1) 的复杂度添加一个具有固定默认值的列——这不需要重写整张表。即使是在拥有 5000 万行的 events 会员表上,迁移速度也非常快:

sql
-- 即使在巨型表上也很安全 —— SQLite 仅将默认值存储在元数据中
ALTER TABLE events ADD COLUMN source TEXT NOT NULL DEFAULT 'web';

无默认值的 NOT NULL 字段追加

这需要重写整张表。在 D1 上,它意味着长达几分钟的写入停摆和相当可观的行扫描计费开销。切勿在生产环境下的活动租户表里进行这种操作。 我所使用的模式是:

  1. 在第 N 次迁移中,将该列添加为可空类型(nullable)。
  2. 通过 Cloudflare Workflow 执行数据回填(backfill),它将以每批次 10000 行包含自动重试的方式处理。
  3. 在回填 Workflow 报告完成后,再在第 N+1 次迁移中加上 NOT NULL 约束。

在 TanStack Ship billing module reference 中记录了这个完整的 Workflow 模式,正是依靠这种方式,才能安全应对超出数千万行以后的租户表的大规模迁移。


租户入驻与注销

有两种操作游离在常规请求路径之外,但其重要性远超表面:分别是租户开通服务(以干净的 Schema 状态产生新账户)以及租户数据导出(客户流失并要求取回他们数据时)。

入驻(Onboarding) 是通过单次事务来完成的操作,用于创建 tenants 的行记录并写入所有你需要的各租户默认配置:

ts
await db.batch([
  db.prepare("INSERT INTO tenants (id, slug, plan) VALUES (?, ?, 'free')")
    .bind(newTenantId, slug),
  db.prepare("INSERT INTO tenant_settings (tenant_id, key, value) VALUES (?, 'theme', 'default')")
    .bind(newTenantId),
  db.prepare("INSERT INTO tenant_settings (tenant_id, key, value) VALUES (?, 'timezone', 'UTC')")
    .bind(newTenantId),
]);

你应该将所有单一租户的默认操作打包进同一个事务内。不完整的入驻——比如租户行建了,设置只写了一部分——将酿就那种六个月后难以彻底清理的烂摊子。

数据导出(Data export) 本质上是对每个含有租户范围设计的表均执行 SELECT … WHERE tenant_id = ?,格式化为 JSON 之后,作为流输出发送到 R2 存储桶。目前我使用的组合方式是一个 Workflow 把每表数据传出单个文件至 R2 ,由另一个 Workflow 对这些提取下来的结果执行 zip 打包加上签名。R2 的成本极低,并且附带签名的 URL 无论如何都会比直接泄露自己的 D1 绑定显得更专业且干净整洁。此模式甚至能以同理处理 GDPR 的彻底删除类请求:抽调对应 tenant_id = ? 的查询把数据传去 R2,然后在单个基于批次操作的独立事务里面去对整体执行 DELETE FROM … WHERE tenant_id = ? 即可。


融会贯通

在 D1 上的多租户 SaaS 并没有什么神秘色彩。它就是我们在 Postgres 或 MySQL 里面老生常谈并且驾轻就熟的 tenant_id 模式,区别仅仅在于必须及早为 D1 特有的两种现实做出预案规划:高达约 200–300 req/s 后的全局写锁瓶颈,以及当租户作用表的行数超过 1000 万行时的重新扫描迁移成本。

那些在我的生产环境中历经真实验证坚持下来的实战操作步骤包括:

  1. 必须让 tenant_id 成为每个复合索引的首列。 它绝对不该放在第二列的位置,更不该仅作为一个非首列过滤条件。
  2. 使用带类型的查询辅助函数 来自动注入租户断言(predicate)。千万要克制住过度抽象的冲动;数据泄露风险是在 SQL 层面,而不是 ORM 层面。
  3. 在热路径上对于任何多条语句的写入都使用 db.batch()。单一事务,只获取一次锁。
  4. 仅在写后读一致性十分关键的地方使用 resolve: "primary"。 其余一切请求都应当交由读副本处理。
  5. 在碰到会改变现行大结构的情况下,任何追加列等操作时,必须基于 Workflow 的数据回填机制。

花一个周末的时间在 D1 上交付多租户 SaaS。 TanStack Ship 的新手入门套件(starter)包含完整的 tenant_id Schema、具备完整类型的查询辅助函数、db.batch() 模式、基于 Workflow 会自动处理回填的表结构迁移,以及能够路由给读副本作快速读取响应的现成实现——各种逻辑被相互连接并覆盖好所有的集成化测试流程。这些同源的经典模式在我的自己所经营三款主打 SaaS 中经受过了各种生产级验证。你可以 Clone the free starter →,或者查阅文档与其他类似产品体系进行 TanStack Ship alternatives 的全方位对比。