Nginx-server

Het hosten van je Document360 kennisbank in een submap op Nginx, zoals example.com/docs, vereist het configureren van proxy- en herschrijfregels op je server. Dit artikel behandelt het inschakelen van de benodigde locatieblokken, het routeren van UI- en API-paden, het genereren van sitemaps en het afhandelen van URL-omleiding om dubbele inhoud in zoekmachines te voorkomen.

Voor meer informatie over Nginx zelf, zie de Nginx-documentatie.

Voordat je begint

• Subfolderhosting werkt alleen wanneer zowel het Submap-pad (bijvoorbeeld /docs of /help) als het Site API-pad (bijvoorbeeld /api of /docs-api) in Document360 zijn gedefinieerd. Na het instellen van deze waarden configureer je de bijbehorende location blokken in Nginx om zowel UI- als API-verkeer te proxyen.
• Vervang het voorbeelddomein in dit artikel door je eigen door Document360 geleverde domein of aangepaste domein. Bijvoorbeeld, example.document360.io vertegenwoordigt je domein, en example.document360.io/docs vertegenwoordigt je submappad.

Hoe configureer je een submappad in Nginx

1. Voeg het volgende locatieblok toe aan je Nginx-configuratiebestand (/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. Herstart de Nginx-webserver. Op Linux gebruik je:

sudo systemctl restart nginx

Hoe gebruik je een aangepast submappad

Je kunt je kennisbasis hosten op een ander pad dan /docs, zoals /help of /support. Voeg bij het instellen van een aangepast pad ook de talen toe die aan elke werkruimte zijn gekoppeld en start vervolgens de server opnieuw.

Het onderstaande voorbeeld brengt het door Document360 geleverde domein, example.document360.iowerkruimte /v1/, submappad /help/en Hebreeuwse taal code /he in kaart — vervang deze door je eigen waarden.

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

Het verwijderen van de workspace slug uit interne links

Om workspace-slugs van interne links op het Nginx reverse proxy-niveau te verwijderen, gebruik een sub_filter regel:

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

Dit herschrijft werkruimte-specifieke paden voordat ze aan lezers worden gepresenteerd. Gebruik deze aanpak alleen als je sitestructuur workspace-agnostische URL's vereist.

Waarom proxy_set_header Accept-Encoding "" is vereist

Bij hosting in een aangepaste submap gebruikt sub_filter Nginx vaak interne URL's /docs zoals naar /help. Standaard kan de upstream-server (Document360) gzip-gecomprimeerde HTML teruggeven, en Nginx kan geen regels toepassen sub_filter op gecomprimeerde antwoorden. Dit zorgt ervoor dat interne links niet worden herschreven, widgets op de homepage steeds naar verwijzen en /docscategoriekaarten of navigatieroutes kapot gaan.

Om dit op te lossen, schakel compressie uit van de upstream-server:

proxy_set_header Accept-Encoding "";

Dit dwingt Document360 om ongecomprimeerde HTML terug te geven, laat sub_filter regels correct uitvoeren en zorgt ervoor dat paden zoals die /docs/en/ worden herschreven naar /help/en/. Deze instelling is altijd nodig wanneer sub_filter deze wordt gebruikt.

Hoe het Site API-pad te configureren

Als je je kennisbank in een submap host, moet je ook een Site API-pad definiëren en een bijbehorend location blok toevoegen in Nginx, om te zorgen dat API-verzoeken correct worden gerouteerd en om redirect-lussen of kapotte API-aanroepen te voorkomen.

Het onderstaande voorbeeld gebruikt /api als het Site API-pad:

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

Zodra je beide locatieblokken hebt toegevoegd, start je Nginx opnieuw op:

sudo systemctl restart nginx

Gebruik sub_filter_types *; alleen bij het herschrijven van HTML- of API-antwoorden die niet-HTML-inhoud kunnen teruggeven — vermijd dit tenzij het herschrijven van URL's daadwerkelijk nodig is.

Wanneer te gebruiken sub_filter in het API-locatieblok

Het toevoegen sub_filter van regels aan het API-locatieblok is niet altijd noodzakelijk. Gebruik het alleen wanneer je UI-pad wordt herschreven (bijvoorbeeld /docs → /help) of wanneer API-antwoorden embedded /docs paden bevatten die herschreven moeten worden. Als je project blijft gebruiken /docs als UI-pad, voeg sub_filter dan geen regels toe aan het API-blok.

Hoe je het keuzemenu werkruimtes inschakelt

Om navigatie in de keuzelijst van de werkruimte in te schakelen wanneer je hostt in een aangepaste subdirectory, voeg je een codeblok toe voor elke werkruimte in je project.

Het onderstaande voorbeeld behandelt twee werkruimtes, v1 en v2, met Document360-domein example.document360.io, submappad /help/, en Hebreeuwse taal /he — vervang deze door je eigen waarden.

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

Begin Nginx opnieuw zodra je het geconfigureerd hebt:

sudo systemctl restart nginx

De standaard startpagina van een kennisbanksite verschijnt bijvoorbeeld in de rootdirectory.example.document360.io Als je project een werkruimte- en taalspecifieke startpagina heeft, volgt de slug na de rootmap bijvoorbeeld het formaat./<workspace_name>/<language_code>example.document360.io/v2/he

Hoe je sitemapgeneratie instelt

Het sitemap-prefix blijft hetzelfde, behalve voor de taalcode (en, fr, de, enzovoort).

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

Hoe de canonieke URL in te stellen

Wanneer je je kennisbank in een submap host, configureer dan een canonieke URL zodat zoekmachines je aangepaste domein en submappad indexeren in plaats van het standaarddomein *.document360.io . Dit voorkomt dubbele indexering en verbetert de SEO-prestaties.

1. Navigeer naar > Knowledge base site > Custom domain > Subfolder hosting.
2. Voer bijvoorbeeld de volledige submap URL in.https://example.com/help
3. Klik op Opslaan.

Eenmaal geconfigureerd, beschouwen zoekmachines de submap URL als de primaire bron voor indexering.

Wat gebeurt er daarna

Zodra Nginx is geconfigureerd, staat je knowledge base-site live in je eigen submap. De bestaande Document360-URL blijft ook verzoeken bedienen – bijvoorbeeld, zowel example.document360.io als example.com/docs verwijzen naar je kennisbanksite. Dit veroorzaakt dubbele inhoud in zoekmachines.

Om dit te voorkomen, schakel de schakelaar Subdomeintoegang Beperken in onder () > Knowledge base site > Custom domain > Subfolder hosting. Zorg ervoor dat een canoniek domein eerst is geconfigureerd - zodra het is ingeschakeld, wordt je Document360-subdomein automatisch doorgestuurd naar je canonieke domein.

Handige links

• NGINX Docs: NGINX en NGINX Plus configureren als webserver
• DigitalOcean: Inzicht in Nginx-server- en locatieblokselectie-algoritmen

Best practices

• Voeg altijd toe proxy_set_header Accept-Encoding ""; aan elk locatieblok met sub_filter, anders zijn je herschrijfregels niet van toepassing op gecomprimeerde reacties.
• Houd het Site API-pad identiek tussen het Document360-portaal en je Nginx-configuratie — een mismatch veroorzaakt kapotte API-aanroepen.
• sub_filter Voeg regels toe aan het API-locatieblok alleen wanneer je UI-pad wordt herschreven of wanneer API-antwoorden embedded /docs paden bevatten.
• Configureer een canonieke URL voordat je toegang tot subdomein beperken inschakelt, om omleidingsproblemen tijdens de installatie te voorkomen.

FAQ