add-custom-domain

添加自定义域名

为 Temps 项目添加自定义域名，并自动启用 HTTPS。此技能通过 CLI 完成整个流程；人工操作方式是在控制面板中选择 项目 → 域名 → 添加域名。

使用时机

用户希望使用自己的域名（例如 app.example.com）提供 Temps 项目服务，并配置 SSL 证书，而不是使用自动分配的子域名。

前提条件

• Temps CLI 已通过身份验证。请检查；如有需要，请登录用户的实例（login 是顶级命令，实例 URL 是位置参数）：

  bunx @temps-sdk/cli whoami || bunx @temps-sdk/cli login "<instance_url>"
  

• 用户知道要添加的域名以及它所属的项目。
• 用户可以编辑该域名的 DNS（或者已在 Temps 中连接 DNS 提供商，以用于 DNS-01 / 通配符域名）。

首先：是否已有隧道覆盖该域名？

如果应用运行在配置了入口隧道的 Worker 上（ADR 058），该域名无需 DNS 记录或证书：Temps 会创建记录，隧道提供商会提供 HTTPS。请先检查：

bunx @temps-sdk/cli tunnels list --json
bunx @temps-sdk/cli tunnels explain app.example.com --json

如果 explain 在 candidates 中列出了隧道（其 domain 为 example.com 或该名称的父域名）：

1. 将该名称关联到环境（见下方步骤 3，使用相同的命令）。不要为其创建证书：隧道流量以普通 HTTP 的形式到达 Temps，而本地证书会使代理将其重定向到 HTTPS。
2. 如果隧道只发布指定名称，或有多个隧道覆盖该域名，请显式配置路由：

   bunx @temps-sdk/cli tunnels route app.example.com --tunnel <tunnel-id>
   

3. 一分钟内，tunnels explain app.example.com 应报告 published。如果没有，detail 会说明需要修复的内容（最常见的情况是：尚无部署在 Worker 上的应用提供该名称）。

Cloudflare 的免费证书覆盖该区域及其下一级域名：app.example.com 可以使用，a.b.example.com 则需要高级证书。

还没有隧道，但该域名是已连接的 Cloudflare DNS 提供商中的区域，且用户希望使用隧道？请在应承载该域名的 Worker 上创建隧道（每个 Worker 都必须允许入口流量：在 Worker 上运行 temps agent ingress delegated）：

bunx @temps-sdk/cli dns-providers list --json   # the Cloudflare provider id
bunx @temps-sdk/cli tunnels workers --json      # worker ids
bunx @temps-sdk/cli tunnels create --name example-com --dns-provider <id> \
  --domain example.com --node <worker-id> [<worker-id>...]

否则，请使用证书流程：

步骤

1. 确定项目。 如果用户提供了名称但没有 ID，请列出项目并确认对应项：

   bunx @temps-sdk/cli projects list --json
   

   记下目标项目的数字 id。在下文中将其用作 <project-id>。

2. 在用户的 DNS 提供商处创建 DNS 记录，使域名指向 Temps 服务端。明确告知用户要添加哪些内容（除非已在 Temps 中连接 DNS 提供商，否则你无法代为创建）：

   • 子域名（app.example.com）：添加 A 记录，名称为 app，值为服务端的公网 IP。也可以使用指向服务端主机名的 CNAME。
   • 根域名（example.com）：添加 A 记录，名称为 @，值为服务端的 IP。（区域根目录不允许使用 CNAME。）
   • 如果用户使用 Cloudflare，请在证书签发期间将记录设为仅 DNS（灰色云朵），这样 Temps 的 Let's Encrypt 验证不会经过代理。

3. 将域名添加到项目。 默认使用 HTTP-01 验证，由系统自动处理：

   bunx @temps-sdk/cli custom-domains create --project-id <project-id> -d app.example.com -y
   

   • 根域名 + 已连接 Cloudflare/其他提供商，或无法访问 80 端口：改用 DNS-01（见下方“通配符域名”）——请先在设置 → DNS 提供商中确认已连接 DNS 提供商。

4. 通配符域名（*.example.com）需要 DNS-01 验证，并且必须连接 DNS 提供商。确认提供商已连接，然后以相同方式添加通配符域名：

   bunx @temps-sdk/cli custom-domains create --project-id <project-id> -d "*.example.com" -y
   

   Temps 会通过提供商自动创建 _acme-challenge TXT 记录。

验证

bunx @temps-sdk/cli custom-domains list --project-id <project-id>

DNS 传播且证书签发后，域名状态应变为活动（HTTP-01 通常不到一分钟）。你可以单独确认 DNS：

dig +short app.example.com A

如果域名一直处于待处理状态：请确认 DNS 记录解析到服务端、80 端口可访问（HTTP-01），并且在证书签发期间 Cloudflare 代理已关闭。证书会在到期前约 30 天自动续期。

相关内容

• 控制面板路径：项目 → 域名 → 添加域名
• 文档：https://temps.sh/docs/add-a-custom-domain
• CLI 命令组：bunx @temps-sdk/cli custom-domains --help
• 隧道：bunx @temps-sdk/cli tunnels --help。控制面板：域名 → 添加域名 如果有隧道覆盖该名称，则会显示“通过隧道 …”；从 Cloudflare DNS 提供商导入区域时， 会显示“通过 Cloudflare Tunnel”。
• 完整的 CLI 参考：temps-cli 技能涵盖全部 440 多条 bunx @temps-sdk/cli 命令。