Ihre Dokumentation mit Vercel in einem Unterordner bereitstellen

Befolgen Sie diese Anleitung, um Ihr Ferndesk-Hilfezentrum mithilfe des External-Origin-Proxys von Vercel in einem benutzerdefinierten Unterordner (z. B. yourdomain.com/help) zu hosten.

Dies dauert ungefähr 10 Minuten und erfordert ein Vercel-Projekt, in dem Sie eine Konfigurationsdatei vercel.json hinzufügen können.

Stecken Sie fest? Kontaktieren Sie [email protected], und wir helfen Ihnen bei der Einrichtung.

Voraussetzungen

Ein Ferndesk-Arbeitsbereich mit Administratorzugriff
Ein Vercel-Projekt, über das Ihre Hauptwebsite bereitgestellt wird
Zugriff zum Hinzufügen einer Datei vercel.json zum Stammverzeichnis Ihres Projekts

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 so, dass es einen benutzerdefinierten Unterordnerpfad verwendet.

Hilfezentrum-Einstellungen öffnen

Melden Sie sich bei Ihrem Ferndesk-Arbeitsbereich an, blenden Sie Hilfezentrum in der linken Seitenleiste ein 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 im Feld Domain ein (z. B. www.example.com) und anschließend den gewünschten Unterordnerpfad im Feld Unterverzeichnis (z. B. /help oder /docs).

Ferndesk-Host speichern und kopieren

Klicken Sie auf Unterordner konfigurieren. Kopieren Sie nach der Konfiguration den Ferndesk-Proxy-Host (z. B. acme.hc.ferndesk.com) – Sie benötigen ihn für die Vercel-Konfiguration.

Verwenden Sie Ihren exakten Vercel-Produktionshostname (z. B. www.example.com) und 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 Stammverzeichnis Ihres Projekts, um Anfragen an Ferndesk weiterzuleiten. Diese Konfiguration verwendet die routes von Vercel 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 Projektstamm noch keine Datei vercel.json 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 Datei vercel.json 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____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__",
      "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 dem 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 Antworten mit Not found 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 dem benutzerdefinierten Unterordnerpfad erreichbar ist.

URL des Unterordners öffnen

Rufen Sie in Ihrem Browser https://yourdomain.com/help (oder den von Ihnen 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

Öffnen Sie einige Artikel, um zu bestätigen, dass die Navigation funktioniert. Überprüfen Sie, ob Styling, Bilder und JavaScript korrekt geladen werden.

Wenn Ihr Hilfezentrum mit funktionierender Navigation und korrektem Styling geladen wird, ist der Reverse Proxy richtig konfiguriert. Ihre Kunden können nun über den benutzerdefinierten Unterordnerpfad auf Ihr Hilfezentrum zugreifen.

Fehlerbehebung

Problem	Ursache	Lösung
404-Not-Found-Fehler	Routen nicht konfiguriert oder Bereitstellung nicht abgeschlossen	Überprüfen Sie, ob sich `vercel.json` im Stammverzeichnis Ihres Projekts befindet und die Bereitstellung abgeschlossen ist. Stellen Sie sicher, dass alle Platzhalter durch tatsächliche Werte ersetzt wurden.
Leere Seite oder fehlerhaftes Styling	Ferndesk-Host oder Basispfad ist falsch	Überprüfen Sie nochmals, ob `FERNDESK_HOST` mit dem Host aus Ihrem Ferndesk-Dashboard und `BASE_PATH` exakt mit Ihrem konfigurierten Unterordner übereinstimmt.
Assets oder CSS werden nach der Ersteinrichtung nicht geladen	Vercel hat eine veraltete Antwort zwischengespeichert	Stellen Sie Ihr Vercel-Projekt erneut bereit, um zwischengespeicherte Antworten zu löschen. Die Konfiguration `headers` sollte dies bei zukünftigen Anfragen verhindern.
Hilfezentrum funktioniert, aber der Hostname stimmt nicht überein	Falscher öffentlicher Host in den Routen	Stellen Sie sicher, dass `PUBLIC_HOST` Ihr Produktionshostname ist (z. B. `www.example.com`) und keine Vercel-Vorschau-URL.

Etwas ist schiefgelaufen? Kontaktieren Sie uns unter [email protected], und wir helfen Ihnen bei 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 Domain entfernen.

Vercel-Routen entfernen

Löschen Sie die Ferndesk-bezogenen Einträge headers und routes aus Ihrer Datei vercel.json oder kommentieren Sie sie aus, und stellen Sie das Projekt anschließend erneut bereit.

Nächste Schritte

War das hilfreich?