Proxy reverso
Publique sua documentação em /docs usando nginx, Apache, Caddy, Traefik ou HAProxy, com configurações testadas para cada proxy reverso.
Se você já usa nginx, Apache, Caddy, Traefik ou HAProxy, adicione um bloco de localização/rota que encaminhe o tráfego de /docs para seu subdomínio do Jamdesk.
Pré-requisitos
- Acesso à configuração do seu servidor web
- Seu subdomínio do Jamdesk (encontrado nas configurações do painel)
Se você usar um subcaminho personalizado em vez do /docs padrão, substitua /docs em todos os blocos de localização/rota abaixo (nginx, Apache, Caddy, Traefik, HAProxy) pelo seu subcaminho. Atualize a configuração novamente após qualquer renomeação no painel.
nginx
Adicione um bloco de localização para encaminhar as solicitações a /docs para o Jamdesk:
server {
listen 443 ssl;
server_name yoursite.com;
# Your existing configuration...
# Proxy /docs to Jamdesk
location /docs {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
# Required for domain verification
proxy_set_header X-Jamdesk-Forwarded-Host $host;
}
# Next.js static assets (JS, CSS)
location /_next/ {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
}
# Jamdesk assets (fonts, images, branding)
location /_jd/ {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
}
}
Substitua YOUR_SLUG pelo seu subdomínio real do Jamdesk.
O tratamento do caminho é importante. A URL proxy_pass não tem um caminho final, portanto o nginx preserva o caminho original da solicitação. Uma solicitação para /docs/page é encaminhada para jamdesk.app/docs/page. Se você adicionar uma barra final (proxy_pass https://...jamdesk.app/), o prefixo /docs será removido. Mantenha exatamente como mostrado acima.
Após atualizar sua configuração, recarregue o nginx:
sudo nginx -t && sudo systemctl reload nginxApache
Use mod_proxy para encaminhar as solicitações a /docs para o Jamdesk:
<VirtualHost *:443>
ServerName yoursite.com
# Your existing configuration...
# Enable proxy modules
ProxyRequests Off
SSLProxyEngine On
# Proxy /docs to Jamdesk
ProxyPass /docs https://YOUR_SLUG.jamdesk.app/docs
ProxyPassReverse /docs https://YOUR_SLUG.jamdesk.app/docs
# Next.js static assets (JS, CSS)
ProxyPass /_next https://YOUR_SLUG.jamdesk.app/_next
ProxyPassReverse /_next https://YOUR_SLUG.jamdesk.app/_next
# Jamdesk assets (fonts, images, branding)
ProxyPass /_jd https://YOUR_SLUG.jamdesk.app/_jd
ProxyPassReverse /_jd https://YOUR_SLUG.jamdesk.app/_jd
<Location /docs>
RequestHeader set X-Forwarded-Host "yoursite.com"
RequestHeader set X-Forwarded-Proto "https"
# Required for domain verification
RequestHeader set X-Jamdesk-Forwarded-Host "yoursite.com"
</Location>
</VirtualHost>
Verifique se os módulos necessários estão habilitados:
sudo a2enmod proxy proxy_http ssl headers
sudo systemctl reload apache2Caddy
O Caddy fornece uma configuração simples de proxy reverso com HTTPS automático:
yoursite.com {
# Your existing configuration...
handle /docs* {
reverse_proxy https://YOUR_SLUG.jamdesk.app {
header_up Host {upstream_hostport}
header_up X-Forwarded-Host {host}
# Required for domain verification
header_up X-Jamdesk-Forwarded-Host {host}
}
}
# Next.js static assets and Jamdesk assets
handle /_next/* {
reverse_proxy https://YOUR_SLUG.jamdesk.app {
header_up Host {upstream_hostport}
}
}
handle /_jd/* {
reverse_proxy https://YOUR_SLUG.jamdesk.app {
header_up Host {upstream_hostport}
}
}
# Handle other routes
handle {
# Your main site configuration
}
}
Recarregue o Caddy após as alterações:
sudo systemctl reload caddyTraefik
Para usuários do Traefik, configure um roteador e um serviço:
http:
routers:
docs-router:
rule: "Host(`yoursite.com`) && (PathPrefix(`/docs`) || PathPrefix(`/_next`) || PathPrefix(`/_jd`))"
service: jamdesk-docs
middlewares:
- jamdesk-headers
tls: {}
middlewares:
jamdesk-headers:
headers:
customRequestHeaders:
# Required for domain verification
X-Jamdesk-Forwarded-Host: "yoursite.com"
services:
jamdesk-docs:
loadBalancer:
servers:
- url: "https://YOUR_SLUG.jamdesk.app"
passHostHeader: falseHAProxy
Para o HAProxy, adicione regras de backend e ACL:
frontend https
bind *:443 ssl crt /etc/ssl/certs/yoursite.pem
# Route /docs and assets to Jamdesk backend
acl is_docs path_beg /docs
acl is_next path_beg /_next
acl is_jd path_beg /_jd
use_backend jamdesk_docs if is_docs or is_next or is_jd
# Default backend for other requests
default_backend main_site
backend jamdesk_docs
server jamdesk YOUR_SLUG.jamdesk.app:443 ssl verify none
http-request set-header Host YOUR_SLUG.jamdesk.app
http-request set-header X-Forwarded-Host %[req.hdr(host)]
# Required for domain verification
http-request set-header X-Jamdesk-Forwarded-Host %[req.hdr(host)]
Encaminhe também os arquivos da raiz
robots.txt, sitemap.xml, llms.txt e llms-full.txt são servidos a partir da raiz do domínio, não de /docs. Um proxy que encaminha apenas /docs, /_next e /_jd deixa esses arquivos serem servidos pelo seu próprio site (ou não serem servidos), o que impede a descoberta por agentes de IA e prejudica seu SEO, independentemente do restante desta página.
Adicione o mesmo padrão de localização/rota usado acima para /docs a cada um desses quatro caminhos. Para nginx:
location = /robots.txt {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
proxy_set_header X-Jamdesk-Forwarded-Host $host;
}
location = /sitemap.xml {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
proxy_set_header X-Jamdesk-Forwarded-Host $host;
}
location = /llms.txt {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
proxy_set_header X-Jamdesk-Forwarded-Host $host;
}
location = /llms-full.txt {
proxy_pass https://YOUR_SLUG.jamdesk.app;
proxy_ssl_server_name on;
proxy_set_header Host YOUR_SLUG.jamdesk.app;
proxy_set_header X-Jamdesk-Forwarded-Host $host;
}
Os mesmos quatro blocos — com os mesmos cabeçalhos e o mesmo upstream — aplicam-se ao Apache, Caddy, Traefik e HAProxy: copie o bloco de /docs usado acima e repita-o uma vez para cada caminho.
Encaminhe esses arquivos somente se o Jamdesk for responsável pela raiz do seu domínio. Se o seu site principal já servir o próprio robots.txt ou sitemap.xml, combine os dois em vez de substituir um pelo outro.
Cabeçalhos obrigatórios
Independentemente do proxy usado, verifique se estes cabeçalhos estão definidos:
| Cabeçalho | Valor | Finalidade |
|---|---|---|
Host | YOUR_SLUG.jamdesk.app | Identifica a solicitação para o Jamdesk |
X-Forwarded-Host | Seu domínio | Informa ao Jamdesk qual domínio usar nas URLs |
X-Forwarded-Proto | https | Garante a geração de URLs seguras |
X-Jamdesk-Forwarded-Host | Seu domínio | Obrigatório para a verificação do domínio |
Marcador de consulta ?jd_proxy=1 | Anexado à URL upstream | Alternativa ao cabeçalho para ferramentas que só conseguem reescrever uma URL e não podem definir cabeçalhos de solicitação — consulte Somente domínio personalizado |
O cabeçalho X-Jamdesk-Forwarded-Host (ou o marcador ?jd_proxy=1) é obrigatório, e não usar nenhum dos dois falha silenciosamente.
As solicitações continuam funcionando — nada apresenta erro, o que torna o problema fácil de não perceber. O que falha é mais sutil:
- Se você ainda não registrou um domínio personalizado no painel, suas páginas de documentação serão servidas com
<meta name="robots" content="noindex">, e as URLs canônicas, do Open Graph e do sitemap apontarão paraYOUR_SLUG.jamdesk.appem vez do seu domínio. Os mecanismos de busca nunca indexarão sua documentação. - Se você registrou um domínio personalizado, o Jamdesk usará o domínio cadastrado, mantendo suas URLs corretas — mas ainda não conseguirá distinguir o tráfego do proxy do tráfego direto para seu subdomínio
*.jamdesk.app, e a verificação preliminar de Somente domínio personalizado falhará.
Um 403 indica o problema oposto: o cabeçalho está presente, mas informa um domínio que não está registrado e ativo para este projeto.
A configuração do proxy é uma configuração única. Se você alterar posteriormente seu domínio personalizado ou a configuração no painel do Jamdesk, não será necessário atualizar o proxy — todas as decisões de roteamento são tomadas no servidor com base nas configurações do painel.
Solução de problemas
Verifique se o proxy consegue acessar YOUR_SLUG.jamdesk.app por HTTPS. Confira as regras do firewall e a resolução de DNS.
Habilite SSL/TLS para a conexão upstream. No nginx, adicione proxy_ssl_server_name on;. No Apache, habilite SSLProxyEngine On.
Verifique se o cabeçalho X-Forwarded-Host está definido corretamente. Ele informa ao Jamdesk qual domínio usar nas URLs de ativos e nos links internos.
Verifique se o proxy não está seguindo redirecionamentos. O proxy deve encaminhar a resposta como está, sem tratamento adicional de redirecionamentos.
Se você vir a mensagem "Domain is not authorized to serve this content":
- Verifique se seu domínio está registrado no painel do Jamdesk
- Conclua a verificação de DNS (registro TXT) do seu domínio
- Verifique se o cabeçalho
X-Jamdesk-Forwarded-Hostestá definido na configuração do proxy - Verifique se seu domínio está associado ao projeto correto
O domínio precisa ser verificado antes que o proxy possa servir a documentação.
A verificação preliminar busca /_jd/preflight no seu domínio ativo e verifica o que realmente chegou ao Jamdesk. Se ela informar que o proxy "não se identifica", uma solicitação chegou ao Jamdesk sem o cabeçalho ou o marcador — verifique novamente a linha X-Jamdesk-Forwarded-Host em todos os blocos de localização/rota acima. Consulte Somente domínio personalizado para saber o significado de cada mensagem da verificação preliminar.