Proxy inverso
Servi la documentazione su /docs con nginx, Apache, Caddy, Traefik o HAProxy. Include configurazioni testate per ogni proxy inverso.
Se utilizzi già nginx, Apache, Caddy, Traefik o HAProxy, aggiungi un blocco location/route che inoltri il traffico verso /docs al tuo sottodominio Jamdesk.
Prerequisiti
- Accesso alla configurazione del tuo server web
- Il tuo sottodominio Jamdesk (disponibile nelle impostazioni del dashboard)
Se utilizzi un sottopercorso personalizzato invece del valore predefinito /docs, sostituisci /docs in ogni blocco location/route riportato di seguito (nginx, Apache, Caddy, Traefik, HAProxy) con il tuo sottopercorso. Aggiorna nuovamente la configurazione dopo ogni modifica del nome nel dashboard.
nginx
Aggiungi un blocco location per eseguire il proxy delle richieste /docs verso 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;
}
}
Sostituisci YOUR_SLUG con il tuo sottodominio Jamdesk effettivo.
La gestione dei percorsi è importante. L'URL proxy_pass non ha un percorso finale, quindi nginx mantiene il percorso della richiesta originale. Una richiesta a /docs/page viene inoltrata a jamdesk.app/docs/page. Se aggiungi una barra finale (proxy_pass https://...jamdesk.app/), il prefisso /docs viene rimosso. Lascialo esattamente come mostrato sopra.
Dopo aver aggiornato la configurazione, ricarica nginx:
sudo nginx -t && sudo systemctl reload nginxApache
Utilizza mod_proxy per inoltrare le richieste /docs a 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>
Assicurati che i moduli richiesti siano abilitati:
sudo a2enmod proxy proxy_http ssl headers
sudo systemctl reload apache2Caddy
Caddy offre una configurazione semplice del proxy inverso con HTTPS automatico:
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
}
}
Ricarica Caddy dopo le modifiche:
sudo systemctl reload caddyTraefik
Per gli utenti di Traefik, configura un router e un servizio:
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
Per HAProxy, aggiungi le regole 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)]
Inoltra anche i file nella root
robots.txt, sitemap.xml, llms.txt e llms-full.txt vengono serviti dalla root del dominio, non da /docs: un proxy che inoltra solo /docs, /_next e /_jd lascia questi file al tuo sito (oppure non li serve affatto). Questo impedisce la rilevazione da parte degli agenti AI e danneggia la SEO, indipendentemente dal resto di questa pagina.
Aggiungi lo stesso schema location/route utilizzato sopra per /docs per ciascuno di questi quattro percorsi. Per 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;
}
Gli stessi quattro blocchi, con gli stessi header e lo stesso upstream, si applicano ad Apache, Caddy, Traefik e HAProxy: copia il blocco /docs utilizzato sopra e ripetilo una volta per ogni percorso.
Inoltra questi percorsi solo se Jamdesk gestisce la root del tuo dominio. Se il tuo sito principale serve già il proprio robots.txt o sitemap.xml, uniscili invece di sovrascrivere l'uno con l'altro.
Header richiesti
Indipendentemente dal proxy utilizzato, assicurati che siano impostati questi header:
| Header | Valore | Scopo |
|---|---|---|
Host | YOUR_SLUG.jamdesk.app | Identifica la richiesta per Jamdesk |
X-Forwarded-Host | Il tuo dominio | Indica a Jamdesk quale dominio utilizzare negli URL |
X-Forwarded-Proto | https | Garantisce la generazione di URL sicuri |
X-Jamdesk-Forwarded-Host | Il tuo dominio | Richiesto per la verifica del dominio |
?jd_proxy=1 query marker | Aggiunto all'URL upstream | Alternativa all'header per gli strumenti che possono riscrivere solo un URL e non impostare gli header della richiesta — vedi Solo dominio personalizzato |
L'header X-Jamdesk-Forwarded-Host (o il marker ?jd_proxy=1) è obbligatorio; omettere entrambi causa un errore silenzioso.
Le richieste continuano ad avere esito positivo: non si verifica alcun errore, ed è proprio questo che rende facile non accorgersene. Il problema è più sottile:
- Se non hai registrato un dominio personalizzato nel dashboard, le pagine della documentazione vengono servite con
<meta name="robots" content="noindex">e gli URL canonical, Open Graph e della sitemap puntano tutti aYOUR_SLUG.jamdesk.appinvece che al tuo dominio. I motori di ricerca non indicizzeranno mai la tua documentazione. - Se hai registrato un dominio personalizzato, Jamdesk utilizza come fallback il dominio registrato, quindi gli URL restano corretti; tuttavia non può distinguere il traffico del proxy dal traffico diretto verso il tuo sottodominio
*.jamdesk.appe il controllo preliminare Solo dominio personalizzato non andrà a buon fine.
Un 403 indica il problema opposto: l'header è presente, ma specifica un dominio che non è registrato e attivo per questo progetto.
La configurazione del proxy è una configurazione una tantum. Se in seguito modifichi il dominio personalizzato o la configurazione nel dashboard Jamdesk, non è necessario aggiornare il proxy: tutte le decisioni di routing vengono prese lato server in base alle impostazioni del dashboard.
Risoluzione dei problemi
Verifica che il proxy possa raggiungere YOUR_SLUG.jamdesk.app tramite HTTPS. Controlla le regole del firewall e la risoluzione DNS.
Abilita SSL/TLS per la connessione upstream. Per nginx, aggiungi proxy_ssl_server_name on;. Per Apache, abilita SSLProxyEngine On.
Assicurati che l'header X-Forwarded-Host sia impostato correttamente. Indica a Jamdesk quale dominio utilizzare per gli URL degli asset e i link interni.
Verifica che il proxy non segua i reindirizzamenti. Il proxy deve inoltrare la risposta così com'è, senza una gestione aggiuntiva dei reindirizzamenti.
Se visualizzi "Domain is not authorized to serve this content":
- Verifica che il tuo dominio sia registrato nel dashboard Jamdesk
- Completa la verifica DNS (record TXT) per il tuo dominio
- Assicurati che l'header
X-Jamdesk-Forwarded-Hostsia impostato nella configurazione del proxy - Controlla che il tuo dominio punti al progetto corretto
Il dominio deve essere verificato prima che il proxy possa servire la documentazione.
Il controllo preliminare esegue il fetch di /_jd/preflight sul tuo dominio attivo e verifica cosa è effettivamente arrivato a Jamdesk. Se segnala che il proxy "non si identifica", una richiesta ha raggiunto Jamdesk senza l'header o il marker: ricontrolla la riga X-Jamdesk-Forwarded-Host in ogni blocco location/route sopra. Vedi Solo dominio personalizzato per il significato di ogni messaggio del controllo preliminare.