Publica tu documentación en una subcarpeta con Cloudflare

Sigue esta guía para alojar tu centro de ayuda de Ferndesk en una subcarpeta personalizada (como yourdomain.com/help) utilizando Cloudflare Workers como proxy inverso.

Requisitos previos

• Un espacio de trabajo de Ferndesk con acceso de administrador

• Un dominio de tu propiedad (ya apuntado a Cloudflare)

• Conocimientos básicos del panel de Cloudflare

Paso 1: Configura la subcarpeta personalizada en Ferndesk

Primero, configura tu centro de ayuda de Ferndesk para que utilice una ruta de subcarpeta personalizada.

1. Inicia sesión en tu espacio de trabajo de Ferndesk, expande Help Center en la barra lateral izquierda y haz clic en Customize.

2. Haz clic en Custom domain

   

3. Selecciona la opción Custom sub-folder

   

4. Introduce tu dominio en el campo Domain (por ejemplo, yourdomain.com).

5. Introduce la ruta de subcarpeta que quieras en el campo Subdirectory (por ejemplo, /help o /docs).

6. Haz clic en Configure sub-folder.

Paso 2: Crea un Cloudflare Worker

Ahora crea un Cloudflare Worker nuevo que actuará como proxy inverso.

1. Inicia sesión en tu panel de Cloudflare.

2. En BUILD → Compute & AI, navega a Workers & Pages desde la barra lateral .

   

3. Haz clic en Create application en la esquina superior derecha.

   

4. En Start with Hello World!, haz clic en Get started.

   

5. Asigna a tu Worker un nombre descriptivo, como ferndesk-reverse-proxy, y haz clic en Deploy.

   

Paso 3: Configura las rutas del Worker

Configura la regla de enrutamiento que dirige el tráfico desde tu subcarpeta personalizada al Cloudflare Worker.

1. En la configuración del Worker, ve a la pestaña Settings.

   

2. Desplázate hasta Domains & Routes y haz clic en Add.

   

3. Se abrirá una ventana modal. Selecciona la opción Route.

   

4. En el menú desplegable Zone, selecciona tu dominio (por ejemplo, yourdomain.com).

5. En el campo Route, introduce el patrón de tu ruta de subcarpeta. Usa yourdomain.com/help para capturar todas las solicitudes a la ruta /help y sus subrutas.

6. Por motivos de seguridad, deja Failure mode configurado como Fail closed (block).

7. Haz clic en Add route.

   

Paso 3b: Añade la ruta _ferndesk

1. Desplázate hasta Domains & Routes y haz clic en Add.

   

2. Se abrirá una ventana modal. Selecciona la opción Route.

   

3. En el menú desplegable Zone, selecciona tu dominio (por ejemplo, yourdomain.com).

4. En el campo Route, introduce el patrón de tu ruta de subcarpeta. Usa yourdomain.com/_ferndesk para capturar todas las solicitudes a la ruta /_ferndesk y sus subrutas.

5. Por motivos de seguridad, deja Failure mode configurado como Fail closed (block).

6. Haz clic en Add route.

   

Paso 4: Edita el código del Worker

Ahora actualiza el código del Worker para gestionar la lógica del proxy inverso. El Worker interceptará las solicitudes a tu subcarpeta y las reenviará a Ferndesk.

1. Haz clic en Edit code (o accede al editor de código desde el panel del Worker).

   

2. Reemplaza todo el código de worker.js por el script de proxy inverso que aparece a continuación.

   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;
   }
   Reemplaza HELP_HOST por el dominio real de Ferndesk que se proporcionó al configurar la subcarpeta personalizada. Reemplaza PROXY_PREFIX si utilizas una ruta de subcarpeta diferente (por ejemplo, /docs en lugar de /help).

   ¿Ya configuraste tu subcarpeta hace algún tiempo? Simplemente reemplaza el código de tu Worker por la versión anterior. Todo seguirá funcionando exactamente igual y las páginas de tu centro de ayuda comenzarán a servirse desde nuestra red perimetral, normalmente en menos de 100 ms.

3. Haz clic en Deploy para publicar los cambios.

   

Paso 5: Verifica la configuración

Comprueba que tu centro de ayuda ya esté accesible en la ruta de tu subcarpeta personalizada.

1. Abre una pestaña nueva del navegador y ve a https://yourdomain.com/help.

2. Deberías ver tu centro de ayuda de Ferndesk cargado con tu identidad de marca.

3. Prueba varias páginas haciendo clic en los enlaces para asegurarte de que la navegación funciona correctamente.

Solución de problemas

Siguientes pasos

• Obtén más información sobre la estructura de las URL del centro de ayuda y las rutas adaptadas a las secciones

• Conecta un dominio personalizado (subdominio) en su lugar