Publica tu documentación en una subcarpeta con Vercel
Sigue esta guía para alojar tu centro de ayuda de Ferndesk en una subcarpeta personalizada (como yourdomain.com/help) mediante el proxy de origen externo de Vercel.
Esto tarda aproximadamente 10 minutos y requiere un proyecto de Vercel en el que puedas añadir un archivo de configuración vercel.json.
¿Tienes algún problema? Contacta con [email protected] y te ayudaremos a completar la configuración.
Requisitos previos
Un espacio de trabajo de Ferndesk con acceso de administrador
Un proyecto de Vercel que sirva tu sitio web principal
Acceso para añadir un archivo
vercel.jsona la raíz de tu proyecto
La configuración de una subcarpeta personalizada requiere tener un método de pago activo registrado.
Paso 1: Configura la subcarpeta en Ferndesk
Primero, configura tu centro de ayuda de Ferndesk para usar una ruta de subcarpeta personalizada.
Abre la configuración del centro de ayuda
Inicia sesión en tu espacio de trabajo de Ferndesk, expande Centro de ayuda en la barra lateral izquierda y haz clic en Personalizar.
Selecciona Subcarpeta personalizada
Haz clic en Dominio personalizado.
Selecciona la opción Subcarpeta personalizada.
Introduce tu dominio y la subcarpeta
Introduce tu dominio en el campo Dominio (por ejemplo, www.example.com) y, a continuación, introduce la ruta de subcarpeta que quieras en el campo Subdirectorio (por ejemplo, /help o /docs).
Guarda y copia el host de Ferndesk
Haz clic en Configurar subcarpeta. Una vez configurada, copia el host del proxy de Ferndesk (por ejemplo, acme.hc.ferndesk.com); lo necesitarás para la configuración de Vercel.
Usa el nombre de host exacto de producción de Vercel (por ejemplo, www.example.com), no el nombre de host de una implementación de vista previa. Si el nombre de host cambia después de la primera implementación, es posible que queden entradas obsoletas en la caché.
Paso 2: Añade la configuración de enrutamiento de Vercel
Crea o actualiza vercel.json en la raíz de tu proyecto para enviar las solicitudes mediante proxy a Ferndesk. Esta configuración utiliza las routes de Vercel con transformaciones de encabezados de solicitud para enviar a Ferndesk la ruta base y la información del host necesarias.
Crea o abre vercel.json
Si todavía no tienes un archivo vercel.json en la raíz de tu proyecto, créalo. Si ya lo tienes, ábrelo para editarlo.
Añade la configuración
Pega la configuración siguiente en tu archivo vercel.json. Sustituye los marcadores de posición por tus valores reales:
PUBLIC_HOST — el nombre de host de producción de Vercel (por ejemplo,
www.example.com)FERNDESK_HOST — el host de Ferndesk que copiaste del panel de Ferndesk (por ejemplo,
acme.hc.ferndesk.com)BASE_PATH — la ruta de tu subcarpeta, incluida la barra inicial (por ejemplo,
/help)
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"headers": [
{
"source": "/_ferndesk",
"headers": [
{ "key": "x-vercel-enable-rewrite-caching", "value": "0" }
]
},
{
"source": "/_ferndesk/:match*",
"headers": [
{ "key": "x-vercel-enable-rewrite-caching", "value": "0" }
]
},
{
"source": "__BASE_PATH__",
"headers": [
{ "key": "x-vercel-enable-rewrite-caching", "value": "0" }
]
},
{
"source": "__BASE_PATH__/:match*",
"headers": [
{ "key": "x-vercel-enable-rewrite-caching", "value": "0" }
]
}
],
"routes": [
{
"src": "/_ferndesk",
"dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
},
{
"src": "/_ferndesk/(.*)",
"dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk/$1?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
},
{
"src": "__BASE_PATH__/_ferndesk",
"dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
},
{
"src": "__BASE_PATH__/_ferndesk/(.*)",
"dest": "https://__FERNDESK_HOST____BASE_PATH__/_ferndesk/$1?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
},
{
"src": "__BASE_PATH__",
"dest": "https://__FERNDESK_HOST__/?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
},
{
"src": "__BASE_PATH__/(.*)",
"dest": "https://__FERNDESK_HOST__/$1?__bp=__BASE_PATH__",
"transforms": [
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-base-path" }, "args": "__BASE_PATH__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-forwarded-host" }, "args": "__PUBLIC_HOST__" },
{ "type": "request.headers", "op": "set", "target": { "key": "x-ferndesk-original-host" }, "args": "__PUBLIC_HOST__" }
]
}
]
}El parámetro __bp permite que Ferndesk sirva tus páginas de ayuda desde su caché perimetral, por lo que se cargan en mucho menos de un segundo en todo el mundo.
Implementa tu proyecto
Confirma y sube tus cambios para activar una nueva implementación de Vercel. La nueva configuración de enrutamiento surtirá efecto cuando se complete la implementación.
La sección headers desactiva el almacenamiento en caché de las reescrituras de Vercel en las rutas de Ferndesk. Esto evita que se almacenen en caché respuestas obsoletas de Not found cuando se solicitan recursos o páginas de Ferndesk antes de que el proxy esté completamente configurado.
Paso 3: Verifica la configuración
Comprueba que tu centro de ayuda ya esté disponible en la ruta de tu subcarpeta personalizada.
Abre la URL de tu subcarpeta
Accede a https://yourdomain.com/help (o a la ruta de subcarpeta que hayas elegido) desde tu navegador.
Comprueba que se carga el centro de ayuda
Deberías ver tu centro de ayuda de Ferndesk con tu marca y contenido.
Prueba la navegación y los recursos
Abre varios artículos para confirmar que la navegación funciona. Comprueba que los estilos, las imágenes y JavaScript se carguen correctamente.
Si tu centro de ayuda se carga con la navegación y los estilos funcionando, el proxy inverso está configurado correctamente. Tus clientes ya pueden acceder a tu centro de ayuda en la ruta de tu subcarpeta personalizada.
Solución de problemas
Problema | Causa | Solución |
|---|---|---|
Error 404 Not Found | Las rutas no están configuradas o la implementación no ha terminado | Verifica que |
Página en blanco o estilos dañados | El host de Ferndesk o la ruta base son incorrectos | Comprueba que |
Los recursos o el CSS no se cargan después de la configuración inicial | Vercel almacenó en caché una respuesta obsoleta | Vuelve a implementar tu proyecto de Vercel para borrar las respuestas almacenadas en caché. La configuración de |
El centro de ayuda funciona, pero el nombre de host no coincide | El host público de las rutas es incorrecto | Asegúrate de que |
¿Algo salió mal? Contáctanos en [email protected] y te ayudaremos a completar la configuración.
Eliminar la subcarpeta
Para dejar de usar la subcarpeta personalizada y volver a tu URL predeterminada de Ferndesk:
Elimina el dominio en Ferndesk
En Ferndesk, ve a Centro de ayuda → Personalizar → Dominio personalizado y haz clic en Eliminar dominio.
Elimina las rutas de Vercel
Elimina o comenta las entradas relacionadas con Ferndesk de headers y routes en tu archivo vercel.json y, a continuación, vuelve a implementar el proyecto.