使用 CloudFront 与 Route 53 在 AWS 上配置子目录

配置你的 GitBook 站点

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

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

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

创建你的 Lambda@Edge 函数

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

点击 创建函数 按钮。

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

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

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

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

点击 创建函数.

更新 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;
};

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

为 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"
        }
    ]
}

点击 更新策略 以保存。

发布你的 Lambda 函数

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

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

2. 选择 发布新版本

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

4. 点击 发布

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

创建你的 CloudFront 分配

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

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

指定源

缓存设置

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

点击 创建分配.

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

将 Lambda@Edge 与 CloudFront 关联

一旦你的 CloudFront 分配部署：

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

2. 转到 缓存行为 选项卡

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

4. 向下滚动到 函数关联

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

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

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

8. 点击 保存更改

配置域名和 DNS 记录

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

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

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

从 CloudFront 配置 Route 53 DNS 记录

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

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

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

测试你的配置

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

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

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

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

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

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

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

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