AWS Route 53 & CloudFront
Leiten Sie /docs-Traffic über AWS CloudFront und Route 53 an Ihre Jamdesk-Seite weiter. Mit Distribution-Setup, Origin-Konfiguration und Cache-Regeln.
Richten Sie eine CloudFront-Distribution ein, die /docs/* an Ihre Jamdesk-Seite weiterleitet, mit Route 53 für DNS. Dauert etwa 15 Minuten.
Voraussetzungen
- Ein AWS-Konto mit Zugriff auf CloudFront und Route 53
- Ihre Domain, verwaltet in Route 53 (oder die Möglichkeit, DNS anderswo zu aktualisieren)
- Ihre Jamdesk-Subdomain (zu finden in den Dashboard-Einstellungen)
- Ihre benutzerdefinierte Domain, registriert und per DNS verifiziert im Jamdesk-Dashboard
Wenn Sie anstelle des Standardpfads /docs einen eigenen Unterpfad verwenden, ersetzen Sie /docs/* im Pfadmuster der Cache-Verhaltensregel (Schritt 3) durch Ihren Unterpfad. Aktualisieren Sie die Distribution erneut nach jeder Umbenennung im Dashboard.
Schritt 1: CloudFront-Distribution erstellen
- Öffnen Sie die CloudFront-Konsole
- Klicken Sie auf Create Distribution
- Konfigurieren Sie den Origin:
| Einstellung | Wert |
|---|---|
| Origin-Domain | YOUR_SLUG.jamdesk.app |
| Protokoll | Nur HTTPS |
| Name | jamdesk-docs-origin |
Ersetzen Sie YOUR_SLUG durch Ihre Jamdesk-Subdomain.
Schritt 2: Origin-Einstellungen konfigurieren
Fügen Sie in den Origin-Einstellungen benutzerdefinierte Header hinzu, um Ihre Domain zu identifizieren:
| Header-Name | Wert |
|---|---|
X-Forwarded-Host | yoursite.com |
X-Jamdesk-Forwarded-Host | yoursite.com |
Diese Header teilen Jamdesk mit, welche Domain die Anfrage stellt.
Dieser Schritt ist erforderlich. Wenn Sie ihn überspringen, schlägt es stillschweigend fehl. Die Richtlinie AllViewerExceptHostHeader (nächster Schritt) leitet nur Header weiter, die der Browser Ihres Besuchers gesendet hat. Sie fügt keine neuen hinzu. X-Jamdesk-Forwarded-Host erreicht Jamdesk nur als benutzerdefinierter Origin-Header. Ohne ihn funktionieren Anfragen weiterhin, aber Seiten werden mit noindex ausgeliefert, und die canonical-Links zeigen auf YOUR_SLUG.jamdesk.app statt auf Ihre Domain.
Statische Origin-Header können sich nicht pro Anfrage unterscheiden. Um mehrere alternative Domainnamen über eine Distribution zu bedienen, verwenden Sie stattdessen eine CloudFront-Funktion bei Viewer Request. Sie setzt request.headers['x-jamdesk-forwarded-host'] = { value: request.headers.host.value }.
Schritt 3: Cache-Verhalten erstellen
Fügen Sie Verhaltensregeln hinzu, um /docs/*- und Asset-Anfragen an Ihren Jamdesk-Origin weiterzuleiten:
- Wechseln Sie zum Tab Behaviors
- Klicken Sie auf Create Behavior
- Erstellen Sie drei Verhaltensregeln mit diesen Einstellungen:
| Pfadmuster | Origin | Cache-Richtlinie | Origin-Request-Richtlinie |
|---|---|---|---|
/docs/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_next/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
/_jd/* | jamdesk-docs-origin | CachingOptimized | AllViewerExceptHostHeader |
Setzen Sie die Viewer protocol policy für alle drei auf Redirect HTTP to HTTPS.
Jedes Verhalten ist erforderlich. /_next/* und /_jd/* liefern das JavaScript, CSS, die Schriften und Bilder, die Ihre Dokumentationsseiten laden. Die Richtlinie AllViewerExceptHostHeader leitet die Request-Header des Viewers weiter (alles außer Host, das CloudFront für den Origin reserviert). Setzen Sie sie für alle drei.
Schritt 4: Alternativen Domainnamen hinzufügen
- Klicken Sie im Tab General auf Edit
- Fügen Sie unter Alternate domain name (CNAME)
yoursite.comhinzu - Wählen Sie ein SSL-Zertifikat für Ihre Domain aus oder beantragen Sie eines
Schritt 5: Route 53 konfigurieren
Erstellen Sie einen Alias-Eintrag, der auf Ihre CloudFront-Distribution verweist:
- Öffnen Sie die Route-53-Konsole
- Wählen Sie Ihre Hosted Zone aus
- Klicken Sie auf Create Record
- Konfigurieren Sie:
| Einstellung | Wert |
|---|---|
| Record name | yoursite.com (oder für die Apex-Domain leer lassen) |
| Record type | A |
| Alias | Ja |
| Route traffic to | CloudFront distribution |
| Distribution | Wählen Sie Ihre Distribution aus |
Schritt 6: Überprüfen
Warten Sie auf die DNS-Propagierung (in der Regel 5–15 Minuten). Rufen Sie dann https://yoursite.com/docs auf und prüfen Sie, ob Ihre Dokumentation geladen wird.
Vollständige Zusammenfassung der CloudFront-Konfiguration
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)Fehlerbehebung
Prüfen Sie, ob die Origin-Domain genau YOUR_SLUG.jamdesk.app lautet, ohne das Präfix https://.
Prüfen Sie, ob die Viewer protocol policy auf „Redirect HTTP to HTTPS“ gesetzt ist und Ihr SSL-Zertifikat gültig ist.
Erstellen Sie eine CloudFront-Invalidierung für /docs/*, um zwischengespeicherte Inhalte nach Veröffentlichung von Änderungen zu leeren.
Wenn Sie „Domain is not authorized to serve this content“ sehen:
- Prüfen Sie, ob Ihre Domain im Jamdesk-Dashboard registriert ist
- Schließen Sie die DNS-Verifizierung (TXT-Eintrag) für Ihre Domain ab
- Setzen Sie die benutzerdefinierten Header
X-Forwarded-HostundX-Jamdesk-Forwarded-Hostin Ihrer Origin-Konfiguration - Prüfen Sie, ob Ihre Domain dem richtigen Projekt zugeordnet ist
Die Domain muss verifiziert sein, bevor CloudFront die Dokumentation ausliefern kann.
Die Preflight-Prüfung ruft /_jd/preflight auf Ihrer Live-Domain ab und prüft, was bei Jamdesk angekommen ist. Wenn sie meldet, dass Ihr Proxy sich „nicht identifiziert“, erreicht CloudFront Jamdesk ohne X-Jamdesk-Forwarded-Host. Prüfen Sie den Origin-Custom-Header in Schritt 2 erneut. Was die einzelnen Preflight-Meldungen bedeuten, finden Sie unter Nur benutzerdefinierte Domain.