Serveur Nginx

Héberger votre base de connaissances Document360 dans un sous-dossier sur Nginx, comme example.com/docs, nécessite de configurer un proxy et de réécrire les règles sur votre serveur. Cet article traite de l’activation des blocs de localisation requis, du routage des chemins de l’interface utilisateur et de l’API, de la génération de sitemaps et de la gestion de la redirection des URL pour éviter le doublon de contenu dans les moteurs de recherche.

Pour en savoir plus sur Nginx lui-même, consultez la documentation Nginx.

Avant que tu commences

• L’hébergement de sous-dossiers ne fonctionne que lorsque le chemin des sous-dossiers (par exemple, /docs ou /help) et le chemin de l’API Site (par exemple, /api ou /docs-api) sont définis dans Document360. Après avoir défini ces valeurs, configurez les blocs correspondants location dans Nginx pour proxy à la fois le trafic UI et API.
• Remplacez le domaine d’exemple tout au long de cet article par votre propre domaine fourni par Document360 ou un domaine personnalisé. Par exemple, example.document360.io représente votre domaine, et example.document360.io/docs le chemin de votre sous-dossier.

Comment configurer un chemin de sous-dossier dans Nginx

1. Ajoutez le bloc de localisation suivant à votre fichier de configuration 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. Redémarrez le serveur web de Nginx. Sur Linux, utilisez :

sudo systemctl restart nginx

Comment utiliser un chemin de sous-dossier personnalisé

Vous pouvez héberger votre base de connaissances sur un chemin autre que /docs, comme /help ou /support. Lors de la configuration d’un chemin personnalisé, ajoutez également les langues associées à chaque espace de travail, puis redémarrez le serveur.

L’exemple ci-dessous correspond au domaine example.document360.iofourni par Document360, au domaine /v1/de travail, au chemin /help/des sous-dossiers et au code /he en hébreu — remplacez-les par vos propres valeurs.

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

Suppression du slug de l’espace de travail des liens internes

Pour retirer les slugs de l’espace de travail des liens internes au niveau proxy inverse Nginx, utilisez une sub_filter règle :

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

Cela réécrit les chemins spécifiques à chaque espace de travail avant qu’ils ne soient proposés aux lecteurs. Utilisez cette approche uniquement si la structure de votre site nécessite des URL indépendantes de l’espace de travail.

Pourquoi proxy_set_header Accept-Encoding "" est nécessaire

Lorsqu’il héberge dans un sous-dossier personnalisé, Nginx utilise sub_filter couramment la réécriture d’URLs internes telles que /docs vers /help. Par défaut, le serveur en amont (Document360) peut renvoyer du HTML compressé en gzip, et Nginx ne peut pas appliquer sub_filter de règles aux réponses compressées. Cela fait que les liens internes restent non réécrits, que les widgets de la page d’accueil pointent sans cesse vers /docs, et que les cartes de catégorie ou les itinéraires de navigation se brisent.

Pour corriger cela, désactivez la compression depuis le serveur en amont :

proxy_set_header Accept-Encoding "";

Cela force Document360 à renvoyer du HTML non compressé, permet sub_filter l’exécution correcte des règles, et garantit que des chemins tels que /docs/en/ sont réécrits en /help/en/. Ce réglage est nécessaire chaque fois sub_filter qu’il est utilisé.

Comment configurer le chemin de l’API Site

Si vous hébergez votre base de connaissances dans un sous-dossier, vous devez également définir un chemin Site API et ajouter un bloc correspondant location dans Nginx, afin de garantir que les requêtes API sont correctement routées et d’éviter les boucles de redirection ou les appels API défaillants.

L’exemple ci-dessous utilise /api comme chemin de l’API Site :

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

Une fois que vous avez ajouté les deux blocs de localisation, redémarrez Nginx :

sudo systemctl restart nginx

À utiliser sub_filter_types *; uniquement lors de la réécriture de réponses HTML ou API qui pourraient retourner du contenu non HTML — évitez-le sauf si la réécriture de l’URL est réellement nécessaire.

Quand utiliser sub_filter dans le bloc de localisation API

Ajouter sub_filter des règles au bloc de localisation de l’API n’est pas toujours nécessaire. Utilisez-le uniquement lorsque votre chemin d’interface utilisateur est réécrit (par exemple, /docs → /help) ou lorsque les réponses API contiennent des chemins intégrés /docs à réécrire. Si votre projet continue d’être /docs utilisé comme chemin d’interface, n’ajoutez sub_filter pas de règles au bloc API.

Comment activer le menu déroulant des espaces de travail

Pour activer la navigation déroulante de l’espace de travail lors de l’hébergement dans un sous-répertoire personnalisé, ajoutez un bloc de code pour chaque espace de travail de votre projet.

L’exemple ci-dessous couvre deux espaces de travail, v1 et v2, avec le domaine example.document360.ioDocument360 , chemin /help/de sous-dossier , et langue /he hébraïque — remplacez-les par vos propres valeurs.

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

Redémarrer Nginx une fois configuré :

sudo systemctl restart nginx

La page d’accueil par défaut d’un site de base de connaissances apparaît dans le répertoire racine, par example.document360.ioexemple . Si votre projet possède une page d’accueil spécifique à l’espace de travail et au langage, le slug après le répertoire racine suit le format /<workspace_name>/<language_code>, par example.document360.io/v2/heexemple .

Comment configurer la génération de sitemap

Le préfixe de la carte de site reste le même sauf pour le code de la langue (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;
 }

Comment définir l’URL canonique

Lorsque vous hébergez votre base de connaissances dans un sous-dossier, configurez une URL canonique pour que les moteurs de recherche indexent votre domaine personnalisé et le chemin de votre sous-dossier au lieu du domaine par défaut *.document360.io . Cela évite l’indexation en double et améliore les performances SEO.

1. Naviguez dans > Knowledge base site > Custom domain personnalisé > Subfolder hosting.
2. Entrez par exemple l’URL https://example.com/helpcomplète du sous-dossier.
3. Cliquez sur Enregistrer.

Une fois configuré, les moteurs de recherche considèrent l’URL du sous-dossier comme la source principale pour l’indexation.

Que se passe-t-il ensuite

Une fois Nginx configuré, votre site de base de connaissances est en ligne dans votre sous-dossier personnalisé. L’URL existante de Document360 continue également de répondre aux requêtes – par exemple, les deux example.document360.io et example.com/docs pointera vers votre site de base de connaissances. Cela provoque des doublons de contenu dans les moteurs de recherche.

Pour éviter cela, activez le bouton Restreindre l’accès au sous-domaine dans () > Knowledge base site > Custom domain. Subfolder hosting Assurez-vous d’abord qu’un domaine canonique est configuré – une fois activé, votre sous-domaine Document360 redirige automatiquement vers votre domaine canonique.

Liens utiles

• NGINX Docs : Configuration de NGINX et NGINX Plus en tant que serveur Web
• DigitalOcean : Comprendre les algorithmes de sélection des serveurs et des blocs de localisation Nginx

Meilleures pratiques

• Ajoutez proxy_set_header Accept-Encoding ""; toujours à n’importe quel bloc de localisation avec sub_filter, sinon vos règles de réécriture ne s’appliqueront pas aux réponses compressées.
• Gardez le chemin de l’API du site identique entre le portail Document360 et votre configuration Nginx — un décalage provoque des appels API défaillants.
• Ajoutez sub_filter des règles au bloc de localisation de l’API uniquement lorsque votre chemin d’interface utilisateur est réécrit ou que les réponses de l’API contiennent des chemins intégrés /docs .
• Configurez une URL canonique avant d’activer Restreindre l’accès au sous-domaine, pour éviter les problèmes de redirection lors de la configuration.

FAQ