专业的 API 文档需要专业的域名。默认情况下，Apidog 文档可通过 <subdomain>.apidog.io 域名访问。不过，你可以通过设置自己的域名来自定义它，让你的受众能够通过符合组织品牌形象的域名访问文档。前提条件#
开始设置自定义域名#
要访问自定义域名设置，请导航到侧边栏中的 Publish Docs 菜单，然后进入 Publish 设置页面。你会找到 Custom Domain 部分，可点击 Edit 按钮开始设置。自定义域名设置方法#
1.
CNAME（推荐）：最容易设置和维护；同时适用于子域名和根域名，提供最大的灵活性。
2.
Reverse Proxy（高级）：需要使用内容分发网络（CDN）或在你自己的服务器上设置反向代理；推荐熟悉这些技术的用户使用。
配置 CNAME#
本节仅适用于你在上一步中选择了 CNAME 选项的情况。
配置 CNAME 记录#
不同 DNS 控制面板中的字段名称和配置步骤可能有所不同，但核心概念保持一致。如果你不确定，请向你的 DNS 提供商确认。type 是你想要创建的 DNS 记录类型。这里需要选择 CNAME。
name 或 DNS entry 是你输入子域名的位置。你可能需要输入完整子域名（例如 docs.example.com），也可能只需输入顶级域名前面的部分（例如 docs）。如果不确定应使用哪种方式，请咨询你的 DNS 提供商。
target、value 或 destination 是子域名应指向的位置。当你选择 DNS CNAME 选项时，可在 Apidog 的 Publish 设置中看到该值。它看起来类似于 {docsSiteId}.apidog.io。你应完整输入此值（例如 12345678.apidog.io）。
你可能还会看到名为 TTL 的字段，它代表 Time To Live（生存时间）。它是 DNS 记录可被缓存的秒数。如果你不确定如何设置，我们建议选择 Auto 或保留默认值。
CNAME 记录不能与同一名称的其他记录共存。如果你为所选子域名已经有 A 记录、AAAA 记录、TXT 记录或任何其他类型的记录，则需要先删除这些记录，然后 再添加 CNAME 记录。
如果你在 Cloudflare 控制面板中配置 DNS，请确保 Cloudflare 的代理功能（橙色云朵，在域名设置中也称为 "Proxy status"）已禁用。原因有两点：此选项会向公众混淆你域名的 DNS 目标，导致 Apidog 无法正确对你的自定义域名运行例行检查。
更改需要多长时间才会生效？#
简短回答：在进入下一步之前，你可能需要等待 10 分钟到 48 小时，DNS 更改才会生效。还记得我们之前提到的 TTL（Time To Live）字段吗？DNS 记录会被缓存一段时间——出于性能原因，这通常是一件非常好的事情，因为它们通常不会频繁变化。当它们_确实_发生变化时，会有一段时间（TTL 值），DNS 缓存服务器需要等缓存过期后，才会检查是否有任何更改并相应地处理。在大多数情况下，最好至少等待 10 分钟后再进入下一个也是最后一个步骤。有时可能会更新得更快一些，也可能需要更长时间。超过 48 小时的情况很少见。想要检查这个称为_传播_的过程进展如何吗？你可以使用 DNS 查询工具，例如 WhatsMyDNS。输入你的完整子域名，从下拉列表中选择 CNAME，然后按 Search 按钮。世界各地的 DNS 缓存服务器会响应，告知你它们的缓存结果。你需要定期检查这些结果，直到绝大多数都返回你分配的 CNAME 值。配置 CDN 或你自己的反向代理服务器#
本节仅适用于你在上一步中选择了 Reverse Proxy 选项的情况。
配置 AWS CloudFront#
你可以使用 AWS CloudFront、Cloudflare Enterprise 等云厂商提供的 CDN 服务，将其设置为你自己的反向代理服务器。在以下示例中，我们将配置 AWS CloudFront 作为 Reverse Proxy。| 设置 | 值 |
|---|
| Origin Domain Name | 设置为 {docsSiteId}.apidog.io |
| Name | 源站的描述。此值用于区分同一分发中的多个源站，因此必须唯一。 |
| Origin Protocol Policy | 设置为仅 HTTP |
| Alternate Domain Names (CNAMEs) | 设置为你的自定义域名（即你在自定义域名设置期间，在 Publish 设置中配置的同一个域名） |
| SSL Certificate | 设置为存储在 AWS Certificate Manager（ACM）中的自定义域名 SSL 证书。 |
3.
提供 Origin Custom Headers 的信息（Header Name 和 Value 字段只会在你提供 Origin Domain Name 后出现）
| 头部名称 | 值 |
|---|
| X-Apidog-Docs-Site-ID | 设置为 {docsSiteId} |
{docsSiteId} 是你的 Docs Site ID，可在自定义域名面板中找到。请确保输入正确的 ID。4.
配置 Default Cache Behavior Settings。以下是你需要更改的值。
| 设置 | 值 |
|---|
| Viewer Protocol Policy | 选择 Redirect HTTP to HTTPS |
| Allowed HTTP Methods | 选择 GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE。 |
| Cache and origin request settings | 选择 Use legacy cache settings。为 Headers、Query strings 和 Cookies 选择 All |
5.
不要启用 AWS Web Application Firewall (WAF)。
6.
点击页面底部的 Create distribution。你将在 CloudFront Distributions 列表中看到新创建的分发。请注意，在分发变为 Deployed 之前，Status 会显示为 In progress。
7.
为你的自定义域名在 DNS 中添加一条新的 CNAME 记录，指向你的 Distribution 的 CloudFront Domain Name。可通过点击你的 Distribution ID，在 General 选项卡下的 Distribution domain name 中找到它（例如 fd1fbc7cac6197.cloudfront.net）。
将 Cloudflare 配置为反向代理#
你可以使用 Cloudflare Workers 作为反向代理。这允许你保持域名代理（橙色云朵）状态，同时确保 Apidog 收到必要的项目标识符。2.
点击 Create Application，然后点击 Create Worker。（如果系统提示选择方法，请继续选择 Start with Hello World!）
3.
为你的 worker 命名（例如 apidog-docs-proxy），然后点击 Deploy。
4.
点击 Edit Code，并用以下内容替换现有脚本：
你可以在自定义域名面板中找到你的 {docsSiteId}。请确保在 targetHost 和 docsSiteId 变量中都输入正确的 ID。
6.
导航到你的 Worker 的 Settings 选项卡，选择 Domains & Routes，然后点击 +Add 按钮。
7.
输入你的自定义域名（例如 docs.example.com）。Cloudflare 将自动处理 DNS 记录和 SSL 证书。
8.
确保你的 Cloudflare SSL/TLS encryption mode 设置为 Full 或 Full (Strict)，以允许 Cloudflare 与 Apidog 之间进行安全通信。
在将自定义域名附加到你的 worker 之前，请确保该域名（例如 example.com）已添加到你的 Cloudflare 账户，并且其名称服务器处于活动状态。
配置你自己的反向代理服务器#
你可以为你的 API 文档配置自己的反向代理服务器。在以下示例中，我们将使用 Nginx 作为反向代理服务器。1.
将以下内容添加到 Nginx 配置文件中以进行简单配置。
:8080 {
handle_path /* {
reverse_proxy http://{docsSiteId}.apidog.io {
header_up X-Apidog-Docs-Site-ID {docsSiteId}
header_up Host "docs.example.com"
}
}
}
{docsSiteId} 是你的 Docs Site ID，可在自定义域名面板中找到。请确保输入正确的 ID。2.
为你的自定义域名配置 DNS 记录，使其指向你的反向代理服务器。
将 API 文档部署到自定义域名的子目录#
配置步骤：#
1.
在 Apidog 的 Custom Domain 设置页面中，输入你的自定义域名。
2.
选择 Reverse Proxy 并启用 Use Subdirectory，然后输入子目录路径。
3.
接下来，你需要修改 Web 服务器的配置文件。假设你使用 Nginx 来代理你的服务，可以参考以下配置：
proxy_pass：将客户端请求转发到另一台服务器（例如 Apidog 的 API 文档服务器）。
proxy_set_header：设置代理服务器发送到上游服务器的请求头部，确保请求被正确处理。
/api-docs/ 是自定义域名的子目录，并且在 Nginx 配置中必须以 / 结尾。
http://{docsSiteId}.apidog.io/ 也必须以 / 结尾。
将 {docsSiteId} 替换为你的 Apidog 文档站点 ID。 docs.example.com 是示例自定义域名。请将其替换为你的实际自定义域名。
启用 HTTPS#
Apidog 的在线文档支持 HTTPS 协议，相比 HTTP 具有多项优势：安全数据传输：HTTPS 使用 SSL/TLS 加密来确保数据传输安全，防止第三方拦截信息。
SEO 优化：搜索引擎爬虫更倾向于使用 HTTPS，因为它提供更好的安全性和隐私保护。因此，在搜索引擎排名中，HTTPS 网站可能比 HTTP 网站具有更高的权威性。
启用 HTTPS 的步骤：#
1.
前往 Publish 页面并打开 Custom Domain 选项卡。
2.
打开 HTTPS 以启用 HTTPS；你也可以选择启用 Always Use HTTPS，以防止通信被劫持或遭受中间人攻击。
SSL 证书管理#
启用 HTTPS 后，你可以选择如何管理 SSL 证书：由 Apidog 生成：Apidog 将自动生成 SSL 证书。
故障排除#
你正在使用 Apidog Europe 吗？#
如果你正在使用 Apidog Europe，请确保在自定义域名设置中使用正确的域名。Apidog Europe 在之前设置中的正确域名是 {docsSiteId}.eu.apidog.com。 
