Dokumentation mit Cloudflare in einem Unterordner bereitstellen

Folgen Sie dieser Anleitung, um Ihr Ferndesk-Hilfezentrum mithilfe von Cloudflare Workers als Reverse-Proxy in einem benutzerdefinierten Unterordner (z. B. yourdomain.com/help) bereitzustellen.

Voraussetzungen

• Ein Ferndesk-Arbeitsbereich mit Administratorzugriff

• Eine Domain, die Ihnen gehört (bereits auf Cloudflare verwiesen)

• Grundlegende Vertrautheit mit dem Cloudflare-Dashboard

Schritt 1: Benutzerdefinierten Unterordner in Ferndesk einrichten

Konfigurieren Sie zunächst Ihr Ferndesk-Hilfezentrum so, dass es einen benutzerdefinierten Unterordnerpfad verwendet.

1. Melden Sie sich in Ihrem Ferndesk-Arbeitsbereich an, öffnen Sie Help Center in der linken Seitenleiste und klicken Sie anschließend auf Customize.

2. Klicken Sie auf Custom domain.

   

3. Wählen Sie die Option Custom sub-folder aus.

   

4. Geben Sie Ihre Domain in das Feld Domain ein (z. B. yourdomain.com).

5. Geben Sie den gewünschten Unterordnerpfad in das Feld Subdirectory ein (z. B. /help oder /docs).

6. Klicken Sie auf Configure sub-folder.

Schritt 2: Einen Cloudflare Worker erstellen

Erstellen Sie nun einen neuen Cloudflare Worker, der als Reverse-Proxy fungiert.

1. Melden Sie sich bei Ihrem Cloudflare-Dashboard an.

2. Unter BUILD → Compute & AI, navigieren Sie zu Workers & Pages in der linken Seitenleiste.

   

3. Klicken Sie oben rechts auf Create application.

   

4. Klicken Sie unter Start with Hello World! auf Get started.

   

5. Geben Sie Ihrem Worker einen aussagekräftigen Namen wie ferndesk-reverse-proxy und klicken Sie anschließend auf Deploy.

   

Schritt 3: Worker-Routen konfigurieren

Richten Sie die Routing-Regel ein, die den Datenverkehr von Ihrem benutzerdefinierten Unterordner an den Cloudflare Worker weiterleitet.

1. Öffnen Sie in den Worker-Einstellungen den Tab Settings.

   

2. Scrollen Sie zu Domains & Routes und klicken Sie auf Add.

   

3. Ein modales Fenster wird geöffnet. Wählen Sie die Option Route aus.

   

4. Wählen Sie im Dropdown-Menü Zone Ihre Domain aus (z. B. yourdomain.com).

5. Geben Sie im Feld Route das Muster für Ihren Unterordnerpfad ein. Verwenden Sie yourdomain.com/help, um alle Anfragen an den Pfad /help und seine Unterpfade zu erfassen.

6. Lassen Sie Failure mode aus Sicherheitsgründen auf Fail closed (block) gesetzt.

7. Klicken Sie auf Add route.

   

Schritt 3b: Die Route _ferndesk hinzufügen

1. Scrollen Sie zu Domains & Routes und klicken Sie auf Add.

   

2. Ein modales Fenster wird geöffnet. Wählen Sie die Option Route aus.

   

3. Wählen Sie im Dropdown-Menü Zone Ihre Domain aus (z. B. yourdomain.com).

4. Geben Sie im Feld Route das Muster für Ihren Unterordnerpfad ein. Verwenden Sie yourdomain.com/_ferndesk, um alle Anfragen an den Pfad /_ferndesk und seine Unterpfade zu erfassen.

5. Lassen Sie Failure mode aus Sicherheitsgründen auf Fail closed (block) gesetzt.

6. Klicken Sie auf Add route.

   

Schritt 4: Den Worker-Code bearbeiten

Aktualisieren Sie nun den Worker-Code, damit er die Logik des Reverse-Proxys verarbeitet. Der Worker fängt Anfragen an Ihren Unterordner ab und leitet sie an Ferndesk weiter.

1. Klicken Sie auf Edit code (oder öffnen Sie den Code-Editor über das Worker-Dashboard).

   

2. Ersetzen Sie den gesamten worker.js-Code durch das unten stehende Reverse-Proxy-Skript.

   const HELP_HOST = 'your-company.hc.ferndesk.com'; // your Ferndesk help domain
   const PROXY_PREFIX = '/help'; // the subfolder you chose in Ferndesk
   const PROXY_VERSION = '2';
   
   addEventListener('fetch', (event) => {
   	event.respondWith(handleRequest(event.request));
   });
   
   async function handleRequest(request) {
   	const originalUrl = new URL(request.url);
   
   	// Keep canonical trailing-slash behaviour on the edge
   	if (originalUrl.pathname.endsWith('/') && originalUrl.pathname !== '/') {
   		originalUrl.pathname = originalUrl.pathname.slice(0, -1);
   		return Response.redirect(originalUrl.toString(), 301);
   	}
   
   	// Only intercept the help subtree (and the help assets)
   	if (
   		originalUrl.pathname !== PROXY_PREFIX &&
   		!originalUrl.pathname.startsWith(`${PROXY_PREFIX}/`) &&
   		!originalUrl.pathname.startsWith('/_ferndesk/')
   	) {
   		return fetch(request);
   	}
   
   	// Build the upstream request with the prefix removed
   	const upstreamUrl = new URL(originalUrl.toString());
   	upstreamUrl.hostname = HELP_HOST;
   
   	if (upstreamUrl.pathname === PROXY_PREFIX) {
   		upstreamUrl.pathname = '/';
   	} else if (upstreamUrl.pathname.startsWith(`${PROXY_PREFIX}/`)) {
   		upstreamUrl.pathname = upstreamUrl.pathname.slice(PROXY_PREFIX.length) || '/';
   	}
   
   	// Enables edge caching: tells Ferndesk this render belongs to your
   	// subfolder so it gets its own cache entry.
   	upstreamUrl.searchParams.set('__bp', PROXY_PREFIX);
   
   	const proxyRequest = new Request(upstreamUrl.toString(), request);
   
   	// Let the help app know we are hosted under the subfolder
   	proxyRequest.headers.set('X-Ferndesk-Base-Path', PROXY_PREFIX);
   	proxyRequest.headers.set('X-Forwarded-Host', originalUrl.host);
   	proxyRequest.headers.set('X-Ferndesk-Original-Host', originalUrl.host);
   	proxyRequest.headers.set('X-Ferndesk-Proxy-Version', PROXY_VERSION);
   
   	// Handle redirects ourselves so renamed articles redirect visitors on
   	// this domain instead of being followed silently.
   	const response = await fetch(proxyRequest, { redirect: 'manual' });
   	if (response.status >= 300 && response.status < 400) {
   		return rewriteRedirect(response, originalUrl);
   	}
   	return response;
   }
   
   // Translates an upstream redirect (on the Ferndesk help host) back onto
   // this site's host and subfolder. External redirects pass through as-is.
   function rewriteRedirect(response, originalUrl) {
   	const location = response.headers.get('location');
   	if (!location) return response;
   
   	const target = new URL(location, `https://${HELP_HOST}`);
   	if (target.hostname !== HELP_HOST) return response;
   
   	target.protocol = 'https:';
   	target.host = originalUrl.host;
   	target.searchParams.delete('__bp');
   
   	const alreadyPrefixed =
   		target.pathname === PROXY_PREFIX || target.pathname.startsWith(`${PROXY_PREFIX}/`);
   	if (!alreadyPrefixed) {
   		target.pathname = target.pathname === '/' ? PROXY_PREFIX : PROXY_PREFIX + target.pathname;
   	}
   
   	// Response headers from fetch are immutable; copy to edit Location.
   	const rewritten = new Response(response.body, response);
   	rewritten.headers.set('location', target.toString());
   	return rewritten;
   }
   Ersetzen Sie HELP_HOST durch die tatsächliche Ferndesk-Domain, die beim Konfigurieren Ihres benutzerdefinierten Unterordners bereitgestellt wurde. Ersetzen Sie PROXY_PREFIX, wenn Sie einen anderen Unterordnerpfad verwenden (z. B. /docs statt /help).

   Haben Sie Ihren Unterordner bereits vor einiger Zeit eingerichtet? Ersetzen Sie einfach Ihren Worker-Code durch die oben stehende Version. Alles funktioniert weiterhin genau wie zuvor, und Ihre Hilfezentrumseiten werden ab sofort über unser Edge-Netzwerk bereitgestellt und laden normalerweise in weniger als 100 ms.

3. Klicken Sie auf Deploy, um Ihre Änderungen zu veröffentlichen.

   

Schritt 5: Einrichtung überprüfen

Testen Sie, ob Ihr Hilfezentrum jetzt unter dem benutzerdefinierten Unterordnerpfad erreichbar ist.

1. Öffnen Sie einen neuen Browser-Tab und rufen Sie https://yourdomain.com/help auf.

2. Ihr Ferndesk-Hilfezentrum sollte mit Ihrem Branding geladen werden.

3. Testen Sie einige Seiten, indem Sie auf Links klicken, um sicherzustellen, dass die Navigation ordnungsgemäß funktioniert.

Fehlerbehebung

Nächste Schritte

• Weitere Informationen zur URL-Struktur des Hilfezentrums und zu abschnittsbezogenen Pfaden

• Stattdessen eine benutzerdefinierte Domain (Subdomain) verbinden