Servidor Nginx

Alojar tu base de conocimiento de Document360 en una subcarpeta en Nginx, como example.com/docs, requiere configurar el proxy y reescribir las reglas en tu servidor. Este artículo trata sobre cómo habilitar los bloques de ubicación necesarios, enrutar rutas de UI y API, generar sitemaps y gestionar la redirección de URLs para evitar contenido duplicado en los motores de búsqueda.

Para saber más sobre Nginx en sí, consulta la documentación de Nginx.

Antes de que empieces

• El alojamiento de subcarpetas solo funciona cuando tanto la ruta de subcarpeta (por ejemplo, /docs o /help) como la ruta de la API del sitio (por ejemplo, /api o /docs-api) están definidas en Document360. Tras establecer estos valores, configura los bloques correspondientes location en Nginx para proxy tanto el tráfico de la interfaz como el de la API.
• Sustituye el dominio de ejemplo a lo largo de este artículo por tu propio dominio proporcionado por Document360 o dominio personalizado. Por ejemplo, example.document360.io representa tu dominio y example.document360.io/docs representa la ruta de tu subcarpeta.

Cómo configurar una ruta de subcarpeta en Nginx

1. Añade el siguiente bloque de ubicación a 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. Reinicia el servidor web de Nginx. En Linux, utiliza:

sudo systemctl restart nginx

Cómo usar una ruta de subcarpeta personalizada

Puedes alojar tu base de conocimiento en un camino distinto a /docs, como /help o /support. Al configurar una ruta personalizada, añade también los idiomas asociados a cada espacio de trabajo y luego reinicia el servidor.

El ejemplo siguiente mapea el dominio example.document360.ioproporcionado por Document360, el espacio de trabajo /v1/, la ruta /help/de subcarpetas y el código /he en hebreo — sustituízalos por tus propios valores.

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

Para eliminar slugs de espacio de trabajo de enlaces internos a nivel de proxy inverso Nginx, usa una sub_filter regla:

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

Esto reescribe los caminos específicos del espacio de trabajo antes de que se sirvan a los lectores. 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 en una subcarpeta personalizada, Nginx suele usarse sub_filter para reescribir URLs internas como /docs en /help. Por defecto, el servidor upstream (Document360) puede devolver HTML comprimido en gzip, y Nginx no puede aplicar sub_filter reglas a respuestas comprimidas. Esto provoca que los enlaces internos queden sin reescribir, que los widgets de la página principal sigan apuntando a /docs, y que las tarjetas de categoría o rutas de navegación se rompan.

Para solucionar esto, desactiva la compresión desde el servidor upstream:

proxy_set_header Accept-Encoding "";

Esto obliga a Document360 a devolver HTML sin comprimir, permite sub_filter que las reglas se ejecuten correctamente y asegura que rutas como /docs/en/ se reescriban a /help/en/. Esta configuración es necesaria siempre que sub_filter se utiliza.

Cómo configurar la ruta de la API del sitio

Si alojas tu base de conocimiento en una subcarpeta, también debes definir una ruta de API del sitio y añadir un bloque correspondiente location en Nginx, para asegurar que las peticiones API enruten correctamente y evitar bucles de redirección o llamadas fallidas.

El ejemplo siguiente se utiliza /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;
}

Una vez que hayas añadido ambos bloques de ubicación, reinicia Nginx:

sudo systemctl restart nginx

Úsalo sub_filter_types *; solo al reescribir respuestas HTML o API que puedan devolver contenido no HTML — evítalo a menos que realmente sea necesario reescribir URLs.

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

No siempre es necesario añadir sub_filter reglas al bloque de ubicación de la API. Úsalo solo cuando tu ruta de interfaz se reescriba (por ejemplo, /docs → /help) o cuando las respuestas de la API contengan rutas incrustadas /docs que necesiten reescribir. Si tu proyecto sigue usándose /docs como ruta de la interfaz, no añadas sub_filter reglas al bloque de la API.

Cómo habilitar el desplegable de espacios de trabajo

Para habilitar la navegación desplegable del espacio de trabajo al alojar en un subdirectorio personalizado, añade un bloque de código para cada espacio de trabajo de tu proyecto.

El ejemplo siguiente cubre dos espacios de trabajo, v1 y v2, con dominio example.document360.ioDocument360 , ruta /help/de subcarpeta y lengua /he hebrea — retitúyelos por tus propios valores.

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;
}

Reiniciar Nginx una vez configurado:

sudo systemctl restart nginx

La página principal predeterminada de un sitio de base de conocimiento aparece en el directorio raíz, por example.document360.ioejemplo. Si tu proyecto tiene una página principal específica de espacio de trabajo y lenguaje, el slug después del directorio raíz sigue el formato /<workspace_name>/<language_code>, por example.document360.io/v2/heejemplo .

Cómo configurar la generación de mapas del sitio

El prefijo del sitemap se mantiene igual excepto por el código del idioma (en, fr, de, etc.).

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;
 }

Cómo establecer la URL canónica

Al alojar tu base de conocimiento en una subcarpeta, configura una URL canónica para que los motores de búsqueda indexen tu dominio personalizado y la ruta de la subcarpeta en lugar del dominio por defecto *.document360.io . Esto evita la indexación duplicada y mejora el rendimiento SEO.

1. Navega a Configuración > Sitio de la base de conocimientos Dominio personalizado personalizado > Alojamiento de subcarpetas.
2. Introduce la URL completa de la subcarpeta, por https://example.com/helpejemplo .
3. Haz clic en Guardar.

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

¿Qué pasa después?

Una vez configurado Nginx, tu base de conocimiento estará activo en tu subcarpeta personalizada. La URL existente de Document360 sigue atendiendo solicitudes también, por ejemplo, ambas example.document360.io y example.com/docs apuntará a tu sitio de base de conocimiento. Esto provoca contenido duplicado en los motores de búsqueda.

Para evitar esto, activa el interruptor Restringir acceso a subdominio en Configuración () > Sitio de la base de conocimientos Alojamiento de subcarpetas Dominio personalizado. Asegúrate primero de configurar un dominio canónico; una vez habilitado, tu subdominio Document360 redirige automáticamente a tu dominio canónico.

Enlaces útiles

• 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

Mejores prácticas

• Añade proxy_set_header Accept-Encoding ""; siempre a cualquier bloque de ubicación usando sub_filter, o tus reglas de reescritura no se aplicarán a respuestas comprimidas.
• Mantén la ruta de la API del sitio idéntica entre el portal Document360 y tu configuración de Nginx: una descoordinación provoca llamadas a la API fallidas.
• Añade sub_filter reglas al bloque de ubicación de la API solo cuando tu ruta de la interfaz se reescribe o las respuestas de la API contienen rutas incrustadas /docs .
• Configura una URL canónica antes de habilitar Restringir el acceso a subdominios, para evitar problemas de redirección durante la configuración.

Preguntas frecuentes