Dokumentation mit Cloudflare in einem Unterordner bereitstellen

Folge dieser Anleitung, um dein 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 dir gehört (bereits auf Cloudflare verwiesen)

• Grundlegende Vertrautheit mit dem Cloudflare-Dashboard

Schritt 1: Benutzerdefinierten Unterordner in Ferndesk einrichten

Konfiguriere zunächst dein Ferndesk-Hilfezentrum so, dass es einen benutzerdefinierten Unterordnerpfad verwendet.

1. Melde dich bei deinem Ferndesk-Arbeitsbereich an, erweitere Help Center in der linken Seitenleiste und klicke anschließend auf Customize.

2. Klicke auf Custom domain

3. Wähle die Option Custom sub-folder aus

   

4. Gib deine Domain in das Feld Domain ein (z. B. yourdomain.com).

5. Gib den gewünschten Unterordnerpfad in das Feld Path ein (z. B. /help oder /docs).

6. Klicke auf Configure subdirectory.

Schritt 2: Einen Cloudflare Worker erstellen

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

1. Melde dich bei deinem Cloudflare-Dashboard an.

2. Wähle unter BUILD → Compute & AI, Workers & Pages** in der linken Seitenleiste aus .

   

3. Klicke oben rechts auf Create application.

   

4. Klicke unter Start with Hello World! auf Get started.

   

5. Benenne deinen Worker mit einem aussagekräftigen Namen wie ferndesk-reverse-proxy und klicke anschließend auf Deploy.

   

Schritt 3: Workerrouten konfigurieren

Richte die Routing-Regel ein, die den Traffic von deinem benutzerdefinierten Unterordner an den Cloudflare Worker weiterleitet.

1. Wechsle in den Worker-Einstellungen zum Tab Settings.

   

2. Scrolle zu Domains & Routes und klicke auf Add.

   

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

   

4. Wähle im Dropdown-Menü Zone deine Domain aus (z. B. yourdomain.com).

5. Gib im Feld Route das Muster für deinen Unterordnerpfad ein. Verwende *yourdomain.com/help*, um alle Anfragen an den Pfad /help und seine Unterpfade zu erfassen.

6. Lass Failure mode aus Sicherheitsgründen auf Fail closed (block) eingestellt.

7. Klicke auf Add route.

   

Schritt 3b: Die Route _ferndesk hinzufügen

1. Scrolle zu Domains & Routes und klicke auf Add.

   

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

   

3. Wähle im Dropdown-Menü Zone deine Domain aus (z. B. yourdomain.com).

4. Gib im Feld Route das Muster für deinen Unterordnerpfad ein. Verwende *yourdomain.com/_ferndesk*, um alle Anfragen an den Pfad /_ferndesk und seine Unterpfade zu erfassen.

5. Lass Failure mode aus Sicherheitsgründen auf Fail closed (block) eingestellt.

6. Klicke auf Add route.

   

Schritt 4: Den Worker-Code bearbeiten

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

1. Klicke auf Edit code (oder öffne den Code-Editor über das Worker-Dashboard).

   

2. Ersetze den gesamten worker.js-Code durch das folgende 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;
   }
   Ersetze HELP_HOST durch die tatsächliche Ferndesk-Domain, die dir bei der Konfiguration deines benutzerdefinierten Unterordners bereitgestellt wurde. Ersetze PROXY_PREFIX, wenn du einen anderen Unterordnerpfad verwendest (z. B. /docs statt /help).

   Du hast deinen Unterordner bereits vor einiger Zeit eingerichtet? Ersetze einfach deinen Worker-Code durch die obige Version. Alles funktioniert weiterhin genau wie zuvor, und die Seiten deines Hilfezentrums werden über unser Edge-Netzwerk bereitgestellt – in der Regel mit einer Ladezeit von weniger als 100 ms.

3. Klicke auf Deploy, um deine Änderungen zu veröffentlichen.

   

Schritt 5: Einrichtung überprüfen

Teste, ob dein Hilfezentrum jetzt unter deinem benutzerdefinierten Unterordnerpfad erreichbar ist.

1. Öffne einen neuen Browser-Tab und rufe https://yourdomain.com/help auf.

2. Dein Ferndesk-Hilfezentrum sollte mit deinem Branding geladen werden.

3. Teste einige Seiten, indem du auf Links klickst, um sicherzustellen, dass die Navigation ordnungsgemäß funktioniert.

Fehlerbehebung

Nächste Schritte

• Mehr über die URL-Struktur des Hilfezentrums und abschnittsbezogene Pfade erfahren

• Stattdessen eine benutzerdefinierte Domain (Subdomain) verbinden