Servidor Nginx - Alojamiento de subcarpetas

Para alojar tu base de conocimiento de Document360 en una subcarpeta (como example.com/docs) usando el servidor Nginx, se requieren configuraciones específicas. Este artículo te guía para habilitar los módulos necesarios, configurar proxy y reglas de reescritura, y gestionar rutas para artículos, APIs y sitemaps. También explica cómo gestionar correctamente la redirección de URL para evitar problemas de contenido duplicado en los motores de búsqueda.

Para saber más sobre Nginx, visita la documentación de Nginx.

Configuración de una subcarpeta/subdirectorio

Ejemplo:

NOTA

Sustituye el dominio de ejemplo por tu propio dominio/dominio personalizado proporcionado por Document360.

• Ejemplo de dominio representado usando example.document360.io

• Ruta de subcarpeta/subdirectorio (/docs) representada como example.document360.io/docs

1. Añade los siguientes bloques de ubicación en tu archivo de configuración Nginx (/etc/nginx/default).

location /docs {
    proxy_pass https://example.document360.io/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
}

2. Reiniciar el servidor web de Nginx

3. Por ejemplo, si usas Nginx en Linux, entonces usa el comando
   $ sudo systemctl restart nginx

NOTA

Si estás en KB Site 2.0 y deseas alojar tu base de conocimientos como una subcarpeta, debes definir ambas:

• La ruta de subcarpetas (por ejemplo, /docs, /help)

• La ruta de la API del sitio (por ejemplo, /api, /docs-api)

Tras establecer estos valores, también debes configurar bloques correspondientes location en tu servidor web para que proxy tanto el tráfico de la interfaz como de la API. Puedes encontrar el ejemplo de configuración de la API en la sección siguiente.

Uso de una ruta personalizada de subcarpeta/subdirectorio

• Puedes configurar tu base de conocimientos en rutas de subdirectorio distintas a /docs.
  Por ejemplo, /help, /support, etc.

• Al configurar otras rutas, añade los lenguajes asociados a cada espacio de trabajo.

• Añade unas cuantas líneas más para conseguirlo. Reinicia el servidor cuando termines.

Ejemplo:

NOTA

Sustituye el dominio proporcionado por Document360 y el dominio del subdirectorio por tus propios dominios. Además, sustituye el nombre del espacio de trabajo, la ruta de la subcarpeta y el lenguaje por tus requisitos.

• Document360 proporcionó el dominio representado como example.document360.io

• Nombre del espacio de trabajo representado como /v1/

• Ruta de subcarpeta representada como /help/

• Idioma representado como /he hebreo.

location /help {
    proxy_pass https://example.document360.io/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;

    sub_filter "v1/docs/" "v1/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}

Eliminando el slug del espacio de trabajo de los enlaces internos

Si es necesario, puedes eliminar slugs de espacio de trabajo de enlaces internos a nivel de proxy inverso NGINX usando sub_filter reglas.

Ejemplo:

sub_filter "/Version_slug/docs/" "/help/";

Utiliza este enfoque solo si la estructura de tu sitio requiere URLs independientes del espacio de trabajo.

Por qué proxy_set_header Accept-Encoding "" es necesario

Al alojar una base de conocimiento de Document360 en una subcarpeta personalizada (por ejemplo, /help), NGINX suele usarse sub_filter para reescribir URLs internas como /docs a /help.

Por defecto, el servidor ascendente (Document360) puede devolver HTML comprimido en gzip. NGINX no puede aplicar sub_filter reglas sobre respuestas comprimidas.

Esto conduce a los siguientes problemas:

• Los enlaces internos no se reescriben

• Los widgets de la página principal siguen apuntando a /docs

• Tarjetas de categoría y rutas de navegación

Para asegurar que la reescritura de URLs funcione correctamente, debes desactivar la compresión desde el servidor upstream añadiendo la siguiente directiva:

proxy_set_header Accept-Encoding "";

Este escenario:

Esta configuración es necesaria siempre que sub_filter se utiliza.

Configuración obligatoria de rutas API para KB Site 2.0

Si estás en KB Site 2.0, debes definir una ruta de API personalizada para el sitio y añadir un bloque correspondiente location en tu configuración NGINX.

Esto garantiza que las solicitudes de API se enruten correctamente a Document360 y evita problemas como bucles de redirección o llamadas a API fallidas.

Aquí tienes un ejemplo usando /api como ruta de la API del sitio:

location /api {
    proxy_pass https://example.document360.io/api;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name on;
    proxy_set_header Accept-Encoding "";

    sub_filter_types *;
    sub_filter "v1/docs/" "v1/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}

NOTA

Reemplazar /api y /docs-api con los valores exactos configurados bajo la ruta de la API del sitio en el portal Document360.

Una vez que hayas añadido ambos location bloques, reinicia el servidor web de Nginx. Por ejemplo, si usas Nginx en Linux, entonces usa el comando $ sudo systemctl restart nginx.

Úsalo sub_filter_types *; solo al reescribir respuestas HTML o API que puedan devolver contenido no HTML. Evita usarlo a menos que sea necesario reescribir URLs.

Cuándo usarlo sub_filter en el bloque de ubicación de la API

No siempre es necesario añadir sub_filter reglas en el bloque de ubicación de la API.

Úsalo sub_filter en el bloque de ubicación de la API solo cuando:

• Tu ruta de interfaz se reescribe (por ejemplo, /docs → /help)

• Las respuestas API contienen rutas incrustadas /docs que deben ser reescritas

Si tu proyecto sigue usándose /docs como ruta de la interfaz, no añadas sub_filter reglas al bloque de la API.

IMPORTANTE
Si tu dominio ya se usa /api para otra aplicación, debes actualizar la ruta de la API del sitio en el portal Document360 a un valor diferente (por ejemplo, /docs-api) y usar la misma ruta en tu configuración NGINX.

La ruta de la API configurada en el portal y el bloque de ubicación NGINX deben coincidir exactamente.

Para habilitar el desplegable de espacios de trabajo

Si quieres activar la navegación desplegable de espacios de trabajo para tu proyecto cuando lo alojes en un subdirectorio y ruta personalizados, añade el siguiente código para cada uno de los espacios de trabajo disponibles en tu proyecto.

Ejemplo:

Supongamos que tu proyecto tiene dos espacios de trabajo, v1 y v2. En ese caso, debes añadir dos bloques de código, uno para cada espacio de trabajo.

NOTA

Sustituye el dominio proporcionado por Document360 y el dominio del subdirectorio por tus propios dominios. Además, sustituye el nombre del espacio de trabajo, la ruta de la subcarpeta y el lenguaje por tus requisitos.

• Document360 proporcionó el dominio representado como example.document360.io

• Nombre del espacio de trabajo representado como /v1/,/v2/

• Ruta de subcarpeta representada como /help/

• Idioma representado como /he hebreo.

location /v2/help {
    proxy_pass https://example.document360.io/v2/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;

    sub_filter "v2/docs/" "v2/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}
-----------------------------------------------------
location /v1/help {
    proxy_pass https://example.document360.io/v1/docs;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;

    sub_filter "v1/docs/" "v1/help/";
    sub_filter "docs/he/" "/help/he";
    sub_filter "/docs/" "/help/";
    sub_filter_once off;
}
-----------------------------------------------------
location = /v2/docs {
    return 301 /v2/help;
}
-----------------------------------------------------
location = /v1/docs {
    return 301 /v1/help;
}

NOTA

Si quieres que tus lectores naveguen entre los diferentes espacios de trabajo públicos de tu proyecto desde el desplegable (con clic del ratón), añade el bloque de ubicación para todos los espacios de trabajo disponibles.

1. Reiniciar el servidor web de Nginx

2. Por ejemplo, si usas Nginx en Linux, entonces usa el comando
   $ sudo systemctl restart nginx

Enlaces útiles

Aquí tienes algunos enlaces externos que pueden ayudarte a entender en detalle los bloques de ubicación del servidor Nginx:

• NGINX Docs: Configuración de NGINX y NGINX Plus como servidor web

• DigitalOcean: Comprendiendo los algoritmos de selección de servidores y bloques de ubicación Nginx

Generación de mapas de sitio

Ejemplo:

NOTA

Sustituye el dominio de ejemplo por tu propio dominio/dominio personalizado proporcionado por Document360.

• Ejemplo de dominio representado usando example.document360.io

• El prefijo del sitemap permanece igual excepto por el código del idioma (en, fr, de, etc.)  example.document360.io/sitemap.xml.en

location /sitemap.xml.en {
    proxy_pass https://example.document360.io/sitemap.xml.en;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
    proxy_set_header Accept-Encoding "";

    sub_filter_types text/xml;
    sub_filter "https://www.example.document360.io/docs/" "https://www.example.document360.io/help/";
    sub_filter_once off;
 }

Página principal alojada en una subcarpeta

Para alojar la página principal de tu proyecto en una ruta personalizada de subdirectorio/subcarpeta, añade el siguiente código para cada uno de los espacios de trabajo de la página principal disponibles en tu proyecto.

Ejemplo:

Supongamos que tu proyecto tiene dos espacios de trabajo, V1 y V2. En ese caso, debes añadir dos bloques de código, uno para cada espacio de trabajo.

NOTA

Sustituye el dominio proporcionado por Document360 y el dominio del subdirectorio por tus propios dominios. Además, sustituye el nombre del espacio de trabajo, la ruta de la subcarpeta y el lenguaje por tus requisitos.

• Document360 proporcionó el dominio representado como example.document360.io

• Nombre del espacio de trabajo representado como /v1/,/v2/

location =/v1 {
    proxy_pass https://example.document360.io/;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
}

location =/v2 {
    proxy_pass https://example.document360.io/;
    proxy_set_header Host example.document360.io;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header "requested-by" "proxy";
    proxy_ssl_server_name   on;
}

location /v1/en {
  return 301 /v1;
}

location /v2/en {
  return 301 /v2;
}

CONSEJO PROFESIONAL

El signo de igual puede usarse si la ubicación necesita coincidir exactamente con el URI de la solicitud. Cuando se empareja este modificador, la búsqueda se detiene justo aquí. Para más información, haz clic aquí.

Ejemplo: location =/help {

2. Reiniciar el servidor web de Nginx

3. Por ejemplo, si usas Nginx en Linux, entonces usa el comando
   $ sudo systemctl restart nginx

Página principal del sitio de la base de conocimiento

¿Qué ocurre después?

Una vez que hayas configurado correctamente el servidor web, tu sitio de la base de conocimiento estará activo en tu subcarpeta/subdirectorio personalizado. Sin embargo, la URL existente de tu proyecto servirá las solicitudes.

Por ejemplo, example.document360.io y example.com/docs (si /docs es la ruta de tu carpeta) apuntará al sitio de la base de conocimientos.

Esto puede provocar duplicados de contenido en los motores de búsqueda (Google, Bing, etc.). Para evitar esto, será necesario redirigir desde el subdominio del proyecto Document360 a tu dominio personalizado.

NOTA

Para habilitar la redirección desde example.document360.io a example.com/docs, por favor contáctanos en support@document360.com.

URL canónica para el alojamiento de subcarpetas

Al alojar tu base de conocimiento en una subcarpeta, debes configurar una URL canónica para asegurar que los motores de búsqueda indexen tu dominio y ruta de subcarpeta personalizados, no el dominio por defecto *.document360.io .

Esto evita la indexación duplicada y mejora el rendimiento SEO.

Cómo establecer la URL canónica

1. Ve a Configuración > sitio de la Knowledge Base > Dominio personalizado > alojamiento de subcarpetas.

2. Introduce la URL completa de la subcarpeta (por ejemplo, https://example.com/help).

3. Haz clic en Guardar.

Una vez configurada, los motores de búsqueda tratarán la URL de la subcarpeta como la fuente principal para la indexación.

Solución de problemas

Esta sección ofrece orientación paso a paso para solucionar los problemas comunes que puedas encontrar durante el proceso de configuración de NGINX. Desde problemas de alojamiento en subcarpetas hasta pruebas de configuración fallidas, cada solución está diseñada para ayudarte a identificar y resolver rápidamente posibles obstáculos, asegurando una configuración fluida y eficiente del servidor.

Resolución de directivas de localización inválidas en NGINX

Error: nginx: [emergencia] la directiva de "ubicación" no está permitida aquí

Este error ocurre cuando una directiva de ubicación se coloca fuera de su contexto válido, como fuera del bloque del servidor. En NGINX, los bloques de ubicación deben definirse dentro de un bloque de servidor.

Pasos para resolver:

1. Asegúrate de que el bloque de ubicación esté colocado correctamente dentro del bloque del servidor. Consulte el siguiente bloque de ejemplo:

   server {
       listen 80;
       server_name example.com;
       location /docs {
           proxy_pass https://example.document360.io/docs;
           proxy_set_header Host example.document360.io;
       }
   }

2. Para evitar este problema, no coloques las directivas de ubicación en el contexto global http ni fuera de él server .

3. Si el problema persiste después de seguir estos pasos, póngase en contacto con el equipo de soporte de Document360 para obtener más ayuda: Póngase en contacto con el equipo de soporte de Document360

Problema con la disponibilidad del paquete Certbot

Error: No hay paquete disponible en Certbot

Este problema suele ocurrir cuando el repositorio EPEL (requerido para la instalación de Certbot en distribuciones basadas en RHEL) no está habilitado, o el gestor de paquetes no puede localizar Certbot en distribuciones basadas en RHEL.

Pasos para resolver:

1. Habilita el repositorio EPEL usando el código que aparece a continuación:

   sudo yum install epel-release

2. Actualiza la caché del repositorio y prueba a instalar Certbot de nuevo usando el código que aparece a continuación:

   sudo yum install certbot

3. Asegúrate de que tu instancia tenga acceso a internet para obtener los archivos del repositorio. Si el problema persiste, verifica los archivos de configuración del repositorio en /etc/yum.repos.d/.

4. Si el problema persiste después de seguir estos pasos, póngase en contacto con el equipo de soporte de Document360 para obtener más ayuda: Póngase en contacto con el equipo de soporte de Document360

Problema con la prueba de configuración NGINX

Error: Prueba de configuración NGINX fallida

Este problema ocurre cuando hay un error de sintaxis en el archivo de configuración NGINX.

Pasos para resolvere:

1. Ejecuta el comando de prueba de configuración:

   sudo nginx -t

2. Revisa el mensaje de error y el número de línea, como se muestra en el ejemplo que se muestra a continuación:

   nginx: [emerg] invalid parameter "proxy_pas" in /etc/nginx/sites-enabled/example:22
   nginx: configuration file /etc/nginx/nginx.conf test failed

3. Abre el archivo /etc/nginx/sites-enabled/example especificado y soluciona el problema de configuración. Por ejemplo:

   # Incorrect
   proxy_pas https://example.com;
   
   # Correct
   proxy_pass https://example.com;

4. Una vez solucionado el problema de configuración, reinicia NGINX:

   sudo systemctl restart nginx

5. Si el problema persiste después de seguir estos pasos, póngase en contacto con el equipo de soporte de Document360 para obtener más ayuda: Póngase en contacto con el equipo de soporte de Document360

Emisión de certificado SSL

Error: El certificado SSL no funciona

Este problema puede deberse a una configuración incorrecta de NGINX SSL o cuando hay un problema con el certificado instalado. Los detalles del certificado, como el dominio y la fecha de caducidad, pueden no coincidir con los detalles de configuración.

Pasos para resolver:

1. Verifica los archivos de certificados usando el código que aparece a continuación:

   openssl x509 -in /etc/letsencrypt/live/yourdomain.com/fullchain.pem -text -noout

2. Asegúrate de que tu configuración coincida con los detalles del certificado, como el dominio y la fecha de caducidad.

3. Asegúrate de que la configuración SSL de NGINX sea correcta. Consulta el código de abajo como ejemplo:

   server {
       listen 443 ssl;
       server_name yourdomain.com;
       
       ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;
   }

4. Una vez hecho, reinicia NGINX usando el código que aparece a continuación:

   sudo systemctl restart nginx

5. Si el problema persiste después de seguir estos pasos, póngase en contacto con el equipo de soporte de Document360 para obtener más ayuda: Póngase en contacto con el equipo de soporte de Document360

proxy_set_header Accept-Encoding "";