设置自定义域名

安装与配置

在执行任何步骤之前，请阅读开始之前 和终端基础知识。这些说明假设您在 VS Code 中打开了完整的 supastack monorepo；它的根 package.json 标记存储库根。在 pnpm 命令中，工作区包是应用程序或共享代码文件夹；在产品中，工作空间是团队的数据容器和安全边界。 corepack pnpm --filter ... 从 monorepo 选择一个包，同时从其根运行命令。如果您仅打开同步的移动或桌面文件夹，则它不包含 Web 后端、Docker 设置或根脚本：从此 monorepo 或可访问的托管服务器运行后端，并使用平台文件夹自己的脚本。环境变量是存储在本地 .env 文件或托管仪表板中的命名设置；更改后重新启动相关应用程序，并将服务器机密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。

1. 打开 apps/web/.env.local 并使用 CUSTOM_DOMAINS_PROVIDER=local 预览没有 DNS 更改的域屏幕。

2. 对于真实的客户主机名，请使用您自己的区域、仅限于该区域的 API 令牌以及 CNAME 目标配置 Cloudflare for SaaS；在 Web 主机上输入仅用于服务器的值，而不是在浏览器中输入。

3. 使用 corepack pnpm --filter @supastack/web dev 运行 Web，并以工作区所有者/管理员身份打开设置 → 域。预期：本地适配器立即激活测试域； Cloudflare 适配器等待显示的 DNS 记录。

将 CUSTOM_DOMAINS_PROVIDER=cloudflare 设置为 CLOUDFLARE_API_TOKEN、CLOUDFLARE_ZONE_ID 和 CUSTOM_DOMAIN_CNAME_TARGET。 API 令牌需要 SSL 和证书：区域的编辑权限（自定义主机名 API 位于 /zones/{zone_id}/custom_hostnames 下）。 CNAME 目标是 Cloudflare 区域中的主机名（例如customers.example.com），可解析为您部署的应用程序。

在区域中添加一条 DNS 记录，将 CNAME 目标指向您的源（Cloudflare 中 SaaS 术语的后备源）。 Cloudflare 为每个自定义主机名颁发一个 DCV TXT 记录以及一个可选的所有权 TXT 记录；设置屏幕向客户准确显示要创建哪些记录。

对于本地开发，请使用 CUSTOM_DOMAINS_PROVIDER=local，它将每个主机名标记为立即与目标客户处于活动状态。localhost。 CUSTOM_DOMAINS_PROVIDER=off（默认值）隐藏该部分的控件。

CUSTOM_DOMAINS_PROVIDER=cloudflare
CLOUDFLARE_API_TOKEN=cf_token_with_ssl_edit
CLOUDFLARE_ZONE_ID=zone_id
CUSTOM_DOMAIN_CNAME_TARGET=customers.example.com

要复制的命令

按照注释查看命令在哪个文件夹中运行。如果标记了两个终端，请打开两个终端窗口，并在使用第二个命令时保持第一个命令运行。

corepack pnpm --filter @supastack/web dev

实现流程

工作区所有者和管理员在“设置”→“域”下管理域（每个工作区五个）。客户将其主机名的 CNAME 记录指向 CNAME 目标，添加显示的 TXT 记录以进行所有权和证书验证，然后按刷新状态。一旦 Cloudflare 报告主机名处于活动状态，它就会成为该部署上的身份验证的可信来源，并且工作区名称/徽标会成为该主机名上应用程序镶边的品牌。

大多数 DNS 提供商的 Apex（根）域不能是 CNAME — 客户应使用 Portal.example.com 等子域或具有 CNAME 扁平化功能的提供商。 Cookie 的范围仅限于每个主机，因此客户域是单独的登录；跨自定义域的单点登录超出了范围。

验证与排障

如果 Cloudflare 保持待处理状态，请将客户的 CNAME 和 TXT 记录与域卡上显示的确切值进行比较，并留出 DNS 时间进行更新。当 DNS 提供商无法展平根域 CNAME 时，请使用子域。如果菜单不存在，请检查该功能是否已启用以及登录用户是否是工作区所有者或管理员。

长时间等待通常意味着客户的 CNAME 丢失或仍在传播 - 重新检查域卡上显示的 DNS 记录。移动或失败状态意味着 Cloudflare 无法再解析该区域的主机名；删除并重新添加它。验证数据存储为提供程序 JSON，因此未来的 Cloudflare 验证形状不需要更改架构。