Proxy inverse

Configurer un proxy inverse personnalisé pour diffuser votre documentation.

Les configurations de proxy inverse ne sont prises en charge que pour les offres Enterprise.

Pour diffuser votre documentation via un proxy inverse personnalisé, vous devez configurer des règles de routage, des stratégies de mise en cache et la transmission des en-têtes.

Lorsque vous mettez en place un proxy inverse, surveillez les problèmes potentiels liés à la vérification du domain, à l’émission des certificats SSL, aux parcours d’authentification, aux performances et au suivi Analytics.

​

Choisissez votre approche de déploiement

Mintlify prend en charge deux configurations de proxy inverse en fonction de vos exigences en matière de sous-chemin.

• Héberger sur /docs : utilisez mintlify.dev comme cible du proxy. Activez le bouton Héberger sur /docs sur la page Configuration du domaine personnalisé de votre Dashboard. Il s’agit d’une configuration plus simple avec moins de routes.
• Sous-chemin personnalisé : utilisez mintlify.app comme cible du proxy. Cette approche prend en charge n’importe quel sous-chemin et nécessite des règles de routage supplémentaires.

​

Héberger sur le sous-chemin /docs

Utilisez cette configuration lorsque vous souhaitez servir la documentation sur le chemin /docs de votre domaine.

Avant de configurer votre reverse proxy :

1. Accédez à Custom domain setup dans votre Dashboard.
2. Activez l’option Host at /docs.
3. Saisissez votre domaine et sélectionnez Add domain.

Lorsque vous activez Host at /docs, l’URL canonique de votre documentation devient <your-subdomain>.mintlify.dev. L’invalidation du cache s’arrête sur mintlify.app, et vous devez configurer le proxy vers mintlify.dev pour que les mises à jour apparaissent.

​

Configuration du routage

Redirigez ces chemins via un proxy vers votre sous-domaine Mintlify :

Path	Destination	Caching
/docs	<your-subdomain>.mintlify.dev/docs	No cache
/docs/*	<your-subdomain>.mintlify.dev/docs	No cache
/.well-known/vercel/*	<your-subdomain>.mintlify.dev	No cache
/.well-known/skills/* (optional)	<your-subdomain>.mintlify.dev/docs	No cache
/skill.md (optional)	<your-subdomain>.mintlify.dev/docs	No cache

Les routes /.well-known/skills/* et /skill.md sont facultatives. Ne les incluez que si vous souhaitez servir des fichiers de compétences IA sur des chemins à la racine comme your-domain.com/skills.md plutôt que sous votre sous-chemin de documentation, par exemple your-domain.com/docs/skills.md.

​

Configuration d’en-têtes requise

Configurez votre reverse proxy avec les en-têtes suivants :

• Origin : contient le sous-domaine cible <your-subdomain>.mintlify.dev
• X-Forwarded-For : conserve les informations d’adresse IP du client
• X-Forwarded-Proto : conserve le protocole d’origine (http/https)
• X-Real-IP : transmet la véritable adresse IP du client
• User-Agent : transmet l’agent utilisateur

Assurez-vous que l’en-tête Host n’est pas transmis.

​

Exemple de configuration Nginx

server {
    listen 80;
    server_name <your-domain>.com;

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

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

    # Manifeste de compétence (facultatif)
    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";
    }

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

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

​

Sous-chemin personnalisé

Lorsque vous avez besoin d’un sous-chemin autre que /docs (comme /help ou /resources), utilisez la configuration de routage suivante.

Redirigez ces chemins vers votre sous-domaine Mintlify avec les politiques de mise en cache indiquées :

Chemin	Destination	Mise en cache
/.well-known/vercel/*	<your-subdomain>.mintlify.app	Pas de cache
/.well-known/skills/*	<your-subdomain>.mintlify.app	Pas de cache
/skill.md	<your-subdomain>.mintlify.app	Pas de cache
/mintlify-assets/_next/static/*	<your-subdomain>.mintlify.app	Cache activé
/_mintlify/*	<your-subdomain>.mintlify.app	Pas de cache
/*	<your-subdomain>.mintlify.app	Pas de cache
/	<your-subdomain>.mintlify.app	Pas de cache

​

Configuration d’en-têtes requise

Configurez votre reverse proxy avec les en-têtes suivants :

• Origin : contient le sous-domaine cible <your-subdomain>.mintlify.app
• X-Forwarded-For : conserve les informations d’adresse IP du client
• X-Forwarded-Proto : conserve le protocole d’origine (HTTP/HTTPS)
• X-Real-IP : transmet la véritable adresse IP du client
• User-Agent : transmet l’agent utilisateur

Assurez-vous que l’en-tête Host n’est pas transmis

​

Exemple de configuration 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;

        # Désactiver la mise en cache pour les chemins de vérification
        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;

        # Désactiver la mise en cache pour les chemins de vérification
        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";
    }
}

​

Résolution des problèmes

​

Les modifications n’apparaissent pas

Symptômes : Vous publiez des mises à jour de la documentation, mais les modifications n’apparaissent pas sur votre site.

Cause : Vous avez activé Host at /docs dans votre Dashboard, mais votre proxy inverse pointe vers mintlify.app au lieu de mintlify.dev.

Solution : Mettez à jour la configuration de votre proxy inverse pour qu’il pointe vers <your-subdomain>.mintlify.dev au lieu de <your-subdomain>.mintlify.app.

​

Erreur 404

Symptômes : La documentation se charge, mais certaines fonctionnalités ne fonctionnent pas. Les appels à l’API échouent.

Cause : Le proxy inverse transmet l’en-tête Host ou l’en-tête Origin est manquant.

Solution :

• Supprimer le transfert de l’en-tête Host
• Définir l’en-tête Origin sur votre sous-domaine Mintlify (mintlify.dev pour un sous-chemin /docs ou mintlify.app pour un autre sous-chemin)

​

Problèmes de performances

Symptômes : temps de chargement lents et décalages de mise en page.

Cause : configuration de la mise en cache incorrecte.

Solution : pour les configurations de sous-chemins personnalisées, activez la mise en cache uniquement pour les chemins /mintlify-assets/_next/static/*. La configuration du sous-chemin /docs gère automatiquement la mise en cache.