Web 应用的自定义域名设置：DNS、SSL 与切换

自定义域名会改变什么（以及可能出的问题）

自定义域名不仅仅是更好看的 URL。从平台地址（例如在 Koder.ai 平台子域下的应用）切换到自己的域名时，浏览器和网络会把它当成不同的网站。这会影响路由、安全性以及用户会话的行为。

一旦切换到自定义域名，以下几项会立即发生变化：

• DNS 路由：用户不再访问旧主机名，而是开始访问 DNS 指向的目标。
• TLS/SSL：证书必须匹配新的主机名，并且在真实用户到达前应当生效。
• 重定向：你要决定用户是落到 www 还是 apex 域，并且需要统一的 HTTP 到 HTTPS 规则。
• Cookies 与会话：Cookie 是按域作用的。为 old-platform.example 设置的登录 Cookie 不会自动在 app.yourdomain.com 上生效。
• 缓存与传播：DNS 解析器与浏览器会缓存结果，所以并不是每个人都会在同一时刻切换。

短暂的中断通常来自于时序问题。DNS 可能先把流量发到新主机，而 SSL 还没准备好，导致浏览器警告；或者相反：SSL 已就绪，但很多用户仍访问旧地址因为他们的 DNS 缓存尚未过期。

重定向也会以微妙的方式破坏登录。改变主机名的重定向（apex 到 www 或反之）如果未正确处理会丢失 Cookie。若身份提供方的回调 URL 仍指向旧域名，也会导致失败。

低风险切换意味着为重叠做计划：让旧 URL 继续可用，先并行启用新域，在可预期的时刻切换流量，并保证回滚只需把 DNS 改回去就行。

在动手改 DNS 之前先决定域名与主机名

在改动任何东西之前，把你希望用户输入的确切名称，以及哪些名称应静默重定向，写下来。大多数“为什么只有一部分生效”的情况，都是因为团队没有就唯一的主机名达成一致。

先做一个重要选择：以 apex（example.com）还是 www（www.example.com）作为主要主机。两者都可行，但请选一个并把另一个当作重定向来源。这对 Cookie 也很重要：当应用仅在一个一致的主机上运行时，会话最容易管理。

接着决定现在需要哪些子域，哪些可以以后再加。常见模式是把 app.example.com 用于 Web 应用、api.example.com 用于 API，之后再增加 admin.example.com 或 assets.example.com。如果在像 Koder.ai 这样的平台注册自定义域，这些选择会直接映射到你需要为其验证 SSL 的主机名以及在 DNS 中要指向的目标。

确认谁真正管理 DNS

很多人只在注册商买域名，但 DNS 可能托管在别处。确认今天在哪里编辑记录、谁有访问权限，以及是否有自动化在管理变更（公司 IT、代理商或某个托管 DNS 提供商）。如果你不能登录查看当前记录，请先解决这个问题再继续。

同时审计已有的域名用途。邮件是经典陷阱：删除或覆盖记录会中断邮件投递。

在继续之前，把以下决策写下来：

• 主要主机名（apex 或 www）及重定向方向
• 现在必须的子域（app、api、admin）与后续计划
• DNS 托管位置和谁能发布变更
• 现有关键记录（MX、SPF、DKIM、DMARC、验证用 TXT）
• Cookie 与认证期望（单一主机或跨子域共享）

如果市场或运营已经在 example.com 上运行邮件，添加应用所需记录时别修改邮件相关记录。

你会用到的 DNS 记录与它们的重要性

在自定义域迁移中，最大风险通常不是应用本身，而是一次错误的 DNS 改动把流量指向空处、破坏邮件或让 SSL 验证失败。

核心记录（A、CNAME 及其相关）

A 记录 将名称指向一个 IP 地址。通俗地说：“把人发到这个服务器。”当你的提供方给出固定 IP 时，常用于 apex（example.com）。

CNAME 记录 将一个名称指向另一个名称。通俗地说：“把这个名字当作那个主机名的别名。”常见用于 www.example.com 指向某个平台主机名。

许多 DNS 提供商还支持 apex 的 ALIAS/ANAME，它在行为上像 CNAME，但适用于 example.com。如果你的提供商支持，使用它能更容易地管理移动的目标而不必频繁改 IP。

一个简单的心理模型：

• A: 名称 → IP（直接）
• CNAME: 名称 → 名称（别名）
• TXT: 名称 → 文本（验证与策略）
• MX: 名称 → 邮件服务器（除非你有意，否则别动）

TXT 记录：验证、SSL 与邮件安全

你常会为域名所有权检查添加 TXT 记录（平台验证）或用于 SSL 的验证令牌（某些 CA 使用 TXT 验证）。TXT 也用于邮件策略，比如 SPF。不小心删除或覆盖已有的 SPF TXT 会破坏邮件接收。

TTL：你的“变更速度”旋钮

TTL 控制其他系统缓存 DNS 答案的时间。切换前一天降低你计划更改的记录的 TTL（通常设为 300 到 600 秒）。一切稳定后再把它调回以减少查询负载。

避免覆盖现有记录，并记录回滚方案

在编辑前导出或截图当前区文件。把你将更改的每一条记录、原值、新值和 TTL 记录下来。如果出问题，回滚即恢复这些先前的值。

这在你的域已经有 MX、DKIM 或其他邮件相关 TXT 时尤为重要。

SSL 签发：验证方式、时序与覆盖范围

SSL（浏览器地址栏的锁）加密浏览器与应用之间的流量。现代浏览器和很多 API 默认期望 HTTPS。没有 HTTPS 会出现警告、请求被阻止，某些功能（service workers、地理位置、支付流程）也可能失效。

要签发证书，证书颁发机构必须验证你对域名的控制权。常见的验证方法有 HTTP 验证和 DNS TXT 验证：

• HTTP 验证 在你应用上的某个 URL 放置临时文件或返回特定响应。
• DNS TXT 验证 在 DNS 区中添加一个 TXT 记录。

当你使用 CDN 或者应用在新域上尚未可达时，DNS 验证通常更方便。

证书在哪里签发取决于架构。有的团队在主机栈上直接签发证书，有的在 CDN 层签发，也有的平台在支持自定义域名时代为处理证书（例如 Koder.ai 可以在域名设置过程中管理证书）。关键是要弄清楚谁负责证书的全生命周期，包括续期。

时序与重试

证书签发并不总是即时的。DNS 传播、验证检查与频率限制都可能让过程变慢。为重试留出时间，不要把切换安排在最后一刻。

一个实用的时序计划：

• 在切换前一天降低 DNS TTL，让更改更快生效。
• 及早添加验证记录（DNS TXT 或 HTTP 令牌）。
• 等到证书显示为已签发并覆盖所有主机名。
• 只有在证书就绪后才把流量指向新目标。

覆盖范围：确保证书包含所有主机名

证书必须覆盖用户会访问的每个主机名。检查 SAN（Subject Alternative Names）列表。如果你的应用会在 example.com 和 www.example.com 两者上可用，证书必须包含它们两者。

通配符证书（如 *.example.com）可以覆盖许多子域，但不包含 apex（example.com）。

举例：如果你只为 www.example.com 签发证书，直接访问 example.com 的用户仍会看到警告，除非在另一个层级上对 apex 做了带有效证书的重定向。

重定向规则：www、apex、HTTP 到 HTTPS 与安全默认值

重定向听起来简单，但大多数域名问题都在这里出现：循环、混合内容、以及用户因在主机间来回跳转而丢失登录状态。

选定一个规范主机并坚持：要么 www.example.com 要么 example.com（apex）。另一个入口点应重定向到规范主机，这样 Cookie、会话与 SEO 信号保持一致。

安全默认：

• 一个规范主机，从另一个主机用单一 301 重定向到它
• 对每个请求从 http:// 做 301 到 https://
• 在重定向时保留完整路径与查询字符串（深度链接必须继续工作）
• 只做一次重定向（避免像 http → https → www 这样的链式重定向）

对于 HTTP 到 HTTPS，避免会让用户来回跳的规则。防止循环最简单方法是基于请求的实际情况做判断。如果你的应用位于代理或 CDN 之后，配置它以信任转发头（例如表明原始协议是 HTTP 的头）。否则应用可能认为每个请求都是 HTTP，从而持续重定向。

迁移期间，保留旧路径的可用性。如果你要更改路由（例如把 /login 改为 /sign-in），请为这些路径添加明确重定向。不要指望把所有请求统一重定向到首页，这会破坏书签和已有链接。

初期别启用 HSTS。如果启用过早，而之后还需要在验证或排错时提供 HTTP，浏览器可能会拒绝。等到 HTTPS 稳定且子域覆盖确认后再启用。

在不影响所有人的情况下测试重定向，可使用临时测试主机名，尝试一些真实深度链接（包括认证页），并运行能显示每一步重定向的命令行请求以查看最终目的地。

逐步低风险切换计划（无停机）

一个安全的切换主要靠时序。你要在真实用户被发送过去之前准备并测试好新域，并且希望 DNS 更改能迅速传播以免在事故中被动等待。

1）在触碰生产 DNS 前准备并测试

提前降低你将修改的记录的 DNS TTL（如果可能就在前一天），然后等待旧 TTL 窗口期过完。

接着在你的主机/提供商中添加自定义域并完成所需的验证。如果你使用像 Koder.ai 这样的平台，先在那里添加域名以便平台确认所有权并准备路由。

尽早签发 SSL。证书可能需要几分钟或更长时间来验证，你不希望在切换时再等待这步。

在域名公开之前做一次私有测试：以不依赖公共 DNS 的方式访问新端点（例如在本机临时 hosts 条目中），确认站点能通过 HTTPS 正常加载并使用正确的证书。

2）分小步可逆地切换

分阶段方法能让你在发现问题时快速停止：

• 提前降低 TTL，然后等待直至之前的 TTL 周期彻底过期。
• 在主机端完成域名验证并内部确认域名指向正确的应用。
• 在切换前确认每个要提供的主机名都已启用 SSL。
• 以受控方式修改 DNS：如果可行，先改一个子域、某个地区或限量受众路由。
• 在观察流量与错误率稳定后再让旧域继续重定向。

如果无法在 DNS 级做真正的灰度，你仍可先只切换一个主机名（例如先切 www），把 apex 留住，等有信心再做全量切换。

3）在头脑清醒时就写好回滚方案

把会回退的具体内容写下来（哪些记录、哪些值），以及由谁负责回滚。回滚通常就是把 DNS 恢复到原样。

确保旧设置仍有效（包括旧域上的 SSL），这样用户可以在你修复新路径时平滑回退。

避免切换后 Cookie、会话与认证中断

域名变化不只是 DNS 的改动。对很多应用来说，“已登录”状态依赖于浏览器按主机名绑定的 Cookie。如果从旧主机切换到新主机，浏览器可能不会再发送旧 Cookie，应用看起来就像把所有人都登出了一样。

Cookie 设置通常是罪魁祸首：

• Domain 决定哪些主机名能接收 Cookie。为 app.old.com 设置的 Cookie 不会发送到 app.new.com。为 .example.com 设置的 Cookie 则能在 app.example.com 与 www.example.com 间共享。
• Path 限定 Cookie 发送的路径，如果设置过窄（如 /api），前端可能拿不到它。
• Secure 表明 Cookie 仅通过 HTTPS 发送，迁入全 HTTPS 后 HTTP 请求将不带该 Cookie。
• SameSite 会影响跨站重定向与嵌入式流程。Lax 往往够用，但某些 SSO 或支付重定向可能需要 None 并配合 Secure。

为降低风险，规划一个短期过渡期让两个域都能工作。让旧主机继续响应并谨慎重定向，同时允许在新域刷新会话。如果可能，使用共享会话存储，这样命中任一主机的用户都能被识别。

如果使用 SSO 或 OAuth，请在切换前更新设置：回调 URL、允许的来源以及任何“受众”或重定向 URI 的白名单。否则身份认证可能在提供方成功，但回到应用时失败。

优先测试那些容易出问题的流程：注册（及邮件验证）、登录/登出、密码重置、结账或支付回调、多标签页会话等。

例如：把 www.example.com 重定向到 example.com 时，确保 Cookie 设置为 .example.com（或始终使用单一主机）。否则用户在主机间来回就会丢失会话。

导致中断或奇怪行为的常见错误

大多数域名问题并不是“神秘的互联网问题”，而是 DNS、证书与重定向规则间的小不匹配，只有真实用户访问时才显现。

一个常见陷阱是 apex（example.com）。很多 DNS 提供商不允许在 apex 使用真正的 CNAME。如果尝试这样做，可能会静默失败、解析不一致，或者仅在某些网络上出现问题。使用你的 DNS 主机支持的记录类型（通常是 A/AAAA，或 ALIAS/ANAME 风格的记录）。

另一个常见的停机原因是在 SSL 尚未就绪时就改 DNS。用户到达新主机，页面加载后浏览器却因证书缺失或只覆盖部分主机名而阻止访问。实践中，通常希望证书同时覆盖 example.com 与 www.example.com，即便计划将其中一个重定向到另一个。

会导致中断或异常行为的常见错误：

• 在没有提前降低 TTL 的情况下更改 DNS，然后需要等几个小时让旧答案过期
• 保留会造成循环的重定向规则（www 到 apex，apex 又回到 www），或在某处强制 HTTP 而在另一处强制 HTTPS
• 硬编码 http:// 的静态资源导致混合内容，触发浏览器警告与功能故障
• 忽视非 Web 的 DNS 记录，尤其是 MX 与 TXT，导致邮件与域名验证失败
• 只测试单一浏览器，忽略其他用户可能遇到的缓存 HSTS 或 Cookie 个性化差异

一个快速的健全性检查：通过 HTTPS 打开两个主机名（www 与 apex），登录、刷新，并确认地址栏不会回退到 HTTP。

如果你在像 Koder.ai 这样的平台注册自定义域，确认自定义域已连接且 SSL 已签发后再修改生产 DNS，并准备好回滚选项以避免错误的重定向或记录长时间生效。

切换前、切换中与切换后的快速清单

冷静的切换主要靠准备工作。目标很简单：用户保持登录、Cookie 能正常工作，如有问题可以快速回滚。

切换前

在流量仍指向旧域时完成这些工作，最好预留一天以便 DNS 更改有时间稳定：

• 降低你将修改的 DNS 记录的 TTL，并记录当前值以便快速恢复。
• 记录你将提供的每个主机名（apex、www、api 等），并选择 SSL 验证方法（DNS 或 HTTP）。
• 在预发布环境测试重定向：HTTP → HTTPS、www → apex 或反向，确保只使用一个规范主机。
• 更新依赖精确 URL 的认证设置：OAuth 回调 URL、允许来源、Cookie 域设定及任何 SSO 配置。
• 决定切换期间谁负责监控（日志、可用性检测、支持邮箱）并设定短时变更窗口。

切换中与切换后

当你翻转 DNS 时，把第一小时当作一次演练来对待。关注真实用户流程，不只看状态面板。

• 切换中：监控 4xx/5xx 峰值、重定向循环与登录失败（尤其是“invalid redirect URI”或突然的会话中断）。
• 切换后：在多个浏览器确认证书链有效，重要页面以 HTTPS 加载且无混合内容。
• 切换后：验证规范主机行为（地址栏只显示一个主机名）并确认关键 Cookie 已设置并被发送。
• 切换后：在一段时间内保留旧域的重定向，许多用户会通过旧书签、邮件或缓存链接返回。

即使 Koder.ai（或其他平台）为你处理自定义域和 SSL，这份清单仍然重要。大多数问题来自 DNS 与重定向，而不是应用代码。

示例场景：从平台 URL 迁移到自定义域

你的应用当前运行在像 myapp.koder.ai 的临时平台地址上。它可用，但你希望客户使用 example.com，并让 www.example.com 重定向到 apex，同时强制 HTTPS。

一个简单的 DNS 方案能把风险降到最低。在动手前记录当前可用状态（如果平台支持快照就拍个快照），并在前一天把 DNS TTL 降到较短值。

在不拆除现有平台 URL 的情况下添加新记录：

• example.com：A/ALIAS 指向平台提供的托管目标
• www.example.com：CNAME 指向 example.com（或根据提供商指向平台目标）
• 保留 myapp.koder.ai，以便始终有已知可用的回退

DNS 就位后，为两个主机名申请证书（example.com 与 www.example.com）。在证书签发并生效前不要切换流量，否则用户会遇到浏览器警告。

明确的切换时间表与检查点：

• T-24h：降低 TTL，确认你能快速回滚
• T-0：在应用主机启用域名并验证 SSL 已就绪
• T+15m：在无痕/隐身窗口测试 example.com（首页、静态资源、API 调用）
• T+30m：启用重定向（HTTP → HTTPS，www → apex）
• 回滚时刻：若登录或 API 调用失败，立即把 DNS 恢复为之前的目标并保持平台 URL 可用

迁移后验证 Cookie 行为。登录、刷新并确认在 www 与 apex 上仍然保持登录；若会话断开，多半是 Cookie 域或 SameSite 设置仍假定旧主机。

接下来的步骤：监控、记录并让未来改动更安全

切换成功后工作并未结束。多数域名迁移会在之后失败，因为没人注意到缓慢的变化：证书临近到期、一次匆忙的 DNS 改动，或一次重定向微调破坏了登录流程。

建立一个你真的会持续维护的小型监控流程。无需企业级工具，但要有你信任的几个信号：关键页面（首页、登录页、一个需认证的页面）可用性检测、证书到期提醒（例如在 30 天和 7 天时报警）、错误率监控（关注 4xx/5xx 峰值，而不仅是在线率），以及偶尔的重定向验证（HTTP 是否跳到 HTTPS，首选主机是否获胜）。

在你有把握之前保留短期回滚窗口。切换后 24 到 72 小时内，保持之前的设置（旧 DNS 目标、旧托管配置、旧 TLS 设置）可快速回退，以防出现隐藏问题，比如支付回调或某个 OAuth 提供方仍指向旧域。

一旦确认无误，再把 DNS TTL 值调回较高值。低 TTL 在变更期有用，但会加重解析器负担并在之后放大小错误的影响。选择与你预计变更频率相匹配的正常 TTL（很多团队选择 1 到 4 小时）。

最后，趁记忆新鲜把最终状态记录下来：哪些记录存在（类型、名称、值、TTL）、支持哪些主机名、以及确切的重定向规则。写清证书在哪里签发、覆盖哪些主机名（apex、www、子域）以及谁负责续期。

如果你在平台上构建与部署，最好把域名视为一等功能并确保回滚足够简单。Koder.ai 将自定义域与快照和回滚并列，这能在未来需要快速撤销改动时减少压力。