Pon tus docs 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) usando Cloudflare Workers como proxy inverso.

Requisitos previos

• Un espacio de trabajo de Ferndesk con acceso de administrador

• Un dominio que poseas (ya apuntado a Cloudflare)

• Familiaridad básica con el panel de Cloudflare

Paso 1: Configura la subcarpeta personalizada en Ferndesk

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

1. Inicia sesión en tu espacio de trabajo de Ferndesk, despliega Help Center en la barra lateral izquierda y luego 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 deseas 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 nuevo Cloudflare Worker que actuará como proxy inverso.

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

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

   

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

   

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

   

5. Ponle a tu Worker un nombre descriptivo como ferndesk-reverse-proxy y luego 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 desplegable Zone, selecciona tu dominio (por ejemplo, yourdomain.com).

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

6. Deja Failure mode en Fail closed (block) por motivos de seguridad.

7. Haz clic en Add route.

   

Paso 3b: Añadir 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 desplegable Zone, selecciona tu dominio (por ejemplo, yourdomain.com).

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

5. Deja Failure mode en Fail closed (block) por motivos de seguridad.

6. Haz clic en Add route.

   

Paso 4: Edita el código del Worker

Ahora actualiza el código del Worker para manejar 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 con 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 con el dominio real de Ferndesk proporcionado cuando configuraste tu subcarpeta personalizada. Reemplaza PROXY_PREFIX si estás usando una ruta de subcarpeta diferente (por ejemplo, /docs en lugar de /help).

   ¿Ya habías configurado tu subcarpeta hace tiempo? Solo reemplaza el código de tu worker con la versión anterior. Todo seguirá funcionando exactamente igual que antes y las páginas de tu centro de ayuda comenzarán a servirse desde nuestra red perimetral, normalmente cargando 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 sea accesible en la ruta de tu subcarpeta personalizada.

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

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

3. Prueba algunas páginas haciendo clic en enlaces para asegurarte de que la navegación funcione correctamente.

Solución de problemas

Próximos pasos

• Más información sobre la estructura de URL del centro de ayuda y las rutas que tienen en cuenta la sección

• Conectar un dominio personalizado (subdominio) en su lugar