multi-tenant-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Multi-Tenant Platform Architecture (Cloudflare · Vercel)

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

Workflow (order matters)

工作流程（顺序至关重要）

Choose platform

Cloudflare: Workers for Platforms + dispatch namespaces for per-tenant code isolation; best when tenants run untrusted code or you need edge-first compute with D1/KV/DO primitives.
Vercel: Next.js App Router + Middleware for shared-app multi-tenancy; best when tenants share one codebase and you need ISR, React Server Components, and managed deployment.
Pick one; do not mix hosting. The remaining steps apply to both with platform-specific guidance in reference files.
After choosing, load only the references for that platform unless you are explicitly comparing Cloudflare vs Vercel.

Choose domain strategy

Use a dedicated tenant domain (separate from the brand domain) for all subdomains/custom hostnames. Reputation does not isolate; a phishing site on
```
random.acme.com
```
damages the whole domain.
Register a separate TLD for tenant workloads (e.g.
```
acme.app
```
for tenants,
```
acme.com
```
for brand).
Consider PSL for browser cookie isolation; it does not protect reputation. See psl.md.
Start PSL submission early; review can take weeks.

Choose tenant identification strategy

Subdomain-based:
```
tenant.yourdomain.com
```
. Requires wildcard DNS. Simplest for many tenants.
Custom domain: Tenant brings own domain, CNAMEs to your platform. Best for serious/paying tenants.
Path-based:
```
yourdomain.com/tenant-slug
```
. No DNS/SSL per tenant, but limits branding and complicates cookie isolation.
Pick one primary strategy; offer custom domain as an upgrade path.

Define isolation model

Cloudflare: Prefer per-tenant Workers for untrusted code (Workers for Platforms dispatch namespaces). Avoid shared-tenant branching unless you fully control code and data.
Vercel: Single shared Next.js app with
```
tenant_id
```
scoping. Middleware resolves tenant from hostname; all data queries include tenant context. Use Postgres RLS for defence-in-depth.

Route traffic deterministically

Cloudflare: Platform Worker owns routing; hostname -> tenant id -> dispatch namespace -> tenant Worker. 404 when no mapping exists.
Vercel: Next.js Middleware extracts hostname, rewrites URL to
```
/domains/[domain]
```
dynamic segment. Edge Config for sub-millisecond tenant lookups. 404 when no mapping exists.
Tenants never control routing or see each other on either platform.

Pass tenant context through the stack

Cloudflare: Platform Worker resolves tenant and injects headers or bindings before dispatching to tenant Worker.
Vercel: Middleware sets
```
x-tenant-id
```
,
```
x-tenant-slug
```
,
```
x-tenant-plan
```
on forwarded request headers. Server Components read via
```
headers()
```
; API routes read from request headers.
Middleware/platform Worker is the single authority; never trust client-supplied tenant identity.

Bind only what is needed

Cloudflare: Least-privilege bindings per tenant (DB/storage/limited platform API), no shared global state. Treat new bindings as explicit changes; redeploy to grant access.
Vercel: Edge Config for tenant config (domain mappings, feature flags, plan info). Vercel SDK (
```
@vercel/sdk
```
) for domain management. Database connection scoped by
```
tenant_id
```
or database-per-tenant (Neon).

Support custom domains

Provide DNS target, verify ownership, store mapping, and route by hostname.
Cloudflare: Cloudflare for SaaS custom hostnames + managed certs. See cloudflare-platform.md.
Vercel: Vercel Domains API via
```
@vercel/sdk
```
for programmatic domain CRUD + automatic Let's Encrypt SSL. Wildcard subdomains require Vercel nameservers. See vercel-domains.md.
Custom domains shift reputation to the tenant and create natural user segments (casual on platform domain, serious on own domain).

Serve per-tenant static files

```
robots.txt
```
,
```
sitemap.xml
```
,
```
llms.txt
```
must vary by tenant; do not serve from
```
/public
```
.
Cloudflare: Generate per-tenant responses in the tenant Worker.
Vercel: Use route handlers per domain segment. See vercel-platform.md.

Surface limits as plans

Map platform limits to pricing tiers; expose in API + UI.
Do not run long jobs in requests; use queues/workflows.
See limits-and-quotas.md for limits snapshots and source links.
Re-check limits in official docs before final architecture or pricing decisions.

Make the API the product

Everything works over HTTP; UI is for ops/incident/billing.
Platform logic stays in the routing layer (dispatch Worker or Middleware); tenant content serves requests.
If it only works in the UI, the platform is leaking.

Extend without breaking boundaries

Add queues/workflows/containers as optional modes.
Keep routing explicit and isolation intact.

选择平台

Cloudflare：使用Workers for Platforms + 调度命名空间（dispatch namespaces）实现租户级代码隔离；最适合租户运行不可信代码，或需要基于边缘的计算并使用D1/KV/DO原语的场景。
Vercel：采用Next.js App Router + Middleware实现共享应用多租户模式；最适合租户共享单一代码库，且需要ISR、React Server Components和托管部署的场景。
二选一，不要混合托管。后续步骤适用于两者，参考文件中会提供平台特定的指导。
选定平台后，仅加载该平台的参考文件，除非你明确要对比Cloudflare和Vercel。

选择域名策略

为所有子域名/自定义主机名使用独立的租户域名（与品牌域名分离）。域名信誉无法隔离；
```
random.acme.com
```
上的钓鱼网站会损害整个域名的信誉。
为租户工作负载注册独立的顶级域名（TLD），例如
```
acme.app
```
用于租户，
```
acme.com
```
用于品牌官网。
考虑使用公共后缀列表（PSL）实现浏览器Cookie隔离，但它无法保护域名信誉。详见psl.md。
尽早提交PSL申请；审核可能需要数周时间。

选择租户识别策略

基于子域名：
```
tenant.yourdomain.com
```
。通配符DNS是必需的。适用于大量租户的最简单方案。
自定义域名：租户自带域名，通过CNAME指向你的平台。最适合付费/核心租户。
基于路径：
```
yourdomain.com/tenant-slug
```
。无需为每个租户配置DNS/SSL，但会限制品牌化并增加Cookie隔离的复杂度。
选择一种主要策略，将自定义域名作为升级选项提供。

定义隔离模型

Cloudflare：对于不可信代码，优先使用租户级Workers（Workers for Platforms调度命名空间）。除非你完全控制代码和数据，否则避免共享租户分支。
Vercel：单一共享Next.js应用，通过
```
tenant_id
```
进行范围限定。Middleware从主机名解析租户信息；所有数据查询都包含租户上下文。使用Postgres RLS（行级安全）实现纵深防御。

确定性路由流量

Cloudflare：平台Worker负责路由；主机名 -> 租户ID -> 调度命名空间 -> 租户Worker。无映射时返回404。
Vercel：Next.js Middleware提取主机名，将URL重写为
```
/domains/[domain]
```
动态路径段。使用Edge Config实现亚毫秒级租户查询。无映射时返回404。
在两个平台上，租户都无法控制路由，也无法看到其他租户的存在。

在技术栈中传递租户上下文

Cloudflare：平台Worker解析租户信息，在调度到租户Worker之前注入请求头或绑定信息。
Vercel：Middleware在转发请求头中设置
```
x-tenant-id
```
、
```
x-tenant-slug
```
、
```
x-tenant-plan
```
。服务端组件通过
```
headers()
```
读取；API路由从请求头读取。
仅信任Middleware/平台Worker作为租户身份的唯一权威；绝不信任客户端提供的租户身份。

仅绑定必要资源

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

支持自定义域名

提供DNS目标、验证所有权、存储映射关系，并按主机名路由。
Cloudflare：使用Cloudflare for SaaS自定义主机名 + 托管证书。详见cloudflare-platform.md。
Vercel：通过
```
@vercel/sdk
```
调用Vercel Domains API实现程序化域名增删改查 + 自动Let's Encrypt SSL。通配符子域名需要使用Vercel域名服务器。详见vercel-domains.md。
自定义域名将信誉风险转移给租户，并自然划分用户群体（普通租户使用平台域名，核心租户使用自有域名）。

提供租户级静态文件

```
robots.txt
```
、
```
sitemap.xml
```
、
```
llms.txt
```
必须按租户动态生成；不要从
```
/public
```
目录直接提供。
Cloudflare：在租户Worker中生成租户专属响应。
Vercel：按域名路径段使用路由处理器。详见vercel-platform.md。

将限制与方案关联

将平台限制映射到定价层级；在API和UI中同步展示。
不要在请求中运行长时间任务；使用队列/工作流处理。
详见limits-and-quotas.md中的限制快照和官方链接。
在最终确定架构或定价决策前，务必重新核对官方文档中的限制信息。

以API为核心构建产品

所有功能均通过HTTP API实现；UI仅用于运维/事件处理/计费管理。
平台逻辑保留在路由层（调度Worker或Middleware）；租户内容负责处理请求。
如果某项功能仅能在UI中使用，说明平台设计存在疏漏。

扩展时不打破边界

可添加队列/工作流/容器作为可选模式。
保持路由规则明确，隔离机制完整。

Deliverables

交付物

Platform choice rationale: Cloudflare vs Vercel with justification
Tenant identification strategy: subdomain, custom domain, or path-based
Domain map: brand vs tenant domain, PSL plan, custom domain flow
Isolation plan: per-tenant Workers or shared-app with tenant scoping
Routing plan: hostname lookup, dispatch/rewrite logic, fallback behavior
Tenant context flow: how tenant identity propagates through middleware/headers/DB
Binding/config matrix: per-tenant capabilities and data access
Limits-to-pricing map: CPU/memory/request/domain budgets per tier
API surface + ops UI scope

平台选择依据：Cloudflare与Vercel的对比及选型理由
租户识别策略：子域名、自定义域名或基于路径的方案
域名映射：品牌域名与租户域名的区分、PSL方案、自定义域名流程
隔离方案：租户级Workers（Cloudflare）或共享应用+RLS（Vercel）
路由方案：主机名查询、调度/重写逻辑、 fallback行为
租户上下文流转：租户身份如何通过Middleware/请求头/数据库传递
绑定/配置矩阵：租户级能力与数据访问权限
限制与定价映射：各层级的CPU/内存/请求/域名配额
API接口范围 + 运维UI功能边界

References to load

需加载的参考文件

Always load PSL submission and cookie isolation guidance: psl.md
If platform is Cloudflare, load platform primitives and routing: cloudflare-platform.md
If platform is Vercel, load platform primitives and routing: vercel-platform.md
If platform is Vercel, load domain management and SSL: vercel-domains.md
Load platform limits and plan mapping last: limits-and-quotas.md

始终加载PSL提交与Cookie隔离指导：psl.md
若选择Cloudflare平台，加载平台原语与路由规则：cloudflare-platform.md
若选择Vercel平台，加载平台原语与路由规则：vercel-platform.md
若选择Vercel平台，加载域名管理与SSL配置：vercel-domains.md
最后加载平台限制与方案映射：limits-and-quotas.md

multi-tenant-architecture

Original

Translation

Multi-Tenant Platform Architecture (Cloudflare · Vercel)

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

Workflow (order matters)

工作流程（顺序至关重要）

Deliverables

交付物

References to load

需加载的参考文件

Pre-commit checklist

提交前检查清单