跳转到主要内容
若要使用 AWS Route 53 和 CloudFront 将文档托管在类似 yoursite.com/docs 这样的子路径上，你必须将 DNS 服务提供商配置为指向你的 CloudFront 分配。 在配置 AWS 之前，请在控制台中设置你的基础路径：
  1. 在控制台中前往 Custom domain setup 页面。
  2. 启用 Host at 开关并输入你的基础路径。例如 /docs 或 /help。
  3. 输入你的域名。
  4. 输入你的基础路径。
  5. 选择 Add domain。

​
概览

以下示例使用 /docs 基础路径。如果你使用不同的基础路径，请将 /docs 替换为你的基础路径。
将流量路由到以下路径，并将缓存策略（Cache Policy）设置为 CachingDisabled：
  • /.well-known/acme-challenge/* - 用于 Let’s Encrypt 证书验证
  • /.well-known/vercel/* - 用于域名验证
  • /docs/* - 用于子路径路由
  • /docs/ - 用于子路径路由
将流量路由到以下路径，并将缓存策略（Cache Policy）设置为 CachingEnabled：
  • /mintlify-assets/_next/static/*
  • Default (*) - 你的网站着陆页
所有 Behaviors 都必须将 origin request policy 设置为 AllViewerExceptHostHeader。 你的子路径对应的 Behaviors 必须允许所有 HTTP 方法。CloudFront 默认只允许 GET 和 HEAD 请求，这会阻止 Mintlify 用于分析和其他交互功能的 POST 请求。 CloudFront「Behaviors」页面，其中包含 4 个 behaviors：/docs/*、/docs、Default 和 /.well-known/*。

​
创建 CloudFront 分配

  1. 在 AWS 控制台中前往 CloudFront。
  2. 选择 Create distribution。
CloudFront Distributions 页面，高亮显示 “Create distribution” 按钮。
  1. 在 Origin domain 中输入 [SUBDOMAIN].mintlify.site，其中 [SUBDOMAIN] 是你项目的唯一子域。
CloudFront “Create distribution” 页面显示 “acme.mintlify.site” 作为 Origin domain。
  1. 在 “Web Application Firewall (WAF)” 中，启用安全防护。
Web Application Firewall (WAF) 选项，已选择 “Enable security protections”。
WAF 规则可能会阻止 Mintlify 用于分析和其他交互功能的 POST 请求。如果启用 WAF 后仪表板中不再显示分析数据，请检查 WAF 日志中是否有指向 /docs/_mintlify/ 下路径的被阻止请求。
  1. 其余设置保持默认。
  2. 选择 Create distribution。

​
添加默认 Origin

  1. 创建分发后，前往 “Origins” 标签页。
CloudFront 分发界面，高亮显示 “Origins” 标签页。
  1. 找到与你主域名对应的预发布环境 URL。具体取决于你的落地页托管服务。例如，Mintlify 的预发布 URL 是 mintlify-landing-page.vercel.app。
如果你的落地页由 Webflow 托管，请使用 Webflow 的预发布 URL，通常为 .webflow.io。如果你使用 Vercel，请使用每个项目默认提供的 .vercel.app 域名。
  1. 新建一个 Origin，并将你的预发布 URL 填入 “Origin domain”。
CloudFront 的 “Create origin” 页面，高亮显示 “Origin domain” 输入框。
此时，你应当有两个 Origins：一个为 [SUBDOMAIN].mintlify.site，另一个为你的预发布 URL。
CloudFront 的 “Origins” 页面，包含两个 origins：一个用于 mintlify，另一个用于 mintlify-landing-page。

​
设置行为

CloudFront 中的行为用于控制子路径逻辑。总体而言，我们希望实现以下逻辑：
  • 如果用户访问你的自定义子路径，跳转到 [SUBDOMAIN].mintlify.site。
  • 如果用户访问其他任意页面，跳转到当前登录页。
  1. 打开 CloudFront 分配的 “Behaviors” 标签页。
突出显示 CloudFront “Behaviors” 标签页。
  1. 点击 Create behavior 按钮，并创建以下行为。

​
/.well-known/*

为用于 Vercel 域名验证的路径创建一个 Path pattern 为 /.well-known/* 的行为，并将 Origin and origin groups 指向你的文档站点 URL。 在 “Cache policy” 中选择 CachingDisabled，以确保这些验证请求直通且不被缓存。
CloudFront “Create behavior” 页面，"Path pattern" 为 "/.well-known/*"，"Origin and origin groups" 指向预发布环境的 URL。
如果 .well-known/* 过于宽泛，你至少可以为 Vercel 将其细化为 2 个行为：
  • /.well-known/vercel/* - Vercel 域名验证所必需
  • /.well-known/acme-challenge/* - Let’s Encrypt 证书验证所必需

​
你的子路径

创建一个行为，将 Path pattern 设置为你选择的子路径，例如 /docs，并将 Origin and origin groups 指向 .mintlify.site 的 URL（在我们的示例中为 acme.mintlify.site）。
  • 将 “Cache policy” 设置为 CachingDisabled。
  • 将 “Origin request policy” 设置为 AllViewerExceptHostHeader。
  • 将 “Viewer Protocol Policy” 设置为 Redirect HTTP to HTTPS。
  • 将 “Allowed HTTP methods” 设置为 GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE。
CloudFront 默认只允许 GET 和 HEAD 请求。如果你不允许所有 HTTP 方法，CloudFront 会拒绝 Mintlify 用于分析的 POST 请求，即使你的文档可以正常加载，仪表板中也不会显示任何页面浏览量。
CloudFront 的 "Create behavior" 页面，其中 "Path pattern" 设置为 "/docs/*"，并且 "Origin and origin groups" 指向 acme.mintlify.site 的 URL。

​
带通配符的子路径

创建一个行为，在 Path pattern 中填写你选择的子路径并在后面添加 /*，例如 /docs/*，并将 Origin and origin groups 指向相同的 .mintlify.site URL。 除 Path pattern 外，其余设置应与基础子路径行为完全一致。
  • 将 “Cache policy” 设置为 CachingDisabled
  • 将 “Origin request policy” 设置为 AllViewerExceptHostHeader
  • 将 “Viewer protocol policy” 设置为 Redirect HTTP to HTTPS
  • 将 “Allowed HTTP methods” 设置为 GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE

​
/mintlify-assets/_next/static/*

  • 将“Cache policy”设置为 CachingOptimized
  • 将“Origin request policy”设置为 AllViewerExceptHostHeader
  • 将“Viewer protocol policy”设置为 Redirect HTTP to HTTPS

​
Default (*)

最后，我们将编辑 Default (*) 行为。
已选中“Default (*)”行为并突出显示 Edit 按钮的 CloudFront 发行版。
  1. 将默认行为的 Origin and origin groups 更改为预发布环境的 URL（在我们的示例中为 mintlify-landing-page.vercel.app）。
CloudFront 的“Edit behavior”页面，突出显示了“Origin and origin groups”输入字段。
  1. 选择 保存更改。

​
检查你是否已正确配置行为

如果你按前述步骤操作，行为配置应如下所示：
CloudFront “Behaviors” 页面，包含 4 个行为：/docs/*、/docs、Default 和 /.well-known/*。

​
预览分发

你现在可以进入 “General” 标签页并访问 Distribution domain name 的 URL，来测试你是否已正确配置分发。
CloudFront “General” 标签页，高亮显示 “Distribution domain name” 的 URL。
所有页面应当指向你的主着陆页；但如果在该 URL 后追加你选择的子路径（例如 /docs），则应会跳转到你的 Mintlify 文档实例。

​
连接 Route 53

现在，我们将把 CloudFront 分配的功能接入到你的主域名。
本节你也可以参考 AWS 的官方指南：将 Amazon Route 53 配置为将流量路由到 CloudFront 分配
  1. 在 AWS 控制台中进入 Route53。
  2. 进入主域名的“Hosted zone”。
  3. 选择 Create record。
Route 53 的“Records”页面，突出显示“Create record”按钮。
  1. 打开 Alias，然后在 Route traffic to 中选择 Alias to CloudFront distribution 选项。
Route 53 的“Create record”页面，突出显示“Alias”开关和“Route traffic to”菜单。
  1. 选择 Create records。
如果当前存在 A 记录，你可能需要将其删除。
你的文档现已通过主域名中你选择的子路径对外可用。
部署完更改后，你的文档通常会在几分钟内在你的子路径下可用。如果你的设置涉及 DNS 变更，传播可能需要 1–4 小时，极少数情况下最长可达 48 小时。如果你的文档没有立即可用，请先耐心等待再进行故障排查。