multi-tenant-platform-architecture

多租户平台架构（Cloudflare · Vercel）

工作流（顺序很重要）

0. 选择平台

• Cloudflare：使用 Workers for Platforms + dispatch namespaces 实现每个租户的代码隔离；适合运行不受信任代码的租户，或需要以边缘计算为先并使用 D1/KV/DO 原语的场景。
• Vercel：使用 Next.js App Router + Middleware 实现共享应用多租户；适合租户共用一个代码库，且需要 ISR、React Server Components 和托管部署的场景。
• 选择一个平台；不要混用托管方式。其余步骤适用于两个平台，具体的平台指南见参考文件。
• 选定平台后，只加载该平台的参考资料，除非你明确要比较 Cloudflare 与 Vercel。

1. 选择域名策略

• 对所有子域名/自定义主机名使用专用租户域名（与品牌域名分开）。声誉不会隔离；random.acme.com 上的钓鱼网站会损害整个域名的声誉。
• 为租户工作负载注册单独的顶级域名（例如，租户使用 acme.app，品牌使用 acme.com）。
• 考虑使用 PSL 实现浏览器 Cookie 隔离；它不能保护声誉。参见 psl.md。
• 尽早提交 PSL；审核可能需要数周。

2. 选择租户识别策略

• 基于子域名：tenant.yourdomain.com。需要通配符 DNS。适合大量租户，且实现最简单。
• 自定义域名：租户使用自己的域名，并通过 CNAME 指向你的平台。适合重视品牌或付费的租户。
• 基于路径：yourdomain.com/tenant-slug。无需为每个租户配置 DNS/SSL，但会限制品牌塑造，并使 Cookie 隔离更复杂。
• 选择一种主要策略；将自定义域名作为升级选项。

3. 定义隔离模型

• Cloudflare：对于运行不受信任代码的租户，优先使用每个租户独立的 Workers（Workers for Platforms dispatch namespaces）。除非你完全控制代码和数据，否则避免采用共享租户分支。
• Vercel：使用单个共享的 Next.js 应用，并按 tenant_id 限定范围。Middleware 根据主机名解析租户；所有数据查询都要包含租户上下文。使用 Postgres RLS 实现纵深防御。

4. 确定性地路由流量

• Cloudflare：由平台 Worker 负责路由；主机名 -> 租户 ID -> dispatch namespace -> 租户 Worker。没有映射时返回 404。
• Vercel：Next.js Middleware 提取主机名，并将 URL 重写到 /domains/[domain] 动态段。使用 Edge Config 实现亚毫秒级租户查询。没有映射时返回 404。
• 在两个平台上，租户都不能控制路由，也无法看到其他租户。

5. 在整个技术栈中传递租户上下文

• Cloudflare：平台 Worker 解析租户，并在分发到租户 Worker 之前注入标头或绑定。
• Vercel：Middleware 设置 x-tenant-id、x-tenant-slug、x-tenant-plan，并将其放入转发请求标头。Server Components 通过 headers() 读取；API 路由从请求标头读取。
• Middleware/平台 Worker 是唯一权威来源；绝不信任客户端提供的租户身份。

6. 仅绑定所需资源

• Cloudflare：为每个租户配置遵循最小权限原则的绑定（数据库/存储/受限平台 API），不使用共享全局状态。将新增绑定视为显式变更；重新部署以授予访问权限。
• Vercel：使用 Edge Config 存储租户配置（域名映射、功能标志、方案信息）。使用 Vercel SDK（@vercel/sdk）管理域名。数据库连接按 tenant_id 限定范围，或每个租户使用独立数据库（Neon）。

7. 支持自定义域名

• 提供 DNS 目标、验证所有权、存储映射，并按主机名路由。
• Cloudflare：使用 Cloudflare for SaaS 自定义主机名 + 托管证书。参见 cloudflare-platform.md。
• Vercel：通过 @vercel/sdk 使用 Vercel Domains API，以编程方式执行域名增删改查（CRUD）+ 自动配置 Let's Encrypt SSL。通配符子域名需要使用 Vercel 名称服务器。参见 vercel-domains.md。
• 自定义域名会将声誉转移给租户，并自然形成用户群体（在平台域名上较随意的用户，以及使用自有域名的认真用户）。

8. 提供按租户区分的静态文件

• robots.txt、sitemap.xml、llms.txt 必须因租户而异；不要从 /public 提供。
• Cloudflare：在租户 Worker 中生成按租户区分的响应。
• Vercel：使用按域名段划分的路由处理程序。请参阅 vercel-platform.md。

9. 将限制作为套餐展示

• 将平台限制映射到定价套餐；在 API 和 UI 中公开。
• 不要在请求中运行长时间任务；使用队列/工作流。
• 有关限制快照和来源链接，请参阅 limits-and-quotas.md。
• 在确定最终架构或定价前，重新检查官方文档中的限制。

10. 让 API 成为产品本身

• 所有功能都通过 HTTP 运作；UI 用于运维、事件处理和账单管理。
• 平台逻辑应留在路由层（分发 Worker 或 Middleware）；租户内容负责处理请求。
• 如果某项功能只能在 UI 中使用，就说明平台边界泄漏了。

11. 扩展时不破坏边界

• 将队列/工作流/容器作为可选模式添加。
• 明确路由，并维持隔离。

交付内容

• 平台选择理由：说明选择 Cloudflare 或 Vercel 的原因
• 租户识别策略：子域名、自定义域名或基于路径
• 域名映射：品牌域名与租户域名、PSL 方案、自定义域名流程
• 隔离方案：每租户一个 Worker，或使用租户范围限定的共享应用
• 路由方案：主机名查询、分发/重写逻辑、回退行为
• 租户上下文流：租户身份如何通过 Middleware/headers/DB 传递
• 绑定/配置矩阵：每个租户的功能和数据访问权限
• 限制到定价的映射：各套餐的 CPU/内存/请求/域名预算
• API 范围和运维 UI 范围

需加载的参考资料

• 始终加载 PSL 提交和 Cookie 隔离指南：psl.md
• 如果平台是 Cloudflare，加载平台原语和路由资料：cloudflare-platform.md
• 如果平台是 Vercel，加载平台原语和路由资料：vercel-platform.md
• 如果平台是 Vercel，加载域名管理和 SSL 资料：vercel-domains.md
• 最后加载平台限制和套餐映射资料：limits-and-quotas.md

提交前检查清单

• 已选择平台，并记录清晰的理由
• 租户工作负载已移出品牌域名；已确定 PSL 决策和时间表
• 已选择租户识别策略；已定义自定义域名升级路径
• 已定义隔离模型：每租户一个 Worker（Cloudflare），或共享应用 + RLS（Vercel）
• 路由权威且不感知租户；分发或 Middleware 负责处理所有流量
• 租户上下文仅通过 Middleware/平台 Worker 传递；不信任客户端提供的身份
• 已定义自定义域名接入流程，包括 DNS 目标、验证和证书配置
• 按租户区分的静态文件（robots.txt、sitemap.xml）由动态方式提供
• 限制与计费挂钩；API 与 UI 保持一致
• 已从官方文档刷新限制快照，并在规划备注中注明日期