Proxy inverso

Configura un proxy inverso personalizado para publicar tu documentación.

Las configuraciones de proxy inverso solo están disponibles en los planes Enterprise.

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 domain, el aprovisionamiento de certificados SSL, los flujos de Autenticación, el rendimiento y el seguimiento de Analytics.

​

Elige tu enfoque de implementación

Mintlify admite dos configuraciones de proxy inverso en función de tus requisitos de subruta.

• 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

Usa esta configuración cuando quieras servir la documentación en la ruta /docs de tu dominio.

Antes de configurar tu proxy inverso:

1. Navega a Configuración de dominio personalizado en tu dashboard.
2. Activa la opción Host at /docs.
3. 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

Encamina (proxy) estas rutas a tu subdomain de Mintlify:

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é
/skill.md (opcional)	<your-subdomain>.mintlify.dev/docs	Sin caché

Las rutas /.well-known/skills/* y /skill.md son opcionales. Inclúyelas solo si quieres servir archivos de habilidades de IA en rutas raíz como your-domain.com/skills.md en lugar de en tu subruta de documentación, como your-domain.com/docs/skills.md.

​

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

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

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

​

Subruta personalizada

Cuando necesites una subruta distinta de /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é
/skill.md	<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é

​

Configuración obligatoria de encabezados

Configura tu proxy inverso con estos requisitos de encabezados:

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

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

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

​

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: Tienes Host at /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.

​

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 en tu subdominio de Mintlify (mintlify.dev para una subruta /docs o mintlify.app para una subruta diferente)

​

Problemas de rendimiento

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.