Proxy inverso - Mintlify

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

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.

Hospedar en la subruta `/docs`

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 docs como 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.

Configuración de enrutamiento

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.

Configuración obligatoria de encabezados

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.

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.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";
    }
}

Subruta personalizada

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, /docs o /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.

Resolución de problemas

Los cambios no aparecen

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.

Error 404

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 con tu subdominio de Mintlify (<your-subdomain>.mintlify.site)

Problemas de rendimiento

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.

​Configura tu ruta base

​Hospedar en la subruta /docs

​Configuración de enrutamiento

​Configuración obligatoria de encabezados

​Ejemplo de configuración de nginx

​Subruta personalizada

​Resolución de problemas

​Los cambios no aparecen

​Error 404

​Problemas de rendimiento

Configura tu ruta base

Hospedar en la subruta `/docs`

Configuración de enrutamiento

Configuración obligatoria de encabezados

Ejemplo de configuración de nginx

Subruta personalizada

Resolución de problemas

Los cambios no aparecen

Error 404

Problemas de rendimiento