> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/fa-bu/custom-domain/setting-a-custom-subdirectory/configuring-a-subdirectory-with-aws.md).

# 使用 AWS、CloudFront 和 Route 53 配置子目录

{% hint style="info" %}
本指南介绍如何使用 AWS CloudFront 和 Lambda\@Edge 设置子目录。这是 AWS 用户的一种实现方式。如果你使用的是不同的 AWS 配置（例如带有运行 NGINX 的 EC2 实例的负载均衡器），你可能需要以不同方式配置反向代理。请联系 [支持](broken://pages/04cf2dcac6d338e981b70bca3ec8785a595da022) 如果你需要其他配置方面的指导。
{% endhint %}

{% stepper %}
{% step %}
**配置你的 GitBook 网站**

在你的 GitBook 组织中，点击侧边栏中的文档站点名称，然后点击 **管理站点** 或者打开 **设置** 选项卡。打开 **域名和重定向** 部分，在“Subdirectory”下，点击 **设置子目录**.

输入你希望托管文档的 URL。然后指定文档访问的子目录，例如 `example.com/docs`，然后点击 **配置**.

在 **附加配置**，你现在会看到一个代理 URL。下一步在配置 Lambda 函数时会用到它。请将其复制到剪贴板。
{% endstep %}

{% step %}
**创建你的 Lambda\@Edge 函数**

登录你的 AWS 控制台并导航到 **Lambda**.

点击 **创建函数** 按钮。

选择 **从头开始编写**，然后：

* 给你的函数起一个描述性名称，例如 `gitbook-subpath-proxy。`
* 选择 **Node.js** 作为运行时（使用可用的最新版本）。
* 将架构和其他设置保持为默认值。

点击 **创建函数**.
{% endstep %}

{% step %}
**更新 Lambda 函数代码**

在 Lambda 函数编辑器中，将默认代码替换为以下内容：

{% code lineNumbers="true" %}

```javascript
export const handler = async (event) => {
	const request = event.Records[0].cf.request;
	
	// 如果你的子目录不是 /docs，请更新
	const subdirectory = '/docs';
	
	// 以下请更新为你的代理 URL
	const target = new URL('<来自 GitBook 的代理 URL>');

	// 重写：/docs* -> proxy.gitbook.site
	if (request.uri.startsWith(subdirectory)) {
		request.uri = target.pathname + request.uri.substring(subdirectory.length);

		// 如果存在，删除尾部斜杠
		if (request.uri.endsWith('/')) {
			request.uri = request.uri.slice(0, -1);
		}

		request.origin = {
			custom: {
				domainName: target.host,
				port: 443,
				protocol: 'https',
				path: '',
				sslProtocols: ['TLSv1.2'],
				readTimeout: 30,
				keepaliveTimeout: 5,
				customHeaders: {},
			},
		};

		request.headers['host'] = [{ key: 'host', value: target.host }];
		request.headers['x-forwarded-host'] = [{ key: 'x-forwarded-host', value: target.host }];
	}
    
	return request;
};
```

{% endcode %}

{% hint style="warning" %}
务必更新 `target` 第 8 行中的值，替换为你在第一步中从 GitBook 获得的代理 URL。它看起来会像 `https://proxy.gitbook.site/sites/site_XXXX`
{% endhint %}

{% hint style="warning" %}
同时务必更新 `subdirectory` 第 5 行中的值，如果你使用的子目录路径不是 `/docs`.
{% endhint %}

点击 **部署** 以保存你的更改。
{% endstep %}

{% step %}
**为 Lambda\@Edge 配置 Lambda 权限**

在你能够将 Lambda 函数与 CloudFront 一起使用之前，你需要配置执行角色以允许 Lambda\@Edge 代入它。

1. 在你的 Lambda 函数中，点击 **配置** 标签页
2. 点击 **权限** 左侧边栏中的
3. 在 **执行角色**，点击角色名称以在 IAM 中打开它
4. 点击 **信任关系** 标签页
5. 点击 **编辑信任策略**
6. 将信任策略替换为以下内容：

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": [
                    "edgelambda.amazonaws.com",
                    "lambda.amazonaws.com"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

点击 **更新策略** 以保存。
{% endstep %}

{% step %}
**发布你的 Lambda 函数**

Lambda\@Edge 需要一个已发布的版本（不仅仅是 `$LATEST`).

1. 在你的 Lambda 函数中，点击右上角的 **操作** 下拉菜单
2. 选择 **发布新版本**
3. 可选地添加描述，例如“CloudFront 初始版本”
4. 点击 **发布**
5. **重要：** 复制页面顶部显示的已发布版本的 ARN（其末尾会包含版本号，例如 `arn:aws:lambda:us-east-1:123456789:function:gitbook-subpath-proxy:1`)

{% hint style="warning" %}
Lambda\@Edge 函数必须创建在 **us-east-1** （弗吉尼亚北部）区域。如果你在其他区域创建了函数，你需要在 us-east-1 中重新创建它。
{% endhint %}
{% endstep %}

{% step %}
**创建你的 CloudFront 分发**

导航到 **CloudFront** 在 AWS 控制台中并点击 **创建分发**.

配置以下设置。未指定的设置请保持默认值。

**指定源**

| 设置       | 值                          |
| -------- | -------------------------- |
| **源类型**  | 其他                         |
| **自定义源** | 你的主网站域名（例如， `example.com`) |

**缓存设置**

| 设置        | 值                         |
| --------- | ------------------------- |
| **缓存策略**  | CachingDisabled           |
| **源请求策略** | AllViewerExceptHostHeader |

点击 **接下来，** 选择你首选的安全防护，然后再次点击 **下一步** 。

点击 **创建分发**.

等待分发部署完成（状态将从“In Progress”变为“Enabled”）。这可能需要几分钟。
{% endstep %}

{% step %}
**将 Lambda\@Edge 关联到 CloudFront**

当你的 CloudFront 分发部署完成后：

1. 点击你的分发 ID 以打开其设置
2. 转到 **行为** 标签页
3. 选择默认行为并点击 **编辑**
4. 向下滚动到 **函数关联**
5. 在 **源请求**，选择 **Lambda\@Edge**
6. 在 **Lambda 函数 ARN** 字段，粘贴你已发布的 Lambda 函数的 ARN（来自第 5 步）
7. 检查 **包含正文** 以允许函数在需要时访问请求正文
8. 点击 **保存更改**
   {% endstep %}

{% step %}
**配置域名和 DNS 记录**

1. 在你的 CloudFront 分发主页面上，点击 **常规** 选项卡，然后在 **备用域名**，点击 **添加域名**
2. 输入你正在为其配置子目录的域名，例如 `example.com` 并点击 **下一步**
3. 选择你现有的 TLS 证书，或者在需要时创建新的证书，然后点击 **下一步** 再次
   {% endstep %}

{% step %}
**从 CloudFront 配置 Route 53 DNS 记录**

如果你使用 Route 53 作为 DNS，你需要创建或更新 DNS 记录，使其指向你的 CloudFront 分发。

1. 在你的 CloudFront 分发主页面上保持不变，确保你位于 **常规** 选项卡，然后在你在 **备用域名中配置的 URL 下方，** 点击 **将域名路由到 CloudFront。**
2. 点击 **自动设置路由** 为你的域创建 A 和 AAAA DNS 记录

{% hint style="info" %}
如果你没有使用 Route 53，你需要更新 DNS 提供商的设置，让你的域名指向 CloudFront 分发域名。你可以在 CloudFront 分发详情中的“Distribution domain name”下找到它。
{% endhint %}
{% endstep %}

{% step %}
**测试你的配置**

当所有更改都传播完成后（这可能需要 10–15 分钟）：

1. 打开浏览器并访问带有子目录路径的你的域名（例如， `https://example.com/docs`)
2. 你应该会看到你的 GitBook 文档站点！

如果站点没有立即加载，请尝试：

* 再等待几分钟以完成 DNS 传播
* 清除浏览器缓存或尝试无痕窗口
* 运行 `nslookup yourdomain.com` 在终端中以验证 DNS 是否正确解析
* 检查 CloudFront 分发状态是否为“Enabled”而不是“In Progress”

{% hint style="success" %}
恭喜！你的 GitBook 文档现在可以通过自定义子目录访问了。
{% endhint %}
{% endstep %}
{% endstepper %}

### 故障排查

**Lambda 函数未触发：**

* 确保你已发布 Lambda 函数的版本（不要使用 `$LATEST`)
* 确认 Lambda 函数位于 us-east-1 区域
* 检查信任策略是否包含 `edgelambda.amazonaws.com`

**DNS 未解析：**

* DNS 更改可能需要一些时间才能传播（最长可达 48 小时，但通常快得多）
* 验证你的 Route 53 记录是否指向正确的 CloudFront 分发
* 检查你是否删除了任何旧的、冲突的 DNS 记录

**SSL 证书错误：**

* 确保你在 AWS Certificate Manager 中的 SSL 证书包含你的自定义域名
* CloudFront 的证书必须在 us-east-1 区域创建

**子目录不工作：**

* 验证 `SUBDIRECTORY` 你在 Lambda 函数中的值与在 GitBook 中配置的值一致
* 检查 `target` 你在 Lambda 函数中的
* 查看 CloudFront 日志，确认请求是否到达了分发


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/zh/fa-bu/custom-domain/setting-a-custom-subdirectory/configuring-a-subdirectory-with-aws.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.