mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
a5d2c6e047
* Document custom domain validation retry Generated-By: mintlify-agent * 💅 --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
144 lines
5.9 KiB
Plaintext
144 lines
5.9 KiB
Plaintext
---
|
||
title: "自定义域名"
|
||
description: "通过 DNS 配置、自动 TLS 证书以及子域名或子路径路由选项，将文档托管在自定义域名上。"
|
||
keywords: ["自定义域名配置", "DNS 配置", "CNAME 记录", "TLS 证书"]
|
||
---
|
||
|
||
要在自定义域名上托管你的文档：
|
||
|
||
1. 在控制台中添加你的 domain。
|
||
2. 在你的域名服务商处配置 DNS 设置。
|
||
3. 等待 DNS 生效并自动签发 TLS 证书。
|
||
|
||
<Info>
|
||
想要配置类似 `example.com/docs` 这样的子路径？请参见 [/docs 子路径](/zh/deploy/docs-subpath)。
|
||
</Info>
|
||
|
||
<div id="add-your-custom-domain">
|
||
## 添加自定义域名
|
||
</div>
|
||
|
||
1. 在控制台前往 [Custom domain setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) 页面。
|
||
2. 输入你的域名，例如 `docs.example.com` 或 `www.example.com`。
|
||
3. 点击 **Add domain**。
|
||
|
||
<Frame>
|
||
<img alt="“Custom domain setup” 页面，显示用于输入自定义域名 URL 的字段。" className="block dark:hidden" src="/images/domain/add-custom-domain-light.png" />
|
||
|
||
<img alt="“Custom domain setup” 页面，显示用于输入自定义域名 URL 的字段。" className="hidden dark:block" src="/images/domain/add-custom-domain-dark.png" />
|
||
</Frame>
|
||
|
||
<div id="configure-your-dns">
|
||
## 配置你的 DNS（域名系统）
|
||
</div>
|
||
|
||
1. 在你的域名提供商网站，前往该域名的 DNS 设置。
|
||
2. 新建一条 DNS 记录，并按以下值进行设置：
|
||
|
||
```text
|
||
CNAME | docs | cname.mintlify.builders
|
||
```
|
||
|
||
<Tip>
|
||
不同域名提供商添加 DNS（域名系统）记录的方式各不相同。请查阅你的域名提供商文档获取具体操作指南。
|
||
</Tip>
|
||
|
||
<Warning>
|
||
在两条验证 `TXT` 记录都在你的 dashboard 中显示为已验证之前，请勿添加或更改 `CNAME`。当 DNS 配置正确时，每条记录都会显示绿色对勾。dashboard 会先验证 `TXT` 记录，证书才能完成签发。过早切换 `CNAME` 通常会导致 HTTPS 中断，直到签发完成。
|
||
|
||
如果你正在迁移现有域名并希望实现零停机，请先发布验证 `TXT` 记录，待其显示为已验证且 TLS 完成预签发后，再将 `CNAME` 指向 Mintlify。
|
||
</Warning>
|
||
|
||
<div id="verification-txt-records">
|
||
### 验证 TXT 记录
|
||
</div>
|
||
|
||
添加自定义域名后，dashboard 会显示两条 `TXT` 记录，你必须在你的 DNS 提供商处添加：
|
||
|
||
```text
|
||
TXT | _acme-challenge.<你的域名> | <dashboard 中显示的值>
|
||
TXT | _cf-custom-hostname.<你的域名> | <dashboard 中显示的值>
|
||
```
|
||
|
||
`_acme-challenge` 记录授权 Let's Encrypt 为你的域名签发 TLS 证书，`_cf-custom-hostname` 记录用于验证你确实拥有该域名的控制权。
|
||
|
||
dashboard 会在后台轮询 DNS，并在验证到预期值后用绿色对勾标记每条记录。在 DNS 提供商处保存记录后，请等待短暂的传播时间，状态才会更新。
|
||
|
||
<div id="dns-propagation">
|
||
### DNS 传播
|
||
</div>
|
||
|
||
DNS 变更通常需要 1–24 小时在全球范围内生效，某些情况下可能长达 48 小时。你可以使用 [DNSChecker](https://dnschecker.org) 验证 DNS 是否配置正确。
|
||
|
||
DNS 记录生效后，你的文档最初将通过 HTTP 提供访问。TLS 证书签发完成后，HTTPS 将可用。
|
||
|
||
<div id="automatic-tls-provisioning">
|
||
### 自动配置 TLS
|
||
</div>
|
||
|
||
在你添加 `TXT` 记录后，当 DNS（域名系统）记录能够正确解析时，系统会使用 Let's Encrypt 为你的站点自动签发免费的 SSL/TLS 证书。
|
||
|
||
通常在 DNS 传播后的数小时内即可完成，极少数情况下可能需要长达 24 小时。证书会在到期前自动续期。
|
||
|
||
<div id="caa-records">
|
||
### CAA 记录
|
||
</div>
|
||
|
||
如果你的 domain 使用 CAA（Certification Authority Authorization）记录，你需要授权 Let's Encrypt 为该 domain 签发证书。将以下 CAA 记录添加到你的 DNS（域名系统）设置中：
|
||
|
||
```text
|
||
0 问题 "letsencrypt.org"
|
||
```
|
||
|
||
<div id="reserved-paths">
|
||
### 保留路径
|
||
</div>
|
||
|
||
用于证书验证的 `/.well-known/acme-challenge` 路径为保留路径，不能重定向或重写。若对该路径配置了重定向或重写，证书签发会失败。
|
||
|
||
<div id="provider-specific-settings">
|
||
### 特定服务商设置
|
||
</div>
|
||
|
||
<Accordion title="Cloudflare 加密模式">
|
||
如果 Cloudflare 是你的 DNS（域名系统）服务商，你需要在 SSL/TLS 加密设置中启用“Full (strict)”模式。此外，请在 Edge Certificates 设置中禁用“Always Use HTTPS”。Cloudflare 的 HTTPS 重定向会在证书配置期间阻止 Let's Encrypt 验证你的域名。
|
||
</Accordion>
|
||
|
||
<div id="retry-validation">
|
||
### 重新触发验证
|
||
</div>
|
||
|
||
在你添加用于验证的 `TXT` 记录后，域名验证可能进入退避等待期，下一次重试最长可能需要数小时。如果你已添加正确的 DNS 记录，但域名仍处于待验证状态，可在控制台中手动重新触发验证以跳过等待。
|
||
|
||
1. 进入控制台中的[自定义域名设置](https://dashboard.mintlify.com/settings/deployment/custom-domain)页面。
|
||
2. 找到处于待验证状态的自定义域名。
|
||
3. 点击 **Retry validation**。
|
||
|
||
请仅在确认 DNS 记录正确后再使用该选项。使用错误的记录反复重试不会加快验证。
|
||
|
||
<div id="set-a-canonical-url">
|
||
## 设置规范 URL
|
||
</div>
|
||
|
||
在配置好 DNS 后，设置一个规范 URL，以确保搜索引擎索引你首选的域名。规范 URL 会告诉搜索引擎哪一个版本的文档是主版本。当文档可通过多个 URL 访问时，这有助于提升 SEO（搜索引擎优化），并避免重复内容问题。
|
||
|
||
在 `docs.json` 中添加 `canonical` 元标签：
|
||
|
||
```json
|
||
"seo": {
|
||
"metatags": {
|
||
"canonical": "https://www.your-custom-domain-here.com"
|
||
}
|
||
}
|
||
```
|
||
|
||
将 `https://www.your-custom-domain-here.com` 替换为你的实际自定义 domain。举例来说，如果你的自定义 domain 是 `docs.mintlify.com`，你应使用：
|
||
|
||
```json
|
||
"seo": {
|
||
"metatags": {
|
||
"canonical": "https://docs.mintlify.com"
|
||
}
|
||
}
|
||
```
|