Las configuraciones de proxy inverso solo están disponibles en los planes Enterprise. Elige tu enfoque de implementación
- Alojar en
/docs: Usa mintlify.dev como destino del proxy. Activa la opción Host at /docs en la página Custom domain setup de tu dashboard. Esta es una configuración más sencilla con menos rutas.
- Subruta personalizada: Usa
mintlify.app como destino del proxy. Este enfoque admite cualquier subruta y requiere reglas de enrutamiento adicionales.
Hospedar en la subruta /docs
/docs de tu dominio.
Antes de configurar tu proxy inverso:
- Navega a Configuración de dominio personalizado en tu dashboard.
- Activa la opción Host at
/docs.
- Ingresa tu domain y selecciona Add domain.
Cuando activas Host at /docs, la URL canónica de tu documentación se convierte en <your-subdomain>.mintlify.dev. La invalidación de caché se detiene en mintlify.app y debes dirigir el proxy a mintlify.dev para que aparezcan las actualizaciones.
Configuración de enrutamiento
| Ruta | Destino | Caché |
|---|
/docs | <your-subdomain>.mintlify.dev/docs | Sin caché |
/docs/* | <your-subdomain>.mintlify.dev/docs | Sin caché |
/.well-known/vercel/* | <your-subdomain>.mintlify.dev | Sin caché |
/.well-known/skills/* (opcional) | <your-subdomain>.mintlify.dev/docs | Sin caché |
/.well-known/agent-skills/* (opcional) | <your-subdomain>.mintlify.dev/docs | Sin caché |
/skill.md (opcional) | <your-subdomain>.mintlify.dev/docs | Sin caché |
/llms.txt (opcional) | <your-subdomain>.mintlify.dev/docs | Sin caché |
/llms-full.txt (opcional) | <your-subdomain>.mintlify.dev/docs | Sin caché |
/.well-known/skills/*, /.well-known/agent-skills/*, /skill.md, /llms.txt y /llms-full.txt son opcionales. Inclúyelas solo si quieres servir archivos de IA en rutas raíz como your-domain.com/llms.txt en lugar de en tu subruta de documentación, como your-domain.com/docs/llms.txt.
Configuración obligatoria de encabezados
Configura tu proxy inverso con estos requisitos de encabezados:
- Origin: Contiene el subdomain de destino
<your-subdomain>.mintlify.dev
- 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.
Ejemplo de configuración de Nginx
server {
listen 80;
server_name <your-domain>.com;
# Rutas de verificación de Vercel
location ~ ^/\.well-known/vercel/ {
proxy_pass https://<your-subdomain>.mintlify.dev;
proxy_set_header Origin <your-subdomain>.mintlify.dev;
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";
}
# Rutas de habilidades de IA
location ^~ /.well-known/skills/ {
proxy_pass https://<your-subdomain>.mintlify.dev/docs;
proxy_set_header Origin <your-subdomain>.mintlify.dev;
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.dev/docs;
proxy_set_header Origin <your-subdomain>.mintlify.dev;
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";
}
# Manifiesto de habilidad (opcional)
location = /skill.md {
proxy_pass https://<your-subdomain>.mintlify.dev/docs;
proxy_set_header Origin <your-subdomain>.mintlify.dev;
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";
}
# Archivos de índice LLM (opcional)
location = /llms.txt {
proxy_pass https://<your-subdomain>.mintlify.dev/docs;
proxy_set_header Origin <your-subdomain>.mintlify.dev;
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.dev/docs;
proxy_set_header Origin <your-subdomain>.mintlify.dev;
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";
}
# Raíz de la documentación
location = /docs {
proxy_pass https://<your-subdomain>.mintlify.dev/docs;
proxy_set_header Origin <your-subdomain>.mintlify.dev;
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";
}
# Todas las rutas de la documentación
location /docs/ {
proxy_pass https://<your-subdomain>.mintlify.dev/docs/;
proxy_set_header Origin <your-subdomain>.mintlify.dev;
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";
}
}
/docs (como /help o /resources), utiliza la siguiente configuración de enrutamiento.
Encamina estas rutas a tu subdomain de Mintlify con las políticas de caché especificadas:
| Ruta | Destino | Caché |
|---|
/.well-known/vercel/* | <your-subdomain>.mintlify.app | Sin caché |
/.well-known/skills/* | <your-subdomain>.mintlify.app | Sin caché |
/.well-known/agent-skills/* | <your-subdomain>.mintlify.app | Sin caché |
/skill.md | <your-subdomain>.mintlify.app | Sin caché |
/llms.txt | <your-subdomain>.mintlify.app | Sin caché |
/llms-full.txt | <your-subdomain>.mintlify.app | Sin caché |
/mintlify-assets/_next/static/* | <your-subdomain>.mintlify.app | Caché habilitada |
/_mintlify/* | <your-subdomain>.mintlify.app | Sin caché |
/* | <your-subdomain>.mintlify.app | Sin caché |
/ | <your-subdomain>.mintlify.app | Sin caché |
Mintlify sirve llms.txt, llms-full.txt y skill.md en la ruta raíz. Si tu documentación se encuentra en una subruta (como /help), también puedes servir estos archivos desde esa subruta (por ejemplo, /help/llms.txt). Para ello, agrega bloques location que reescriban la subruta a la ruta raíz. Consulta el ejemplo de nginx a continuación para ambos patrones.
- Origin: Contiene el subdomain de destino
<your-subdomain>.mintlify.app
- 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
Ejemplo de configuración de Nginx
server {
listen 80;
server_name <your-domain>.com;
# Vercel verification paths
location ~ ^/\.well-known/vercel/ {
proxy_pass https://<your-subdomain>.mintlify.app;
proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
proxy_set_header User-Agent $http_user_agent;
# Deshabilitar caché para rutas de verificación
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# AI skills paths
location ^~ /.well-known/skills/ {
proxy_pass https://<your-subdomain>.mintlify.app;
proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
proxy_set_header User-Agent $http_user_agent;
# Deshabilitar caché para rutas de verificación
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.app;
proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
proxy_set_header User-Agent $http_user_agent;
# Deshabilitar caché para rutas agent-skills
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# Skill manifest
location = /skill.md {
proxy_pass https://<your-subdomain>.mintlify.app;
proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
proxy_set_header User-Agent $http_user_agent;
# Disable caching for skill manifest
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# Archivos de índice LLM
location = /llms.txt {
proxy_pass https://<your-subdomain>.mintlify.app;
proxy_set_header Origin <your-subdomain>.mintlify.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-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.app;
proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
proxy_set_header User-Agent $http_user_agent;
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# Opcional: Servir archivos de IA en tu subruta con reescritura de rutas.
# Reemplaza "/help" con tu subruta. Estos bloques reescriben la
# subruta para que Mintlify reciba la ruta raíz que espera.
#
# location = /help/llms.txt {
# proxy_pass https://<your-subdomain>.mintlify.app/llms.txt;
# proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
# proxy_set_header User-Agent $http_user_agent;
# add_header Cache-Control "no-cache, no-store, must-revalidate";
# }
#
# location = /help/llms-full.txt {
# proxy_pass https://<your-subdomain>.mintlify.app/llms-full.txt;
# proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
# proxy_set_header User-Agent $http_user_agent;
# add_header Cache-Control "no-cache, no-store, must-revalidate";
# }
#
# location = /help/skill.md {
# proxy_pass https://<your-subdomain>.mintlify.app/skill.md;
# proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
# proxy_set_header User-Agent $http_user_agent;
# add_header Cache-Control "no-cache, no-store, must-revalidate";
# }
# Static assets with caching
location ~ ^/mintlify-assets/_next/static/ {
proxy_pass https://<your-subdomain>.mintlify.app;
proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
proxy_set_header User-Agent $http_user_agent;
# Enable caching for static assets
add_header Cache-Control "public, max-age=86400";
}
# Mintlify-specific paths
location ~ ^/_mintlify/ {
proxy_pass https://<your-subdomain>.mintlify.app;
proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
proxy_set_header User-Agent $http_user_agent;
# Disable caching for Mintlify paths
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# Root path
location = / {
proxy_pass https://<your-subdomain>.mintlify.app;
proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
proxy_set_header User-Agent $http_user_agent;
# Disable caching for dynamic content
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
# All other documentation paths
location / {
proxy_pass https://<your-subdomain>.mintlify.app;
proxy_set_header Origin <your-subdomain>.mintlify.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-Proto $scheme;
proxy_set_header User-Agent $http_user_agent;
# Disable caching for dynamic content
add_header Cache-Control "no-cache, no-store, must-revalidate";
}
}
/docs activado en tu dashboard, pero tu proxy inverso apunta a mintlify.app en lugar de mintlify.dev.
Solución: Actualiza la configuración de tu proxy inverso para que apunte a <your-subdomain>.mintlify.dev en lugar de <your-subdomain>.mintlify.app.
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
Origin en tu subdominio de Mintlify (mintlify.dev para una subruta /docs o mintlify.app para una subruta diferente)
Síntomas: Cargas de página lentas y desplazamientos de diseño.
Causa: Configuración de caché incorrecta.
Solución: Para configuraciones personalizadas de subrutas, habilita la caché solo para las rutas /mintlify-assets/_next/static/*. La configuración de la subruta /docs gestiona la caché automáticamente.
