AWS Route 53 与 CloudFront
通过 AWS CloudFront 和 Route 53 将 /docs 流量代理到你的 Jamdesk 站点。包括分发设置、源站配置和缓存行为规则。
设置 CloudFront 分发，将 /docs/* 转发到你的 Jamdesk 站点，并使用 Route 53 管理 DNS。大约需要 15 分钟。
前提条件
- 拥有 CloudFront 和 Route 53 访问权限的 AWS 账户
- 你的域名由 Route 53 管理（或能够在其他地方更新 DNS）
- 你的 Jamdesk 子域名（可在仪表板设置中找到）
- 你的自定义域名已在 Jamdesk 仪表板中注册并完成 DNS 验证
如果你使用自定义子路径而非默认的 /docs，请将缓存行为路径模式（步骤 3）中的 /docs/* 替换为你的子路径。在仪表板中进行任何重命名后，请重新更新分发。
第 1 步：创建 CloudFront 分配
- 打开 CloudFront 控制台
- 点击 Create Distribution
- 配置源站：
| 设置 | 值 |
|---|---|
| Origin domain | YOUR_SLUG.jamdesk.app |
| Protocol | HTTPS only |
| Name | jamdesk-docs-origin |
将 YOUR_SLUG 替换为你的 Jamdesk 子域名。
第 2 步：配置源设置
在源站设置中添加自定义标头，以标识你的域名：
| 标头名称 | 值 |
|---|---|
X-Forwarded-Host | yoursite.com |
X-Jamdesk-Forwarded-Host | yoursite.com |
这些标头告诉 Jamdesk 是哪个域名发出的请求。
此步骤是必需的。跳过它会静默失败。AllViewerExceptHostHeader 策略（下一步）只转发访问者浏览器发送的标头，不会添加新的标头。X-Jamdesk-Forwarded-Host 只能作为源站自定义标头到达 Jamdesk。如果没有它，请求仍会成功，但页面会以 noindex 提供服务，并且规范链接会指向 YOUR_SLUG.jamdesk.app 而不是你的域名。
静态源站标头无法按请求变化。若要通过一个分发提供多个备用域名，请改用查看器请求上的 CloudFront Function，并让它设置 request.headers['x-jamdesk-forwarded-host'] = { value: request.headers.host.value }。
第 3 步：创建缓存行为
添加行为，将 /docs/* 和资源请求路由到你的 Jamdesk 源站：
- 转到 Behaviors 选项卡
- 点击 Create Behavior
- 使用以下设置创建三个行为：
| 路径模式 | 源站 | 缓存策略 | 源站请求策略 |
|---|---|---|---|
/docs/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_next/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_jd/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
将三者的 Viewer protocol policy 均设置为 Redirect HTTP to HTTPS。
每个行为都是必需的。/_next/* 和 /_jd/* 提供你的文档页面所加载的 JavaScript、CSS、字体和图片。AllViewerExceptHostHeader 策略转发查看器的请求标头（除 Host 外，CloudFront 将其保留给源站）。请在三个行为上都设置它。
第 4 步：添加备用域名
- 在 General 选项卡中，点击 Edit
- 在 Alternate domain name (CNAME) 下，添加
yoursite.com - 为你的域名选择或申请 SSL 证书
第 5 步：配置 Route 53
创建一条指向 CloudFront 分发的别名记录：
- 打开 Route 53 控制台
- 选择你的托管区域
- 点击 Create Record
- 配置：
| 设置 | 值 |
|---|---|
| Record name | yoursite.com（或留空以使用顶级域名） |
| Record type | A |
| Alias | Yes |
| Route traffic to | CloudFront distribution |
| Distribution | 选择你的分发 |
第 6 步：验证
等待 DNS 传播（通常需要 5–15 分钟）。然后访问 https://yoursite.com/docs，确认你的文档已加载。
CloudFront 完整配置摘要
Distribution Settings:
├── Origin: YOUR_SLUG.jamdesk.app
│ ├── Custom Header: X-Forwarded-Host = yoursite.com
│ └── Custom Header: X-Jamdesk-Forwarded-Host = yoursite.com
├── Behavior: /docs/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
├── Behavior: /_next/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
├── Behavior: /_jd/*
│ ├── Cache Policy: CachingOptimized
│ └── Origin Request Policy: AllViewerExceptHostHeader
└── Alternate Domain: yoursite.com (with SSL certificate)故障排除
检查源站域名是否完全为 YOUR_SLUG.jamdesk.app，且不包含 https:// 前缀。
确认 Viewer protocol policy 设置为 "Redirect HTTP to HTTPS"，并且你的 SSL 证书有效。
为 /docs/* 创建 CloudFront 失效（invalidation），以在发布更改后清除缓存内容。
如果你看到 "Domain is not authorized to serve this content"：
- 确认你的域名已在 Jamdesk 仪表板中注册
- 完成你的域名的 DNS 验证（TXT 记录）
- 在源站配置中设置
X-Forwarded-Host和X-Jamdesk-Forwarded-Host自定义标头 - 检查你的域名是否映射到正确的项目
在 CloudFront 能够提供文档服务之前，域名必须已通过验证。
预检会在你的线上域名上获取 /_jd/preflight，并检查到达 Jamdesk 的内容。如果它报告你的代理"未标识自身"，说明 CloudFront 在没有 X-Jamdesk-Forwarded-Host 的情况下访问 Jamdesk。请重新检查步骤 2 中的源站自定义标头。有关每条预检消息的含义，请参阅 Custom domain only。