Proxy inverso
Configura un proxy inverso personalizado con Nginx, Apache o Caddy para servir tu documentación de Mintlify en una subruta de tu propio dominio.
Para publicar tu documentación a través de un proxy inverso personalizado, debes configurar reglas de enrutamiento, políticas de caché y reenvío de encabezados.
Al implementar un proxy inverso, supervisa posibles problemas con la verificación del dominio, el aprovisionamiento de certificados SSL, los flujos de autenticación, el rendimiento y el seguimiento de analíticas.
Configura tu ruta base en la página de configuración de dominio personalizado en tu dashboard y, luego, configura tu proxy inverso para enrutar esa ruta a Mintlify. La ruta base predeterminada es /docs, pero puedes usar cualquier ruta base que elijas, como /help o /resources.
En todas las configuraciones, usa mintlify.site como destino del proxy.
Usa esta configuración cuando quieras servir la documentación en la ruta /docs de tu dominio.
Antes de configurar tu proxy inverso:
- Ve a la configuración de dominio personalizado en tu dashboard.
- Habilita el interruptor Host at.
- Ingresa tu dominio.
- Ingresa
docscomo tu ruta base. - Haz clic en Add domain.
Cuando alojas en una subruta, la URL canónica de tu documentación se convierte en <your-subdomain>.mintlify.site<your-base-path>, como <your-subdomain>.mintlify.site/docs. Dirige el proxy a <your-subdomain>.mintlify.site para que la invalidación de caché y las actualizaciones surtan efecto.
Redirige mediante proxy estas rutas a tu subdominio de Mintlify:
| Ruta | Destino | Caché |
|---|---|---|
/docs | <your-subdomain>.mintlify.site/docs | Sin caché |
/docs/* | <your-subdomain>.mintlify.site/docs/* | Sin caché |
/.well-known/vercel/* | <your-subdomain>.mintlify.site/.well-known/vercel/* | Sin caché |
/.well-known/skills/* (opcional) | <your-subdomain>.mintlify.site/docs/.well-known/skills/* | Sin caché |
/.well-known/agent-skills/* (opcional) | <your-subdomain>.mintlify.site/docs/.well-known/agent-skills/* | Sin caché |
/skill.md (opcional) | <your-subdomain>.mintlify.site/docs/skill.md | Sin caché |
/llms.txt (opcional) | <your-subdomain>.mintlify.site/docs/llms.txt | Sin caché |
/llms-full.txt (opcional) | <your-subdomain>.mintlify.site/docs/llms-full.txt | Sin caché |
Tu proxy debe reenviar todos los métodos HTTP en las rutas de documentación. Mintlify envía eventos de analítica como solicitudes POST a /docs/_mintlify/api/v1/e, por lo que un proxy que solo permita solicitudes GET y HEAD interrumpirá silenciosamente las analíticas en tu panel.
Mintlify sirve estos archivos bajo tu ruta base, como <your-subdomain>.mintlify.site/docs/llms.txt, de modo que están disponibles en tu dominio bajo tu subruta, como your-domain.com/docs/llms.txt, a través de tu ruta de subruta principal.
Las rutas /.well-known/skills/*, /.well-known/agent-skills/*, /skill.md, /llms.txt y /llms-full.txt son opcionales. Inclúyelas solo si también quieres servir estos archivos en rutas raíz de tu dominio, como your-domain.com/llms.txt. Ten en cuenta que cada ruta raíz se mapea al archivo bajo tu ruta base en tu subdominio de Mintlify.
Configura tu proxy inverso con estos requisitos de encabezados:
- Origin: Contiene el subdominio de destino
<your-subdomain>.mintlify.site - X-Forwarded-For: Conserva la información de la IP del cliente
- X-Forwarded-Proto: Conserva el protocolo original (HTTP/HTTPS)
- X-Real-IP: Reenvía la dirección IP real del cliente
- User-Agent: Reenvía el agente de usuario
Asegúrate de no reenviar el encabezado Host.
server {
listen 80;
server_name <your-domain>.com;
# Vercel verification paths
location ~ ^/\.well-known/vercel/ {
proxy_pass https://<your-subdomain>.mintlify.site;
proxy_set_header Origin <your-subdomain>.mintlify.site;
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 User-Agent $http_user_agent;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# AI skills paths
location ^~ /.well-known/skills/ {
proxy_pass https://<your-subdomain>.mintlify.site/docs/.well-known/skills/;
proxy_set_header Origin <your-subdomain>.mintlify.site;
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 User-Agent $http_user_agent;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# Agent-skills discovery paths
location ^~ /.well-known/agent-skills/ {
proxy_pass https://<your-subdomain>.mintlify.site/docs/.well-known/agent-skills/;
proxy_set_header Origin <your-subdomain>.mintlify.site;
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 User-Agent $http_user_agent;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# Skill manifest (optional)
location = /skill.md {
proxy_pass https://<your-subdomain>.mintlify.site/docs/skill.md;
proxy_set_header Origin <your-subdomain>.mintlify.site;
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 User-Agent $http_user_agent;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# LLM index files (optional)
location = /llms.txt {
proxy_pass https://<your-subdomain>.mintlify.site/docs/llms.txt;
proxy_set_header Origin <your-subdomain>.mintlify.site;
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 User-Agent $http_user_agent;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
location = /llms-full.txt {
proxy_pass https://<your-subdomain>.mintlify.site/docs/llms-full.txt;
proxy_set_header Origin <your-subdomain>.mintlify.site;
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 User-Agent $http_user_agent;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# Documentation root
location = /docs {
proxy_pass https://<your-subdomain>.mintlify.site;
proxy_set_header Origin <your-subdomain>.mintlify.site;
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 User-Agent $http_user_agent;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# All documentation paths
location /docs/ {
proxy_pass https://<your-subdomain>.mintlify.site/docs/;
proxy_set_header Origin <your-subdomain>.mintlify.site;
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 User-Agent $http_user_agent;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
}Para usar una subruta distinta de /docs (como /help o /resources):
- Ve a la página de configuración de dominio personalizado en tu dashboard.
- Habilita el interruptor Host at e ingresa tu ruta base. Por ejemplo,
/docso/help. - Ingresa tu dominio.
- Ingresa tu ruta base.
- Haz clic en Add domain.
Mintlify reconstruye tu documentación para servirla en tu ruta base, de modo que <your-subdomain>.mintlify.site<your-base-path> sirve tu contenido.
Configura tu proxy inverso usando la misma configuración de enrutamiento, los mismos requisitos de encabezados y los mismos patrones de nginx que la subruta /docs, reemplazando /docs por tu ruta base.
Síntomas: Publicas actualizaciones de la documentación, pero los cambios no aparecen en tu sitio.
Causa: Tu proxy inverso apunta a un nombre de host obsoleto.
Solución: Actualiza la configuración de tu proxy inverso para que apunte a <your-subdomain>.mintlify.site.
Síntomas: La documentación carga, pero las funciones no se ejecutan. Las llamadas a la API fallan.
Causa: El proxy inverso reenvía el encabezado Host o falta el encabezado Origin.
Solución:
- Elimina el reenvío del encabezado
Host - Configura el encabezado
Origincon tu subdominio de Mintlify (<your-subdomain>.mintlify.site)
Síntomas: Cargas de página lentas y desplazamientos de diseño.
Causa: Configuración de caché incorrecta.
Solución: Deshabilita la caché para las rutas de documentación. Si proxyeas rutas /mintlify-assets/_next/static/*, habilita la caché solo para esos recursos estáticos.