Nginx-server - Submap hosting

Om je Document360-kennisbank in een submap (zoals example.com/docs) te hosten met behulp van de Nginx-server, zijn specifieke configuraties vereist. Dit artikel leidt je bij het inschakelen van de benodigde modules, het configureren van proxy- en herschrijfregels, en het beheren van paden voor artikelen, API's en sitemaps. Het legt ook uit hoe je URL-omleiding correct kunt aanpakken om problemen met dubbele inhoud in zoekmachines te voorkomen.

Voor meer informatie over Nginx, bezoek de Nginx-documentatie.

Een submap/submap instellen

Voorbeeld:

OPMERKING

Vervang het voorbeelddomein door je eigen document360-domein/aangepaste domein.

• Voorbeelddomein weergegeven met behulp van example.document360.io

• Submap/subdirectorypad (/docs) weergegeven als example.document360.io/docs

1. Voeg de volgende locatieblokken 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

3. Als je bijvoorbeeld Nginx op Linux gebruikt, gebruik dan het commando
   $ sudo systemctl restart nginx

OPMERKING

Als je op KB Site 2.0 zit en je kennisbank als submap wilt hosten, moet je beide definiëren:

• Het Submap-pad (bijv. /docs, , /help)

• Het Site API-pad (bijv. /api, , /docs-api)

Na het instellen van deze waarden moet je ook de bijbehorende location blokken in je webserver configureren om zowel UI- als API-verkeer te proxyën. Je kunt het voorbeeld van API-configuratie vinden in de onderstaande sectie.

Een aangepast submap/subdirectorypad gebruiken

• Je kunt je kennisbasis opzetten op subdirectorypaden anders dan /docs.
  Bijvoorbeeld, /help, /support, enzovoort.

• Voeg bij het instellen van andere paden de talen toe die aan elke werkruimte horen.

• Voeg een paar extra lijnen toe om dit te bereiken. Herstart de server zodra je klaar bent.

Voorbeeld:

OPMERKING

Vervang het door Document360 geleverde domein en het subdirectorydomein door je eigen domeinen. Vervang ook de naam van de werkruimte, het submappad en de taal door je eigen vereisten.

• Document360 leverde domein weergegeven als example.document360.io

• Werkruimtenaam weergegeven als /v1/

• Subfolderpad weergegeven als /help/

• Taal wordt weergegeven als /he voor Hebreeuws.

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

Indien nodig kun je workspace-slugs van interne links op NGINX reverse proxy-niveau verwijderen met sub_filter behulp van regels.

Voorbeeld:

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

Gebruik deze aanpak alleen als je sitestructuur workspace-agnostische URL's vereist.

Waarom proxy_set_header Accept-Encoding "" is vereist

Bij het hosten van een Document360-kennisbank in een aangepaste submap (bijvoorbeeld /help), gebruikt sub_filter NGINX vaak interne URL's /docs zoals ./help

Standaard kan de upstream-server (Document360) gzip-gecomprimeerde HTML teruggeven. NGINX kan geen regels toepassen sub_filter op gecomprimeerde reacties.

Dit leidt tot de volgende problemen:

• Interne links worden niet herschreven

• Startpaginawidgets blijven verwijzen naar /docs

• Categoriekaarten en navigatieroutes breken

Om te garanderen dat het herschrijven van URL's correct werkt, moet je compressie van de upstreamserver uitschakelen door de volgende richtlijn toe te voegen:

proxy_set_header Accept-Encoding "";

Deze instelling:

Deze instelling is altijd nodig wanneer sub_filter deze wordt gebruikt.

Verplichte API-padconfiguratie voor KB Site 2.0

Als je op KB Site 2.0 zit, moet je een Custom Site API-pad definiëren en een overeenkomstig location blok toevoegen in je NGINX-configuratie.

Dit zorgt ervoor dat API-verzoeken correct naar Document360 worden gerouteerd en voorkomt problemen zoals redirect-lussen of kapotte API-aanroepen.

Hier is een voorbeeld met /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;
}

OPMERKING

Vervang /api en /docs-api met de exacte waarden geconfigureerd onder het Site API-pad in het Document360-portaal.

Zodra je beide location blokken hebt toegevoegd, start je de Nginx-webserver opnieuw op. Als je bijvoorbeeld Nginx op Linux gebruikt, gebruik dan het commando $ sudo systemctl restart nginx.

Gebruik sub_filter_types *; alleen bij het herschrijven van HTML- of API-antwoorden die mogelijk niet-HTML-inhoud teruggeven. Vermijd het gebruik tenzij het herschrijven van de URL vereist is.

Wanneer te gebruiken sub_filter in het API-locatieblok

Het toevoegen van sub_filter regels in het API-locatieblok is niet altijd vereist.

Gebruik sub_filter alleen in het API-locatieblok wanneer:

• Je UI-pad wordt herschreven (bijvoorbeeld /docs → /help)

• API-antwoorden bevatten ingebedde /docs paden die herschreven moeten worden

Als je project blijft gebruiken /docs als UI-pad, voeg dan geen regels toe sub_filter aan het API-blok.

BELANGRIJK
Als je domein al gebruikt /api voor een andere applicatie, moet je het Site API-pad in het Document360-portaal bijwerken naar een andere waarde (bijvoorbeeld /docs-api) en hetzelfde pad gebruiken in je NGINX-configuratie.

Het API-pad dat in het portaal is geconfigureerd en het NGINX-locatieblok moeten exact overeenkomen.

Om het keuzemenu werkruimtes in te schakelen

Als je de navigatie in de werkruimte voor je project wilt inschakelen wanneer je het host in een aangepaste submap en pad, voeg dan de volgende code toe voor elk van de werkruimtes die in je project beschikbaar zijn.

Voorbeeld:

Laten we aannemen dat je project twee werkruimtes heeft, v1 en v2. In dat geval moet je twee codeblokken toevoegen, één voor elke Werkruimte.

OPMERKING

Vervang het door Document360 geleverde domein en het subdirectorydomein door je eigen domeinen. Vervang ook de naam van de werkruimte, het submappad en de taal door je eigen vereisten.

• Document360 leverde domein weergegeven als example.document360.io

• Werkruimtenaam weergegeven als /v1/,/v2/

• Subfolderpad weergegeven als /help/

• Taal wordt weergegeven als /he voor Hebreeuws.

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

OPMERKING

Als je wilt dat je lezers via het keuzemenu tussen de verschillende openbare werkruimtes van je project navigeren (met een muisklik), voeg dan het locatieblok toe voor alle beschikbare werkruimtes.

1. Herstart de Nginx-webserver

2. Als je bijvoorbeeld Nginx op Linux gebruikt, gebruik dan het commando
   $ sudo systemctl restart nginx

Handige links

Hier zijn een paar externe links die je kunnen helpen de Nginx-serverlocatieblokken in detail te begrijpen:

• NGINX Docs: NGINX en NGINX Plus configureren als webserver

• DigitalOcean: Inzicht in Nginx-server- en locatieblokselectie-algoritmen

Sitemap-generatie

Voorbeeld:

OPMERKING

Vervang het voorbeelddomein door je eigen document360-domein/aangepaste domein.

• Voorbeelddomein weergegeven met behulp van example.document360.io

• De sitemap-prefix blijft hetzelfde, behalve voor de taalcode (en, fr, de, enz.)  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;
 }

Startpagina gehost op een submap

Om de startpagina van je project te hosten op een aangepast subdirectory/subfolderpad, voeg je de volgende code toe voor elk van de werkruimtes op de startpagina die in je project beschikbaar zijn.

Voorbeeld:

Laten we aannemen dat je project twee werkruimtes heeft, V1 en V2. In dat geval moet je twee codeblokken toevoegen, één voor elke Werkruimte.

OPMERKING

Vervang het door Document360 geleverde domein en het subdirectorydomein door je eigen domeinen. Vervang ook de naam van de werkruimte, het submappad en de taal door je eigen vereisten.

• Document360 leverde domein weergegeven als example.document360.io

• Werkruimtenaam weergegeven als /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;
}

PRO TIP

Het gelijkheidsteken kan worden gebruikt als de locatie exact overeenkomt met de verzoek-URI. Wanneer deze modifier wordt gematcht, stopt de zoekopdracht hier. Voor meer informatie, klik hier.

Voorbeeld: location =/help {

2. Herstart de Nginx-webserver

3. Als je bijvoorbeeld Nginx op Linux gebruikt, gebruik dan het commando
   $ sudo systemctl restart nginx

Startpagina van de kennisbank

Wat gebeurt er nu?

Zodra je de webserver succesvol hebt geconfigureerd, staat je kennisbanksite live in je eigen submap/subdirectory. De bestaande URL van je project zal echter de verzoeken bedienen.

Bijvoorbeeld, example.document360.io en example.com/docs (als /docs dat je map pad is) zal het wijzen naar de knowledge base-site.

Dit kan leiden tot dubbele inhoud in zoekmachines (Google, Bing, enz.). Om dit te voorkomen, is een doorverwijzing van het Document360-projectsubdomein naar je aangepaste domein nodig.

OPMERKING

Om de doorverwijzing van example.document360.io naar example.com/docsmogelijk te maken, neem contact met ons op via support@document360.com.

Canonieke URL voor subfolderhosting

Wanneer je je kennisbank in een submap host, moet je een canonieke URL instellen om ervoor te zorgen dat zoekmachines je aangepaste domein en submappad indexeren, niet het standaarddomein *.document360.io .

Dit voorkomt dubbele indexering en verbetert de SEO-prestaties.

Hoe de canonieke URL in te stellen

1. Ga naar Instellingen > Knowledge Base-site > Aangepast domein > Subfolderhosting.

2. Voer de volledige submap-URL in (bijvoorbeeld https://example.com/help).

3. Klik op Opslaan.

Zodra deze is geconfigureerd, behandelen zoekmachines de submap URL als de primaire bron voor indexering.

Probleemoplossing

Deze sectie biedt stapsgewijze begeleiding om veelvoorkomende uitdagingen te onderzoeken waarmee u tijdens het NGINX-opzetproces kunt worden tegengekomen. Van problemen met het hosten van submappen tot mislukte configuratietests, elke oplossing is ontworpen om je snel potentiële obstakels te helpen identificeren en op te lossen, zodat een soepele en efficiënte serverconfiguratie wordt gegarandeerd.

Ongeldige locatie-richtlijn oplossen in NGINX

Fout: nginx: [emerg] "locatie" richtlijn is hier niet toegestaan

Deze fout doet zich voor wanneer een locatie-richtlijn buiten zijn geldige context wordt geplaatst, bijvoorbeeld buiten het serverblok. In NGINX moeten locatieblokken binnen een serverblok worden gedefinieerd.

Stappen om op te lossen:

1. Zorg ervoor dat het locatieblok correct binnen het serverblok wordt geplaatst. Zie het onderstaande voorbeeldblok:

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

2. Om dit probleem te vermijden, plaats locatie-instructies niet in de globale http context of buiten de server context.

3. Als het probleem zich blijft voordoen na het volgen van deze stappen, neem dan contact op met het Document360-ondersteuningsteam voor verdere hulp: Neem contact op met Document360 Support

Probleem met beschikbaarheid van Certbot-pakketten

Fout: Geen pakket-Certbot beschikbaar

Dit probleem doet zich vaak voor wanneer de EPEL-repository (vereist voor Certbot-installatie op RHEL-gebaseerde distributies) niet is ingeschakeld, of wanneer de pakketbeheerder Certbot niet kan vinden op RHEL-gebaseerde distributies.

Stappen om op te lossen:

1. Schakel de EPEL-repository in door gebruik te maken van de onderstaande code:

   sudo yum install epel-release

2. Werk de repositorycache bij en probeer Certbot opnieuw te installeren met behulp van onderstaande code:

   sudo yum install certbot

3. Zorg ervoor dat je instantie internettoegang heeft om de repositorybestanden op te halen. Als het probleem aanhoudt, verifieer dan de configuratiebestanden van de repository in /etc/yum.repos.d/.

4. Als het probleem zich blijft voordoen na het volgen van deze stappen, neem dan contact op met het Document360-ondersteuningsteam voor verdere hulp: Neem contact op met Document360 Support

NGINX-configuratietestprobleem

Fout: NGINX-configuratietest mislukt

Dit probleem doet zich voor wanneer er een syntaxisfout is in het NGINX-configuratiebestand.

Stappen om e op te lossen:

1. Voer het configuratie-testcommando uit:

   sudo nginx -t

2. Bekijk de foutmelding en het regelnummer, zoals in het onderstaande voorbeeld:

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

3. Open het opgegeven bestand /etc/nginx/sites-enabled/example en los het configuratieprobleem op. Bijvoorbeeld:

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

4. Zodra het configuratieprobleem is opgelost, start je NGINX opnieuw:

   sudo systemctl restart nginx

5. Als het probleem zich blijft voordoen na het volgen van deze stappen, neem dan contact op met het Document360-ondersteuningsteam voor verdere hulp: Neem contact op met Document360 Support

SSL-certificaatuitgifte

Fout: SSL-certificaat werkt niet

Dit probleem kan ontstaan door een verkeerde NGINX SSL-configuratie of wanneer er een probleem is met het geïnstalleerde certificaat. De certificaatgegevens, zoals domein en vervaldatum, komen mogelijk niet overeen met de configuratiedetails.

Stappen om op te lossen:

1. Controleer de certificaatbestanden met behulp van de onderstaande code:

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

2. Zorg ervoor dat je configuratie overeenkomt met de certificaatgegevens, zoals het domein en de vervaldatum.

3. Zorg ervoor dat de NGINX SSL-configuratie correct is. Zie de onderstaande code als voorbeeld:

   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. Als je klaar bent, start je NGINX opnieuw met de onderstaande code:

   sudo systemctl restart nginx

5. Als het probleem zich blijft voordoen na het volgen van deze stappen, neem dan contact op met het Document360-ondersteuningsteam voor verdere hulp: Neem contact op met Document360 Support

proxy_set_header Accept-Encoding "";