Stellen Sie Ihre Dokumentation mit Vercel in einem Unterordner bereit
Befolgen Sie diese Anleitung, um Ihr Ferndesk-Hilfezentrum mithilfe des External-Origin-Proxyings von Vercel in einem benutzerdefinierten Unterordner (z. B. yourdomain.com/help) bereitzustellen.
Dies dauert ungefähr 10 Minuten und erfordert ein Vercel-Projekt, in dem Sie eine vercel.json-Konfigurationsdatei hinzufügen können.
Kommen Sie nicht weiter? Kontaktieren Sie [email protected], und wir helfen Ihnen beim Abschließen der Einrichtung.
Voraussetzungen
Ein Ferndesk-Arbeitsbereich mit Administratorzugriff
Ein Vercel-Projekt, das Ihre Hauptwebsite bereitstellt
Zugriff zum Hinzufügen einer
vercel.json-Datei zum Projektstammverzeichnis
Für die Konfiguration eines benutzerdefinierten Unterordners muss eine aktive Zahlungsmethode hinterlegt sein.
Schritt 1: Unterordner in Ferndesk konfigurieren
Konfigurieren Sie zunächst Ihr Ferndesk-Hilfezentrum für die Verwendung eines benutzerdefinierten Unterordnerpfads.
Hilfezentrum-Einstellungen öffnen
Melden Sie sich bei Ihrem Ferndesk-Arbeitsbereich an, erweitern Sie Hilfezentrum in der linken Seitenleiste und klicken Sie anschließend auf Anpassen.
Benutzerdefinierten Unterordner auswählen
Klicken Sie auf Benutzerdefinierte Domain.
Wählen Sie die Option Benutzerdefinierter Unterordner aus.
Domain und Unterordner eingeben
Geben Sie Ihre Domain in das Feld Domain ein (z. B. www.example.com) und anschließend den gewünschten Unterordnerpfad in das Feld Pfad (z. B. /help oder /docs).
Ferndesk-Host speichern und kopieren
Klicken Sie auf Unterverzeichnis konfigurieren. Kopieren Sie nach der Konfiguration den Ferndesk-Proxy-Host (z. B. acme.hc.ferndesk.com), da Sie ihn für die Vercel-Konfiguration benötigen.
Verwenden Sie Ihren exakten Vercel-Produktionshostnamen (z. B. www.example.com), nicht den Hostnamen einer Vorschau-Bereitstellung. Wenn sich der Hostname nach der ersten Bereitstellung ändert, können veraltete Cache-Einträge bestehen bleiben.
Schritt 2: Vercel-Routing-Konfiguration hinzufügen
Erstellen oder aktualisieren Sie vercel.json im Projektstammverzeichnis, um Anfragen an Ferndesk weiterzuleiten. Diese Konfiguration verwendet Vercels routes mit Transformationen von Anfrage-Headern, um Ferndesk den erforderlichen Basispfad und die erforderlichen Hostinformationen zu übermitteln.
vercel.json erstellen oder öffnen
Wenn sich in Ihrem Projektstammverzeichnis noch keine vercel.json-Datei befindet, erstellen Sie eine. Falls bereits eine vorhanden ist, öffnen Sie sie zur Bearbeitung.
Konfiguration hinzufügen
Fügen Sie die folgende Konfiguration in Ihre vercel.json-Datei ein. Ersetzen Sie die Platzhalter durch Ihre tatsächlichen Werte:
PUBLIC_HOST — Ihr Vercel-Produktionshostname (z. B.
www.example.com)FERNDESK_HOST — der Ferndesk-Host, den Sie aus dem Ferndesk-Dashboard kopiert haben (z. B.
acme.hc.ferndesk.com)BASE_PATH — Ihr Unterordnerpfad einschließlich des führenden Schrägstrichs (z. B.
/help)
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"headers": [
{
"source": "/_ferndesk",
"headers": [
{ "key": "x-vercel-enable-rewrite-caching", "value": "0" }
]
},
{
"source": "/_ferndesk/:match*",
"headers": [
{ "key": "x-vercel-enable-rewrite-caching", "value": "0" }
]
},
{
"source": "__BASE_PATH__",
"headers": [
{ "key": "x-vercel-enable-rewrite-caching", "value": "0" }
]
},
{
"source": "__BASE_PATH__/:match*",
"headers": [
{ "key": "x-vercel-enable-rewrite-caching", "value": "0" }
]
}
],
"routes": [
{
"src": "/_ferndesk",
"dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
},
{
"src": "/_ferndesk/(.*)",
"dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk/$1?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
},
{
"src": "__BASE_PATH__/_ferndesk",
"dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
},
{
"src": "__BASE_PATH__/_ferndesk/(.*)",
"dest": "https://__FERNDESK_HOST__/_ferndesk/$1?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
},
{
"src": "__BASE_PATH__",
"dest": "https://__FERNDESK_HOST__/?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
},
{
"src": "__BASE_PATH__/(.*)",
"dest": "https://__FERNDESK_HOST__/$1?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
}
]
}Der Parameter __bp ermöglicht es Ferndesk, Ihre Hilfeseiten aus seinem Edge-Cache bereitzustellen, sodass sie weltweit deutlich unter einer Sekunde geladen werden.
Projekt bereitstellen
Committen und pushen Sie Ihre Änderungen, um eine neue Vercel-Bereitstellung auszulösen. Die neue Routing-Konfiguration wird wirksam, sobald die Bereitstellung abgeschlossen ist.
Der Abschnitt headers deaktiviert das Rewrite-Caching von Vercel für Ferndesk-Pfade. Dadurch wird verhindert, dass veraltete Not found-Antworten zwischengespeichert werden, wenn Ferndesk-Assets oder -Seiten angefordert werden, bevor der Proxy vollständig konfiguriert ist.
Schritt 3: Einrichtung überprüfen
Testen Sie, ob Ihr Hilfezentrum jetzt unter Ihrem benutzerdefinierten Unterordnerpfad erreichbar ist.
URL des Unterordners öffnen
Rufen Sie in Ihrem Browser https://yourdomain.com/help (oder Ihren gewählten Unterordnerpfad) auf.
Überprüfen, ob das Hilfezentrum geladen wird
Sie sollten Ihr Ferndesk-Hilfezentrum mit Ihrem Branding und Ihren Inhalten sehen.
Navigation und Assets testen
Klicken Sie einige Artikel durch, um zu bestätigen, dass die Navigation funktioniert. Überprüfen Sie, ob Styles, Bilder und JavaScript korrekt geladen werden.
Wenn Ihr Hilfezentrum mit funktionierender Navigation und korrekten Styles geladen wird, ist der Reverse-Proxy richtig konfiguriert. Ihre Kunden können nun unter Ihrem benutzerdefinierten Unterordnerpfad auf Ihr Hilfezentrum zugreifen.
Fehlerbehebung
Problem | Ursache | Lösung |
|---|---|---|
404-Fehler „Not Found“ | Routen nicht konfiguriert oder Bereitstellung nicht abgeschlossen | Überprüfen Sie, ob sich |
Leere Seite oder fehlerhafte Styles | Ferndesk-Host oder Basispfad ist falsch | Überprüfen Sie nochmals, ob |
Assets oder CSS werden nach der ersten Einrichtung nicht geladen | Vercel hat eine veraltete Antwort zwischengespeichert | Stellen Sie Ihr Vercel-Projekt erneut bereit, um zwischengespeicherte Antworten zu löschen. Die |
Hilfezentrum funktioniert, aber der Hostname stimmt nicht überein | Falscher öffentlicher Host in den Routen | Stellen Sie sicher, dass |
Etwas ist schiefgelaufen? Kontaktieren Sie uns unter [email protected], und wir helfen Ihnen beim Abschließen der Einrichtung.
Unterordner entfernen
So beenden Sie die Verwendung des benutzerdefinierten Unterordners und kehren zu Ihrer standardmäßigen Ferndesk-URL zurück:
Domain in Ferndesk entfernen
Gehen Sie in Ferndesk zu Hilfezentrum → Anpassen → Benutzerdefinierte Domain und klicken Sie auf Unterverzeichnis entfernen.
Vercel-Routen entfernen
Löschen Sie die Ferndesk-bezogenen Einträge headers und routes aus Ihrer vercel.json-Datei oder kommentieren Sie sie aus, und stellen Sie das Projekt anschließend erneut bereit.