Platziere deine Docs in einem Unterordner mit Cloudflare

Folge dieser Anleitung, um dein Ferndesk Help Center in einem benutzerdefinierten Unterordner wie yourdomain.com/help mit Cloudflare Workers als Reverse-Proxy zu hosten.

Voraussetzungen

• Ein Ferndesk-Workspace mit Admin-Zugriff

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

• Grundkenntnisse im Cloudflare-Dashboard

Schritt 1: Den benutzerdefinierten Unterordner in Ferndesk einrichten

Konfiguriere zuerst dein Ferndesk Help Center so, dass es einen benutzerdefinierten Unterordnerpfad verwendet.

1. Melde dich in deinem Ferndesk-Workspace an, erweitere Help Center in der linken Seitenleiste und klicke dann auf Customize.

2. Klicke auf Custom domain

   

3. Wähle die Option Custom sub-folder

   

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

5. Gib den gewünschten Unterordnerpfad im Feld Subdirectory ein (z. B. /help oder /docs).

6. Klicke auf Configure sub-folder.

Schritt 2: Einen Cloudflare Worker erstellen

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

1. Melde dich im Cloudflare-Dashboard an.

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

   

3. Klicke oben rechts auf Create application.

   

4. Unter Start with Hello World! klicke auf Get started.

   

5. Gib deinem Worker einen aussagekräftigen Namen wie ferndesk-reverse-proxy und klicke dann auf Deploy.

   

Schritt 3: Die Worker-Routen konfigurieren

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

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

   

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

   

3. Ein modales Fenster öffnet sich. Wähle die Option Route.

   

4. Wähle im Dropdown 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. Lasse 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 öffnet sich. Wähle die Option Route.

   

3. Wähle im Dropdown 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. Lasse Failure mode aus Sicherheitsgründen auf Fail closed (block) eingestellt.

6. Klicke auf Add route.

   

Schritt 4: Den Worker-Code bearbeiten

Aktualisiere jetzt den Worker-Code, damit die Reverse-Proxy-Logik funktioniert. 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 Code in worker.js 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;
   }
   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).

   Hast du deinen Unterordner schon vor einiger Zeit eingerichtet? Ersetze einfach deinen Worker-Code durch die obige Version. Alles funktioniert weiterhin wie bisher, und deine Help-Center-Seiten werden nun über unser Edge-Netzwerk ausgeliefert, typischerweise mit Ladezeiten unter 100 ms.

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

   

Schritt 5: Das Setup überprüfen

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

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

2. Du solltest sehen, wie dein Ferndesk Help Center mit deinem Branding geladen wird.

3. Teste ein paar Seiten, indem du auf Links klickst, um sicherzustellen, dass die Navigation korrekt funktioniert.

Fehlerbehebung

Nächste Schritte

• Mehr über die URL-Struktur des Help Centers und bereichsbezogene Pfade erfahren

• Stattdessen eine benutzerdefinierte Domain (Subdomain) verbinden