Proxy inverso
Sirve tu documentación en /docs usando nginx, Apache, Caddy, Traefik o HAProxy. Incluye fragmentos de configuración probados para cada proxy inverso.
Si ya usas nginx, Apache, Caddy, Traefik o HAProxy, añade un bloque de location/route 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)
Si usas una subruta personalizada en lugar de /docs por defecto, reemplaza /docs en cada bloque de location/route a continuación (nginx, Apache, Caddy, Traefik, HAProxy) por tu subruta. Actualiza la configuración de nuevo después de cualquier cambio de nombre en el dashboard.
nginx
Añade un bloque location para redirigir las solicitudes de /docs a 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 por tu subdominio real de Jamdesk.
El manejo de la ruta es importante. 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. Mantenlo 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 de /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>
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 los cambios:
sudo systemctl reload caddyTraefik
Para los 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 estos archivos servidos por tu propio sitio (o no servidos en absoluto), lo que rompe el descubrimiento por agentes de IA y te cuesta SEO, independientemente de todo lo demás en esta página.
Añade el mismo patrón de bloque location/route 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;
}
Estos mismos cuatro bloques — mismos encabezados, mismo upstream — se aplican a Apache, Caddy, Traefik y HAProxy: copia el bloque /docs que estés usando arriba y repítelo una vez por 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 requeridos
Independientemente del proxy que uses, asegúrate de que estos encabezados estén configurados:
| 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 URL |
X-Forwarded-Proto | https | Garantiza la generación segura de URL |
X-Jamdesk-Forwarded-Host | Tu dominio | Requerido para la verificación del dominio |
Marcador de consulta ?jd_proxy=1 | Añadido a la URL de 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 prescindir de ambos falla silenciosamente.
Las solicitudes se completan igualmente — no aparece ningún error, lo que hace que sea 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 URL canónicas, de Open Graph y de 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 URL siguen siendo 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 contrario: el encabezado sí está presente, pero indica un dominio que no está registrado y 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, el proxy no necesita actualizarse - todas las decisiones de enrutamiento se toman del lado del servidor según la configuración de tu dashboard.
Solución de problemas
Verifica que el proxy pueda alcanzar YOUR_SLUG.jamdesk.app mediante HTTPS. Revisa las reglas de firewall y la resolución DNS.
Habilita SSL/TLS para la conexión de 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 URL de los recursos y los enlaces internos.
Verifica que tu proxy no esté siguiendo redirecciones. El proxy debe reenviar la respuesta tal cual, sin manejo adicional de redirecciones.
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 DNS (registro TXT) de tu dominio
- Asegúrate de que el encabezado
X-Jamdesk-Forwarded-Hostesté configurado en tu configuración de proxy - Verifica que tu dominio se corresponda con el proyecto correcto
El dominio debe estar verificado antes de que el proxy pueda servir la documentación.
Preflight obtiene /_jd/preflight en tu dominio en producción y verifica qué llegó realmente a Jamdesk. Si informa que tu proxy "no se identifica", una solicitud llegó a Jamdesk pero sin el encabezado ni el marcador — vuelve a revisar la línea X-Jamdesk-Forwarded-Host en cada bloque location/route anterior. Consulta Solo dominio personalizado para saber qué significa cada mensaje de preflight.