Servidor Nginx - Hospedagem de subpastas

Para hospedar sua base de conhecimento Document360 em uma subpasta (como example.com/docs) usando o servidor Nginx, são necessárias configurações específicas. Este artigo guia você na habilitação dos módulos necessários, na configuração de proxy e regras de reescrita, e no gerenciamento de caminhos para artigos, APIs e sitemaps. Também explica como lidar corretamente com o redirecionamento de URL para evitar problemas de conteúdo duplicado nos mecanismos de busca.

Para saber mais sobre a Nginx, visite a documentação da Nginx.

Configuração de uma subpasta/subdiretório

Exemplo:

NOTA

Substitua o domínio de exemplo pelo seu próprio domínio/domínio personalizado fornecido no document360.

• Exemplo de domínio representado usando example.document360.io

• Caminho de subpasta/subdiretório (/docs) representado como example.document360.io/docs

1. Adicione os seguintes blocos de localização no seu arquivo de configuração 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. Reinicie o servidor web Nginx

3. Por exemplo, se você está usando Nginx no Linux, então use o comando
   $ sudo systemctl restart nginx

NOTA

Se você está no KB Site 2.0 e deseja hospedar sua base de conhecimento como uma subpasta, deve definir ambas:

• O caminho da subpasta (por exemplo, /docs, /help)

• O caminho da API do Site (por exemplo, /api, /docs-api)

Após definir esses valores, você também deve configurar blocos correspondentes location no seu servidor web para proxy tanto o tráfego da interface quanto o da API. Você pode encontrar o exemplo de configuração da API na seção abaixo.

Usando um caminho personalizado de subpasta/subdiretório

• Você pode configurar sua base de conhecimento em caminhos de subdiretório diferentes de /docs.
  Por exemplo, /help, /support, etc.

• Ao configurar outros caminhos, adicione as linguagens associadas a cada Workspace.

• Adicione mais algumas linhas para conseguir isso. Reinicie o servidor assim que terminar.

Exemplo:

NOTA

Substitua o domínio fornecido pelo Document360 e o domínio do subdiretório pelos seus próprios domínios. Além disso, substitua o nome do workspace, o caminho da subpasta e o idioma pelos seus requisitos.

• O Document360 forneceu domínio representado como example.document360.io

• Nome do espaço de trabalho representado como /v1/

• Caminho da subpasta representado como /help/

• Língua representada como /he para o hebraico.

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

Remoção do slug do workspace dos links internos

Se necessário, você pode remover slugs de workspace dos links internos no nível do proxy reverso NGINX usando sub_filter regras.

Exemplo:

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

Use essa abordagem apenas se a estrutura do seu site exigir URLs independentes do espaço de trabalho.

Por que proxy_set_header Accept-Encoding "" é necessário

Ao hospedar uma base de conhecimento Document360 em uma subpasta personalizada (por exemplo, /help), o NGINX comumente usa sub_filter para reescrever URLs internas, como /docs para /help.

Por padrão, o servidor upstream (Document360) pode devolver HTML comprimido em gzip. O NGINX não pode aplicar sub_filter regras sobre respostas comprimidas.

Isso leva aos seguintes problemas:

• Links internos não são reescritos

• Widgets da página inicial continuam apontando para /docs

• Cartões de categoria e rotas de navegação quebram

Para garantir que a reescrita de URL funcione corretamente, você deve desativar a compressão do servidor upstream adicionando a seguinte diretiva:

proxy_set_header Accept-Encoding "";

Este cenário:

Essa configuração é necessária sempre que sub_filter for usada.

Configuração obrigatória de caminhos de API para KB Site 2.0

Se você estiver no KB Site 2.0, é obrigado a definir um caminho de API Personalizado para o Site e adicionar um bloco correspondente location na sua configuração NGINX.

Isso garante que as requisições de API sejam roteadas corretamente para o Document360 e evita problemas como loops de redirecionamento ou chamadas de API quebradas.

Aqui está um exemplo usando /api como caminho da API do 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;
}

NOTA

Substituir /api e /docs-api com os valores exatos configurados no caminho da API do Site no portal Document360.

Depois de adicionar ambos location os blocos, reinicie o servidor web da Nginx. Por exemplo, se você estiver usando Nginx no Linux, use o comando $ sudo systemctl restart nginx.

Use sub_filter_types *; apenas ao reescrever respostas HTML ou API que possam devolver conteúdo não HTML. Evite usá-lo a menos que seja necessário reescrever URLs.

Quando usar sub_filter no bloco de localização da API

Adicionar sub_filter regras no bloco de localização da API nem sempre é obrigatório.

Use sub_filter no bloco de localização da API apenas quando:

• Seu caminho da interface é reescrito (por exemplo, /docs → /help)

• Respostas de API contêm caminhos embutidos /docs que precisam ser reescritos

Se seu projeto continuar sendo usado /docs como caminho da interface, não adicione sub_filter regras ao bloco da API.

IMPORTANTE
Se seu domínio já for usado /api para outra aplicação, você deve atualizar o Caminho da API do Site no portal Document360 para um valor diferente (por exemplo, /docs-api) e usar o mesmo caminho na sua configuração NGINX.

O caminho da API configurado no portal e o bloco de localização NGINX devem coincidir exatamente.

Para ativar o menu suspenso de workspaces

Se você quiser ativar a navegação suspensa do seu projeto ao hospedar o espaço de trabalho em um subdiretório e caminho personalizados, adicione o código a seguir para cada um dos espaços de trabalho disponíveis no seu projeto.

Exemplo:

Vamos supor que seu projeto tenha dois espaços de trabalho, v1 e v2. Nesse caso, você deve adicionar dois blocos de código, um para cada Workspace.

NOTA

Substitua o domínio fornecido pelo Document360 e o domínio do subdiretório pelos seus próprios domínios. Além disso, substitua o nome do workspace, o caminho da subpasta e o idioma pelos seus requisitos.

• O Document360 forneceu domínio representado como example.document360.io

• Nome do espaço de trabalho representado como /v1/,/v2/

• Caminho da subpasta representado como /help/

• Língua representada como /he para o hebraico.

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

Se você quer que seus leitores naveguem entre os diferentes espaços públicos do seu projeto a partir do menu suspenso (com clique do mouse), adicione o bloco de localização para todos os espaços de trabalho disponíveis.

1. Reinicie o servidor web Nginx

2. Por exemplo, se você está usando Nginx no Linux, então use o comando
   $ sudo systemctl restart nginx

Links úteis

Aqui estão alguns links externos que podem ajudar você a entender em detalhes os blocos de localização dos servidores Nginx:

• NGINX Docs: Configurando NGINX e NGINX Plus como um Servidor Web

• DigitalOcean: Entendendo Algoritmos de Seleção de Servidores e Blocos de Localização Nginx

Geração de sitemap

Exemplo:

NOTA

Substitua o domínio de exemplo pelo seu próprio domínio/domínio personalizado fornecido no document360.

• Exemplo de domínio representado usando example.document360.io

• O prefixo sitemap permanece o mesmo, exceto pelo código da língua (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 inicial hospedada em uma subpasta

Para hospedar a página inicial do seu projeto em um caminho personalizado de subdiretório/subpasta, adicione o código a seguir para cada um dos espaços de trabalho da página inicial disponíveis no seu projeto.

Exemplo:

Vamos supor que seu projeto tenha dois espaços de trabalho, V1 e V2. Nesse caso, você deve adicionar dois blocos de código, um para cada Workspace.

NOTA

Substitua o domínio fornecido pelo Document360 e o domínio do subdiretório pelos seus próprios domínios. Além disso, substitua o nome do workspace, o caminho da subpasta e o idioma pelos seus requisitos.

• O Document360 forneceu domínio representado como example.document360.io

• Nome do espaço de trabalho 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;
}

DICA PROFISSIONAL

O sinal de igual pode ser usado se a localização precisar corresponder exatamente ao URI da solicitação. Quando esse modificador é combinado, a busca para bem aqui. Para mais informações, clique aqui.

Exemplo: location =/help {

2. Reinicie o servidor web Nginx

3. Por exemplo, se você está usando Nginx no Linux, então use o comando
   $ sudo systemctl restart nginx

Página inicial do site da base de conhecimento

O que acontece depois?

Depois de configurar com sucesso o servidor web, seu site da base de conhecimento estará ativo na sua subpasta/subdiretório personalizado. No entanto, a URL existente do seu projeto atende as solicitações.

Por exemplo, example.document360.io e example.com/docs (se /docs for o caminho da sua pasta) apontará para o site da base de conhecimento.

Isso pode causar duplicação de conteúdo em mecanismos de busca (Google, Bing, etc.). Para evitar isso, será necessário redirecionar do subdomínio do projeto Document360 para seu domínio personalizado.

NOTA

Para permitir o redirecionamento de example.document360.io para example.com/docs, por favor, entre em contato conosco pelo support@document360.com.

URL canônica para hospedagem de subpastas

Ao hospedar sua base de conhecimento em uma subpasta, você deve configurar uma URL canônica para garantir que os motores de busca indexem seu domínio personalizado e o caminho da subpasta, e não o domínio padrão *.document360.io .

Isso previne a indexação duplicada e melhora o desempenho do SEO.

Como definir a URL canônica

1. Vá para Configurações > site da Knowledge Base > Domínio > Subpastas.

2. Insira a URL completa da subpasta (por exemplo, https://example.com/help).

3. Clique em Salvar.

Uma vez configurado, os mecanismos de busca tratarão a URL da subpasta como a fonte principal para indexação.

Solução de problemas

Esta seção oferece orientações passo a passo para solucionar desafios comuns que você pode enfrentar durante o processo de configuração do NGINX. Desde problemas de hospedagem em subpastas até testes de configuração fracassados, cada solução foi projetada para ajudar você a identificar e resolver rapidamente possíveis obstáculos, garantindo uma configuração do servidor suave e eficiente.

Resolvendo diretiva de localização inválida no NGINX

Erro: nginx: [emergência] a diretiva "localização" não é permitida aqui

Esse erro ocorre quando uma diretiva de localização é colocada fora de seu contexto válido, como fora do bloco do servidor. No NGINX, blocos de localização devem ser definidos dentro de um bloco de servidor.

Passos para resolver:

1. Certifique-se de que o bloco de localização esteja posicionado corretamente dentro do bloco do servidor. Consulte o bloco de exemplo abaixo:

   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 esse problema, não coloque diretivas de localização no contexto global http ou fora dele server .

3. Se o problema persistir após seguir essas etapas, entre em contato com a equipe de suporte do Document360 para obter mais assistência: Entre em contato com o suporte do Document360

Problema de disponibilidade de pacotes Certbot

Erro: Nenhum pacote disponível com Certbot

Esse problema ocorre frequentemente quando o repositório EPEL (necessário para instalação do Certbot em distribuições baseadas em RHEL) não está habilitado, ou o gerenciador de pacotes não consegue localizar o Certbot em distribuições baseadas em RHEL.

Passos para resolver:

1. Ative o repositório EPEL usando o código abaixo:

   sudo yum install epel-release

2. Atualize o cache do repositório e tente instalar o Certbot novamente usando o código abaixo:

   sudo yum install certbot

3. Certifique-se de que sua instância tenha acesso à internet para buscar os arquivos do repositório. Se o problema persistir, verifique os arquivos de configuração do repositório em /etc/yum.repos.d/.

4. Se o problema persistir após seguir essas etapas, entre em contato com a equipe de suporte do Document360 para obter mais assistência: Entre em contato com o suporte do Document360

Problema com o teste de configuração NGINX

Erro: Teste de configuração NGINX falhou

Esse problema ocorre quando há um erro de sintaxe no arquivo de configuração NGINX.

Passos para resolvere:

1. Execute o comando de teste de configuração:

   sudo nginx -t

2. Revise a mensagem de erro e o número da linha, como no exemplo mostrado abaixo:

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

3. Abra o arquivo /etc/nginx/sites-enabled/example especificado e corrija o problema de configuração. Por exemplo:

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

4. Uma vez que o problema de configuração seja corrigido, reinicie o NGINX:

   sudo systemctl restart nginx

5. Se o problema persistir após seguir essas etapas, entre em contato com a equipe de suporte do Document360 para obter mais assistência: Entre em contato com o suporte do Document360

Emissão de certificado SSL

Erro: Certificado SSL não funcionando

Esse problema pode ocorrer devido a uma configuração incorreta do SSL NGINX ou quando há um problema com o certificado instalado. Os detalhes do certificado, como domínio e data de expiração, podem não corresponder aos detalhes de configuração.

Passos para resolver:

1. Verifique os arquivos de certificados usando o código abaixo:

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

2. Certifique-se de que sua configuração corresponda aos detalhes do certificado, como domínio e data de validade.

3. Certifique-se de que a configuração SSL do NGINX está correta. Consulte o código abaixo como exemplo:

   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. Depois de concluir, reinicie o NGINX usando o código abaixo:

   sudo systemctl restart nginx

5. Se o problema persistir após seguir essas etapas, entre em contato com a equipe de suporte do Document360 para obter mais assistência: Entre em contato com o suporte do Document360

proxy_set_header Accept-Encoding "";