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 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: 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 cualquier subruta que elijas. Este enfoque requiere reglas de enrutamiento adicionales.

En ambas 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:

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

Encamina (proxy) estas rutas a tu subdomain 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`	Sin caché
`/.well-known/skills/*` (opcional)	`<your-subdomain>.mintlify.site/docs`	Sin caché
`/.well-known/agent-skills/*` (opcional)	`<your-subdomain>.mintlify.site/docs`	Sin caché
`/skill.md` (opcional)	`<your-subdomain>.mintlify.site/docs`	Sin caché
`/llms.txt` (opcional)	`<your-subdomain>.mintlify.site/docs`	Sin caché
`/llms-full.txt` (opcional)	`<your-subdomain>.mintlify.site/docs`	Sin caché

Las rutas /.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.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;

    # Rutas de verificación de Vercel
    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";
    }

    # Rutas de habilidades de IA
    location ^~ /.well-known/skills/ {
        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";
    }

    # Agent-skills discovery paths
    location ^~ /.well-known/agent-skills/ {
        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";
    }

    # Manifiesto de habilidad (opcional)
    location = /skill.md {
        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";
    }

    # Archivos de índice LLM (opcional)
    location = /llms.txt {
        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";
    }

    location = /llms-full.txt {
        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";
    }

    # Raíz de la documentación
    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";
    }

    # Todas las rutas de la documentación
    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

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

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.site`	Sin caché
`/.well-known/skills/*`	`<your-subdomain>.mintlify.site`	Sin caché
`/.well-known/agent-skills/*`	`<your-subdomain>.mintlify.site`	Sin caché
`/skill.md`	`<your-subdomain>.mintlify.site`	Sin caché
`/llms.txt`	`<your-subdomain>.mintlify.site`	Sin caché
`/llms-full.txt`	`<your-subdomain>.mintlify.site`	Sin caché
`/mintlify-assets/_next/static/*`	`<your-subdomain>.mintlify.site`	Caché habilitada
`/_mintlify/*`	`<your-subdomain>.mintlify.site`	Sin caché
`/*`	`<your-subdomain>.mintlify.site`	Sin caché
`/`	`<your-subdomain>.mintlify.site`	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.

Configuración obligatoria de encabezados

Configura tu proxy inverso con estos requisitos de encabezados:

Origin: Contiene el subdomain 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;

        # 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.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;

        # 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.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;

        # 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.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;

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

    location = /llms-full.txt {
        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";
    }

    # 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.site/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 = /help/llms-full.txt {
    #     proxy_pass https://<your-subdomain>.mintlify.site/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";
    # }
    #
    # location = /help/skill.md {
    #     proxy_pass https://<your-subdomain>.mintlify.site/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";
    # }

    # Static assets with caching
    location ~ ^/mintlify-assets/_next/static/ {
        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;

        # Enable caching for static assets
        add_header Cache-Control "public, max-age=86400";
    }

    # Mintlify-specific paths
    location ~ ^/_mintlify/ {
        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;

        # Disable caching for Mintlify paths
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Root path
    location = / {
        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;

        # 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.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;

        # 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: 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 en 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: 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.

​Elige tu enfoque de implementación

​Hospedar en la subruta /docs

​Configuración de enrutamiento

​Configuración obligatoria de encabezados

​Ejemplo de configuración de Nginx

​Subruta personalizada

​Configuración obligatoria de encabezados

​Ejemplo de configuración de Nginx

​Resolución de problemas

​Los cambios no aparecen

​Error 404

​Problemas de rendimiento

Elige tu enfoque de implementación

Hospedar en la subruta `/docs`

Configuración de enrutamiento

Configuración obligatoria de encabezados

Ejemplo de configuración de Nginx

Subruta personalizada

Configuración obligatoria de encabezados

Ejemplo de configuración de Nginx

Resolución de problemas

Los cambios no aparecen

Error 404

Problemas de rendimiento