Proxy inverso
Sirve tu documentación en /docs con nginx, Apache, Caddy, Traefik o HAProxy. Incluye snippets de configuración probados para cada proxy inverso.
Si ya usas nginx, Apache, Caddy, Traefik o HAProxy, añade un bloque de ubicación/ruta que redirija el tráfico de /docs a tu subdominio de Jamdesk.
Requisitos previos
- Acceso a la configuración de tu servidor web
- Tu subdominio de Jamdesk (disponible en la configuración del dashboard)
nginx
Añade un bloque de ubicación (location) para redirigir las solicitudes a /docs hacia 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;
}
}
Reemplaza YOUR_SLUG con tu subdominio real de Jamdesk.
El manejo de rutas importa. La URL de proxy_pass no tiene ruta final, por lo que nginx conserva la ruta original de la solicitud. Una solicitud a /docs/page se redirige a jamdesk.app/docs/page. Si añades una barra final (proxy_pass https://...jamdesk.app/), se elimina el prefijo /docs. Mantenla exactamente como se muestra arriba.
Después de actualizar tu configuración, recarga nginx:
sudo nginx -t && sudo systemctl reload nginxApache
Usa mod_proxy para redirigir las solicitudes a /docs hacia 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>
Asegúrate de que los módulos necesarios estén habilitados:
sudo a2enmod proxy proxy_http ssl headers
sudo systemctl reload apache2Caddy
Caddy ofrece una configuración de proxy inverso sencilla con 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
}
}
Recarga Caddy después de hacer cambios:
sudo systemctl reload caddyTraefik
Para usuarios de Traefik, configura un router y un servicio:
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 HAProxy, añade reglas de backend y 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)]
Redirige también tus archivos raíz
robots.txt, sitemap.xml, llms.txt y llms-full.txt se sirven desde la raíz del dominio, no desde /docs — un proxy que solo redirige /docs, /_next y /_jd deja que estos archivos los sirva tu propio sitio (o no se sirvan en absoluto), lo que rompe el descubrimiento por parte de agentes de IA y te cuesta SEO, independientemente de todo lo demás en esta página.
Añade el mismo patrón de ubicación/ruta que usaste para /docs arriba, para cada una de estas cuatro rutas. 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;
}
Los mismos cuatro bloques —mismos encabezados, mismo upstream— se aplican a Apache, Caddy, Traefik y HAProxy: copia el bloque de /docs que estés usando arriba y repítelo una vez por cada ruta.
Redirige estos archivos solo si Jamdesk es propietario de la raíz de tu dominio. Si tu sitio principal ya sirve su propio robots.txt o sitemap.xml, combina ambos en lugar de sobrescribir uno con el otro.
Encabezados necesarios
Independientemente del proxy que uses, asegúrate de configurar estos encabezados:
| Header | Valor | Propósito |
|---|---|---|
Host | YOUR_SLUG.jamdesk.app | Identifica la solicitud ante Jamdesk |
X-Forwarded-Host | Tu dominio | Indica a Jamdesk qué dominio usar en las URLs |
X-Forwarded-Proto | https | Garantiza la generación segura de URL |
X-Jamdesk-Forwarded-Host | Tu dominio | Necesario para la verificación de dominio |
Marcador de consulta ?jd_proxy=1 | Añadido a la URL upstream | Alternativa al encabezado, para herramientas que solo pueden reescribir una URL y no pueden establecer encabezados de solicitud — consulta Solo dominio personalizado |
El encabezado X-Jamdesk-Forwarded-Host (o el marcador ?jd_proxy=1) es obligatorio, y omitir ambos falla de forma silenciosa.
Las solicitudes siguen teniendo éxito —nada da error, que es justo lo que hace fácil pasarlo por alto. Lo que falla es más sutil:
- Si no has registrado un dominio personalizado en el dashboard, tus páginas de documentación se sirven con
<meta name="robots" content="noindex">, y las URLs canónicas, de Open Graph y del sitemap apuntan todas aYOUR_SLUG.jamdesk.appen lugar de a tu dominio. Los motores de búsqueda nunca indexarán tu documentación. - Si has registrado un dominio personalizado, Jamdesk recurre al dominio registrado, por lo que tus URLs se mantienen correctas —pero aun así no puede distinguir el tráfico del proxy del tráfico directo a tu subdominio
*.jamdesk.app, y la verificación previa de Solo dominio personalizado fallará.
Un 403 es el problema opuesto: el encabezado sí está presente, pero indica un dominio que no está registrado ni activo para este proyecto.
La configuración del proxy es una configuración única. Si más adelante cambias tu dominio personalizado o la configuración en el dashboard de Jamdesk, no es necesario actualizar el proxy: todas las decisiones de enrutamiento se toman en el servidor según la configuración de tu dashboard.
Solución de problemas
Verifica que el proxy pueda acceder a YOUR_SLUG.jamdesk.app mediante HTTPS. Revisa las reglas del firewall y la resolución de DNS.
Habilita SSL/TLS para la conexión upstream. En nginx, añade proxy_ssl_server_name on;. En Apache, habilita SSLProxyEngine On.
Asegúrate de que el encabezado X-Forwarded-Host esté configurado correctamente. Esto indica a Jamdesk qué dominio usar para las URLs de los recursos y los enlaces internos.
Verifica que tu proxy no esté siguiendo redirecciones. El proxy debe reenviar la respuesta tal cual, sin gestionar redirecciones adicionales.
Si ves "Domain is not authorized to serve this content":
- Verifica que tu dominio esté registrado en el dashboard de Jamdesk
- Completa la verificación de DNS (registro TXT) para tu dominio
- Asegúrate de que el encabezado
X-Jamdesk-Forwarded-Hostesté configurado en tu proxy - Verifica que tu dominio esté asignado al proyecto correcto
El dominio debe estar verificado antes de que el proxy pueda servir la documentación.
La verificación previa obtiene /_jd/preflight en tu dominio activo y comprueba qué llegó realmente a Jamdesk. Si indica que tu proxy "no se identifica", significa que una solicitud llegó a Jamdesk pero sin el encabezado ni el marcador — revisa la línea X-Jamdesk-Forwarded-Host en cada bloque de ubicación/ruta anterior. Consulta Solo dominio personalizado para saber qué significa cada mensaje de la verificación previa.