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
- 配置源：
| 设置 | 值 |
|---|---|
| 源域名 | YOUR_SLUG.jamdesk.app |
| 协议 | 仅 HTTPS |
| 名称 | 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，在 viewer request 阶段运行，并设置 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 会将 Host 保留给源），并且必须在三个行为中全部设置。
第 4 步：添加备用域名
- 在 General 标签页中，点击 Edit
- 在 Alternate domain name (CNAME) 下添加
yoursite.com - 为您的域名选择或申请 SSL 证书
第 5 步：配置 Route 53
创建一个指向 CloudFront 分配的别名记录：
- 打开 Route 53 控制台
- 选择您的托管区域
- 点击 Create Record
- 配置：
| 设置 | 值 |
|---|---|
| 记录名称 | yoursite.com（或留空以用于根域名） |
| 记录类型 | A |
| 别名 | 是 |
| 路由流量到 | CloudFront 分配 |
| 分配 | 选择您的分配 |
第 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 缓存失效，以便在发布更改后清除缓存内容。
如果看到 "Domain is not authorized to serve this content"：
- 确认您的域名已在 Jamdesk 仪表板中注册
- 完成域名的 DNS 验证（TXT 记录）
- 确保源配置中已设置
X-Forwarded-Host和X-Jamdesk-Forwarded-Host自定义标头 - 检查您的域名是否映射到正确的项目
CloudFront 必须在域名完成验证后才能提供文档。
预检会在您的线上域名上请求 /_jd/preflight，并检查实际到达 Jamdesk 的内容。如果报告您的代理“未标识自身”，说明 CloudFront 已到达 Jamdesk，但没有携带 X-Jamdesk-Forwarded-Host — 请重新检查第 2 步中的源自定义标头。有关每条预检消息含义，请参阅仅限自定义域名。