mintlify__docs/zh/deploy/route53-cloudfront.mdx

---
title: "使用 AWS Route 53 和 CloudFront 在子路径下部署"
sidebarTitle: "AWS"
description: "使用 AWS Route 53 进行 DNS 路由，并通过 CloudFront CDN 和 Lambda@Edge 函数将你的 Mintlify 文档部署到子路径。"
keywords: ["AWS 部署", "Route 53 DNS（域名系统）", "CloudFront CDN", "缓存策略"]
---

import Propagating from "/snippets/zh/custom-subpath-propagating.mdx";
import SubpathSetupSteps from "/snippets/zh/subpath-setup-steps.mdx";

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

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

<SubpathSetupSteps />

<div id="overview">
  ## 概览
</div>

<Note>
  以下示例使用 `/docs` 基础路径。如果你使用不同的基础路径，请将 `/docs` 替换为你的基础路径。
</Note>

将流量路由到以下路径，并将缓存策略（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` 请求。

![CloudFront「Behaviors」页面，其中包含 4 个 behaviors：`/docs/*`、`/docs`、`Default` 和 `/.well-known/*`。](/images/cloudfront/all-behaviors.png)

<div id="create-cloudfront-distribution">
  ## 创建 CloudFront 分配
</div>

1. 在 AWS 控制台中前往 [CloudFront](https://aws.amazon.com/cloudfront)。
2. 选择 **Create distribution**。

<Frame>
    ![CloudFront Distributions 页面，高亮显示 “Create distribution” 按钮。](/images/cloudfront/create-distribution.png)
  </Frame>

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

<Frame>
    ![CloudFront “Create distribution” 页面显示 “acme.mintlify.site” 作为 Origin domain。](/images/cloudfront/origin-name.png)
  </Frame>

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

<Frame>
    ![Web Application Firewall (WAF) 选项，已选择 “Enable security protections”。](/images/cloudfront/enable-security-protections.png)
  </Frame>

  <Note>
    WAF 规则可能会阻止 Mintlify 用于分析和其他交互功能的 `POST` 请求。如果启用 WAF 后仪表板中不再显示分析数据，请检查 WAF 日志中是否有指向 `/docs/_mintlify/` 下路径的被阻止请求。
  </Note>

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

<div id="add-default-origin">
  ## 添加默认 Origin
</div>

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

<Frame>
  ![CloudFront 分发界面，高亮显示 “Origins” 标签页。](/images/cloudfront/origins.png)
</Frame>

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

<Info>
  如果你的落地页由 Webflow 托管，请使用 Webflow 的预发布 URL，通常为 `.webflow.io`。

  如果你使用 Vercel，请使用每个项目默认提供的 `.vercel.app` 域名。
</Info>

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

<Frame>
  ![CloudFront 的 “Create origin” 页面，高亮显示 “Origin domain” 输入框。](/images/cloudfront/default-origin.png)
</Frame>

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

<Frame>
  ![CloudFront 的 “Origins” 页面，包含两个 origins：一个用于 mintlify，另一个用于 mintlify-landing-page。](/images/cloudfront/final-origins.png)
</Frame>

<div id="set-behaviors">
  ## 设置行为
</div>

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

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

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

<Frame>
	![突出显示 CloudFront “Behaviors” 标签页。](/images/cloudfront/behaviors.png)
</Frame>

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

<div id="well-known">
  ### `/.well-known/*`
</div>

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

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

<Frame>
  ![CloudFront “Create behavior” 页面，"Path pattern" 为 "/.well-known/*"，"Origin and origin groups" 指向预发布环境的 URL。](/images/cloudfront/well-known-policy.png)
</Frame>

<Info>
如果 `.well-known/*` 过于宽泛，你至少可以为 Vercel 将其细化为 2 个行为：
  - `/.well-known/vercel/*` - Vercel 域名验证所必需
  - `/.well-known/acme-challenge/*` - Let's Encrypt 证书验证所必需
</Info>

<div id="your-subpath">
  ### 你的子路径
</div>

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

<Warning>
  CloudFront 默认只允许 `GET` 和 `HEAD` 请求。如果你不允许所有 HTTP 方法，CloudFront 会拒绝 Mintlify 用于分析的 `POST` 请求，即使你的文档可以正常加载，仪表板中也不会显示任何页面浏览量。
</Warning>

<Frame>
  ![CloudFront 的 "Create behavior" 页面，其中 "Path pattern" 设置为 "/docs/*"，并且 "Origin and origin groups" 指向 `acme.mintlify.site` 的 URL。](/images/cloudfront/behavior-1.png)
</Frame>

<div id="your-subpath-with-wildcard">
  ### 带通配符的子路径
</div>

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

<div id="mintlify-assets">
  ### `/mintlify-assets/*`
</div>

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

<div id="_mintlify">
  ### `/_mintlify/*`
</div>

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

<div id="default">
  ### `Default (*)`
</div>

编辑 `Default (*)` 行为。

<Frame>
  ![已选中“Default (*)”行为并突出显示 Edit 按钮的 CloudFront 发行版。](/images/cloudfront/default-behavior-1.png)
</Frame>

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

<Frame>
  ![CloudFront 的“Edit behavior”页面，突出显示了“Origin and origin groups”输入字段。](/images/cloudfront/default-behavior-2.png)
</Frame>

2. 选择 **保存更改**。

<div id="check-behaviors-are-set-up-correctly">
  ### 检查你是否已正确配置行为
</div>

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

<Frame>
  ![CloudFront “Behaviors” 页面，包含 4 个行为：`/docs/*`、`/docs`、`Default` 和 `/.well-known/*`。](/images/cloudfront/all-behaviors.png)
</Frame>

<div id="preview-distribution">
  ## 预览分发
</div>

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

<Frame>
  ![CloudFront “General” 标签页，高亮显示 “Distribution domain name” 的 URL。](/images/cloudfront/preview-distribution.png)
</Frame>

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

<div id="connect-with-route-53">
  ## 连接 Route 53
</div>

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

<Note>
  本节你也可以参考 AWS 的官方指南：[将 Amazon Route 53 配置为将流量路由到 CloudFront 分配](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-cloudfront-distribution.html#routing-to-cloudfront-distribution-config)
</Note>

1. 在 AWS 控制台中进入 [Route53](https://aws.amazon.com/route53)。
2. 进入主域名的“Hosted zone”。
3. 选择 **Create record**。

<Frame>
  ![Route 53 的“Records”页面，突出显示“Create record”按钮。](/images/cloudfront/route53-create-record.png)
</Frame>

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

<Frame>
  ![Route 53 的“Create record”页面，突出显示“Alias”开关和“Route traffic to”菜单。](/images/cloudfront/create-record-alias.png)
</Frame>

5. 选择 **Create records**。

<Note>
  如果当前存在 A 记录，你可能需要将其删除。
</Note>

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

<Propagating />