Servidor Nginx

Hospedar sua base de conhecimento Document360 em uma subpasta no Nginx, como example.com/docs, requer configurar proxy e reescrever regras no seu servidor. Este artigo aborda como habilitar os blocos de localização necessários, roteamento de UI e caminhos da API, geração de sitemaps e gerenciamento de redirecionamento de URL para evitar conteúdo duplicado em mecanismos de busca.

Para saber mais sobre o próprio Nginx, veja a documentação do Nginx.

Antes de começar

• A hospedagem de subpastas funciona apenas quando tanto o caminho da subpasta (por exemplo, /docs ou /help) quanto o caminho da API do Site (por exemplo, /api ou /docs-api) são definidos no Document360. Após definir esses valores, configure os blocos correspondentes location no Nginx para proxy tanto o tráfego da interface quanto o da API.
• Substitua o domínio de exemplo ao longo deste artigo por seu próprio domínio fornecido pelo Document360 ou domínio personalizado. Por exemplo, example.document360.io representa seu domínio e example.document360.io/docs representa o caminho da subpasta.

Como configurar um caminho de subpasta no Nginx

1. Adicione o seguinte bloco de localização ao 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 da Nginx. No Linux, use:

sudo systemctl restart nginx

Como usar um caminho de subpasta personalizado

Você pode hospedar sua base de conhecimento em um caminho diferente de /docs, como /help ou /support. Ao configurar um caminho personalizado, adicione também as linguagens associadas a cada workspace e depois reinicie o servidor.

O exemplo abaixo mapeia o domínio example.document360.io, espaço de trabalho /v1/, caminho /help/de subpasta e código em hebraico /he fornecidos pelo Document360 — substitua esses por seus próprios 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;
}

Remoção do slug do workspace dos links internos

Para remover slugs de workspace dos links internos no nível de proxy reverso Nginx, use uma sub_filter regra:

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

Isso reescreve caminhos específicos do espaço de trabalho antes que sejam servidos aos leitores. 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 em uma subpasta personalizada, a Nginx costuma usar sub_filter para reescrever URLs internas, como /docs para /help. Por padrão, o servidor upstream (Document360) pode retornar HTML comprimido em gzip, e o Nginx não pode aplicar sub_filter regras a respostas comprimidas. Isso faz com que links internos fiquem sem reescrita, widgets da página inicial continuem apontando para /docs, e cartões de categoria ou rotas de navegação quebrem.

Para resolver isso, desative a compressão do servidor upstream:

proxy_set_header Accept-Encoding "";

Isso força o Document360 a retornar HTML não comprimido, permite sub_filter que regras sejam executadas corretamente e garante que caminhos como /docs/en/ o sejam reescritos para /help/en/. Essa configuração é necessária sempre que sub_filter for usada.

Como configurar o caminho da API do Site

Se você hospeda sua base de conhecimento em uma subpasta, também deve definir um caminho de API Site e adicionar um bloco correspondente location no Nginx, para garantir que as requisições de API sejam roteadas corretamente e evitar loops de redirecionamento ou chamadas de API quebradas.

O exemplo abaixo usa /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;
}

Depois de adicionar ambos os blocos de localização, reinicie o Nginx:

sudo systemctl restart nginx

Use sub_filter_types *; apenas ao reescrever respostas em HTML ou API que possam devolver conteúdo não HTML — evite isso, a menos que a reescrita de URL seja realmente necessária.

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

Adicionar sub_filter regras ao bloco de localização da API nem sempre é necessário. Use isso apenas quando seu caminho da interface for reescrito (por exemplo, /docs → /help) ou quando as respostas da 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.

Como ativar o menu suspenso dos espaços de trabalho

Para habilitar a navegação suspensa do workspace ao hospedar em um subdiretório personalizado, adicione um bloco de código para cada workspace do seu projeto.

O exemplo abaixo cobre dois espaços de trabalho, v1 e v2, com domínio example.document360.ioDocument360 , caminho /help/de subpasta , e idioma /he hebraico — substitua esses por seus próprios 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;
}

Reinicie o Nginx assim que configurado:

sudo systemctl restart nginx

A página inicial padrão de um site de base de conhecimento aparece no diretório raiz, por example.document360.ioexemplo. Se seu projeto tiver uma página inicial específica de espaço de trabalho e idioma, o slug após o diretório raiz segue o formato /<workspace_name>/<language_code>, por example.document360.io/v2/heexemplo.

Como configurar a geração de sitemaps

O prefixo do sitemap permanece o mesmo, exceto pelo código da língua (en, fr, de, e assim por diante).

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

Como definir a URL canônica

Ao hospedar sua base de conhecimento em uma subpasta, configure uma URL canônica para que os motores de busca indexem seu domínio personalizado e o caminho da subpasta, em vez do domínio padrão *.document360.io . Isso previne a indexação duplicada e melhora o desempenho do SEO.

1. Navegue até Configurações > Site da base de conhecimento > Domínio > Hospedagem de subpastasDomínio personalizado
2. Insira a URL completa da subpasta, por https://example.com/helpexemplo.
3. Clique em Salvar.

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

O que acontece a seguir

Depois que o Nginx está configurado, seu site de base de conhecimento fica ativo na sua subpasta personalizada. A URL existente do Document360 continua a atender solicitações também – por exemplo, ambas example.document360.io e example.com/docs apontará para o seu site de base de conhecimento. Isso causa conteúdo duplicado nos mecanismos de busca.

Para evitar isso, ative a opção Restringir acesso a subdomínios em Configurações () > Site da base de conhecimento > Domínio personalizado personalizado > Hospedagem de subpastas. Certifique-se de que um domínio canônico esteja configurado primeiro – uma vez habilitado, seu subdomínio Document360 redireciona automaticamente para seu domínio canônico.

Links úteis

• 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

Melhores práticas

• Sempre adicione proxy_set_header Accept-Encoding ""; a qualquer bloco de localização usando sub_filter, ou suas regras de reescrita não se aplicarão a respostas comprimidas.
• Mantenha o caminho da API do site idêntico entre o portal Document360 e sua configuração Nginx — uma incompatibilidade causa chamadas de API quebradas.
• Adicione sub_filter regras ao bloco de localização da API apenas quando seu caminho da interface for reescrito ou as respostas da API conterem caminhos embutidos /docs .
• Configure uma URL canônica antes de ativar Restringir acesso a subdomínios, para evitar problemas de redirecionamento durante a configuração.

FAQ