使用 AWS Route 53 和 CloudFront 在子路径下部署

若要使用 AWS Route 53 和 CloudFront 将文档托管在类似 yoursite.com/docs 这样的子路径上，你必须将 DNS 服务提供商配置为指向你的 CloudFront 分配。

在配置 AWS 之前，请在控制台中设置你的基础路径：

1. 在控制台中前往 Custom domain setup 页面。
2. 启用 Host at 开关并输入你的基础路径。例如 /docs 或 /help。
3. 输入你的域名。
4. 输入你的基础路径。
5. 选择 Add domain。

将流量路由到以下路径，并将缓存策略（Cache Policy）设置为 CachingDisabled：

• /.well-known/acme-challenge/* - 用于 Let’s Encrypt 证书验证
• /.well-known/vercel/* - 用于域名验证
• /docs/* - 用于子路径路由
• /docs/ - 用于子路径路由
• /_mintlify/* - 用于 API playground 请求

将流量路由到以下路径，并将缓存策略（Cache Policy）设置为 CachingEnabled：

• /mintlify-assets/* - 用于 CSS、JavaScript 和 favicon
• Default (*) - 你的网站着陆页

所有 Behaviors 都必须将 origin request policy 设置为 AllViewerExceptHostHeader。

你的子路径对应的 Behaviors 必须允许所有 HTTP 方法。CloudFront 默认只允许 GET 和 HEAD 请求，这会阻止 Mintlify 用于分析和其他交互功能的 POST 请求。

1. 在 AWS 控制台中前往 CloudFront。
2. 选择 Create distribution。

3. 在 Origin domain 中输入 [SUBDOMAIN].mintlify.site，其中 [SUBDOMAIN] 是你项目的唯一子域。

4. 在 “Web Application Firewall (WAF)” 中，启用安全防护。

5. 其余设置保持默认。
6. 选择 Create distribution。

1. 创建分发后，前往 “Origins” 标签页。

2. 找到与你主域名对应的预发布环境 URL。具体取决于你的落地页托管服务。例如，Mintlify 的预发布 URL 是 mintlify-landing-page.vercel.app。

3. 新建一个 Origin，并将你的预发布 URL 填入 “Origin domain”。

你现在应当有两个 Origins：一个为 [SUBDOMAIN].mintlify.site，另一个为你的预发布 URL。

CloudFront 中的行为用于控制子路径逻辑。总体而言，我们希望实现以下逻辑：

• 如果用户访问你的自定义子路径，跳转到 [SUBDOMAIN].mintlify.site。
• 如果用户访问其他任意页面，跳转到当前登录页。

1. 打开 CloudFront 分配的 “Behaviors” 标签页。

2. 点击 Create behavior 按钮，并创建以下行为。

为用于 Vercel 域名验证的路径创建一个 Path pattern 为 /.well-known/* 的行为，并将 Origin and origin groups 指向你的文档站点 URL。

在 “Cache policy” 中选择 CachingDisabled，以确保这些验证请求直通且不被缓存。

创建一个行为，将 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。

创建一个行为，在 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

创建一个行为，在 Path pattern 中填写 /mintlify-assets/*，并将 Origin and origin groups 指向 .mintlify.site 的 URL。此路径从你域名的根路径提供文档的 CSS、JavaScript 和 favicon。

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

创建一个行为，在 Path pattern 中填写 /_mintlify/*，并将 Origin and origin groups 指向 .mintlify.site 的 URL。此路径从你域名的根路径处理 API playground 请求。

• 将 “Cache policy” 设置为 CachingDisabled。
• 将 “Origin request policy” 设置为 AllViewerExceptHostHeader。
• 将 “Viewer protocol policy” 设置为 Redirect HTTP to HTTPS。
• 将 “Allowed HTTP methods” 设置为 GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE。

编辑 Default (*) 行为。

1. 将默认行为的 Origin and origin groups 更改为预发布环境的 URL（在我们的示例中为 mintlify-landing-page.vercel.app）。

2. 选择 保存更改。

如果你按前述步骤操作，行为配置应如下所示：

若要测试你的分发，请进入 “General” 标签页并访问 Distribution domain name 的 URL。

所有页面都应路由到你的主着陆页。当你在 URL 后追加你选择的子路径（例如 /docs）时，该 URL 应会提供你的 Mintlify 文档。

接下来，将 CloudFront 分配连接到你的主域名。

1. 在 AWS 控制台中进入 Route53。
2. 进入主域名的“Hosted zone”。
3. 选择 Create record。

4. 打开 Alias，然后在 Route traffic to 中选择 Alias to CloudFront distribution 选项。

5. 选择 Create records。

你的文档现已通过主域名中你选择的子路径对外可用。