使用 AWS（CloudFront 和 Route 53）配置子目录

使用 AWS CloudFront 和 Route 53 将您的文档托管在 /docs 子目录下。

本指南介绍如何使用 AWS CloudFront 和 Lambda@Edge 设置子目录。这是针对 AWS 用户的一种方法。如果你使用不同的 AWS 配置（例如带有运行 NGINX 的 EC2 实例的负载均衡器），你可能需要以不同方式配置反向代理。请联系 支持 如果你需要替代配置的指导。

1

配置你的 GitBook 站点

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

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

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

2

创建你的 Lambda@Edge 函数

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

点击 创建函数 按钮。

选择 从头创建作者，然后：

• 为你的函数起一个描述性名称，例如 gitbook-subpath-proxy。

• 选择 Node.js 作为运行时（使用可用的最新版本）。

• 将架构和其他设置保持为默认。

点击 创建函数.

3

更新 Lambda 函数代码

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

export const handler = async (event) => {
	const request = event.Records[0].cf.request;
	
	// 如果你的子目录不是 /docs，请更新此处
	const subdirectory = '/docs';
	
	// 在下面用你的代理 URL 更新
	const target = new URL('<proxy URL you got from GitBook>');

	// 重写：/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;
};

务必在第 8 行将 target 更新为你在第一步从 GitBook 获取的代理 URL。它看起来像 https://proxy.gitbook.site/sites/site_XXXX

如果你使用的子目录路径不是 subdirectory ，也务必在第 5 行更新 /docs.

点击 部署 以保存你的更改。

4

为 Lambda@Edge 配置 Lambda 权限

在将 Lambda 函数与 CloudFront 一起使用之前，你需要配置执行角色以允许 Lambda@Edge 承担该角色。

1. 在你的 Lambda 函数中，点击左侧边栏的 配置 选项卡

2. 点击 权限 在左侧边栏中

3. 在 执行角色，点击角色名称以在 IAM 中打开它

4. 点击 信任关系 选项卡

5. 点击 编辑信任策略

6. 将信任策略替换为以下内容：

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

点击 更新策略 以保存。

5

发布你的 Lambda 函数

Lambda@Edge 需要已发布的版本（而不仅仅是 $LATEST).

1. 在你的 Lambda 函数中，点击右上角的 操作 下拉菜单

2. 选择 发布新版本

3. 可选地添加描述，例如 “用于 CloudFront 的初始版本”

4. 点击 发布

5. 重要： 复制出现在页面顶部的已发布版本的 ARN（它将在末尾包含一个版本号），例如 arn:aws:lambda:us-east-1:123456789:function:gitbook-subpath-proxy:1)

Lambda@Edge 函数必须在 us-east-1 （北弗吉尼亚）区域创建。如果你在其他区域创建了函数，则需要在 us-east-1 中重新创建它。

6

创建你的 CloudFront 分配

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

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

指定源

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

缓存设置

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

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

点击 创建分配.

等待分配部署（状态将从“进行中”变为“已启用”）。这可能需要几分钟时间。

7

将 Lambda@Edge 与 CloudFront 关联

一旦你的 CloudFront 分配部署：

1. 点击你的分配 ID 打开其设置

2. 转到 缓存行为 选项卡

3. 选择默认行为并点击 编辑

4. 向下滚动到 函数关联

5. 在 源请求，选择 Lambda@Edge

6. 在 Lambda 函数 ARN 字段中，粘贴你已发布 Lambda 函数的 ARN（来自步骤 5）

7. 勾选 包含正文 以允许该函数在需要时访问请求主体

8. 点击 保存更改

8

配置域名和 DNS 记录

1. 在你的 CloudFront 分配主页面，点击 常规 选项卡，并在 备用域名下，点击 添加域名

2. 输入你为其配置子目录的域名，例如 example.com 然后点击 下一步

3. 选择你现有的 TLS 证书，或在需要时创建新的证书，然后再次点击 下一步 再次

9

从 CloudFront 配置 Route 53 DNS 记录

如果你使用 Route 53 进行 DNS，你需要创建或更新你的 DNS 记录以指向你的 CloudFront 分配。

1. 在 CloudFront 分配的主页面上，确保你处于 常规 选项卡，然后在你在 备用域名中配置的 URL 下， 点击 将域名路由到 CloudFront。

2. 点击 自动设置路由 以为你的域名创建 A 和 AAAA DNS 记录

如果你不使用 Route 53，你需要在你的 DNS 提供商处更新设置，将你的域名指向 CloudFront 分配域名。你可以在 CloudFront 分配详情中的“分配域名”下找到该值。

10

测试你的配置

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

1. 打开浏览器并访问带子目录路径的域名（例如， https://example.com/docs)

2. 你应该能看到你的 GitBook 文档站点！

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

• 再等待几分钟以完成 DNS 传播

• 清除浏览器缓存或尝试使用隐身窗口

• 在终端运行 nslookup yourdomain.com 以验证 DNS 是否正确解析

• 检查 CloudFront 分配状态是否为“已启用”而不是“进行中”

恭喜！你的 GitBook 文档现在可以通过自定义子目录访问。

故障排除

Lambda 函数未触发：

• 确保你已发布 Lambda 函数的一个版本（而不是使用 $LATEST)

• 验证 Lambda 函数是否位于 us-east-1 区域

• 检查信任策略是否包含 edgelambda.amazonaws.com

DNS 未解析：

• DNS 更改可能需要时间传播（最长可达 48 小时，尽管通常要快得多）

• 验证你的 Route 53 记录是否指向正确的 CloudFront 分配

• 检查你是否删除了任何旧的冲突 DNS 记录

SSL 证书错误：

• 确保你在 AWS 证书管理器中的 SSL 证书包含你的自定义域名

• CloudFront 的证书必须在 us-east-1 区域创建

子目录无法工作：

• 验证 Lambda 函数中的 SUBDIRECTORY 值与您在 GitBook 中配置的匹配

• 检查你在 Lambda 函数中的 target 是否正确

• 查看 CloudFront 日志以确定请求是否到达该分配