mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
3b313d0fd5
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
316 lines
13 KiB
Plaintext
316 lines
13 KiB
Plaintext
---
|
||
title: "Proxy inverse"
|
||
description: "Configurer un proxy inverse personnalisé pour diffuser votre documentation."
|
||
keywords: ["configuration de proxy inverse", "nginx", "routage du proxy", "transmission des en-têtes"]
|
||
---
|
||
|
||
<Note>
|
||
Les configurations de proxy inverse ne sont prises en charge que pour les [offres Enterprise](https://mintlify.com/pricing?ref=reverse-proxy).
|
||
</Note>
|
||
|
||
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.
|
||
|
||
<div id="choose-your-deployment-approach">
|
||
## Choisissez votre approche de déploiement
|
||
</div>
|
||
|
||
Mintlify prend en charge deux configurations de reverse proxy en fonction de vos besoins en matière de sous-chemins.
|
||
|
||
- **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é](https://dashboard.mintlify.com/settings/deployment/custom-domain) 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.
|
||
|
||
<div id="host-at-docs-subpath">
|
||
## Héberger sur le sous-chemin `/docs`
|
||
</div>
|
||
|
||
Utilisez cette configuration lorsque vous souhaitez servir la documentation sur le chemin `/docs` de votre domain.
|
||
|
||
Avant de configurer votre proxy inverse :
|
||
|
||
1. Accédez à [Custom domain setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) dans votre Dashboard.
|
||
2. Activez l’option **Host at `/docs`**.
|
||
3. Saisissez votre domain et sélectionnez **Add domain**.
|
||
|
||
<Warning>
|
||
L’activation de **Host at `/docs`** arrête l’invalidation du cache sur `mintlify.app`. Vous devez utiliser un proxy vers `mintlify.dev` pour que les mises à jour apparaissent.
|
||
</Warning>
|
||
|
||
<div id="routing-configuration">
|
||
### Configuration du routage
|
||
</div>
|
||
|
||
Redirigez ces chemins 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. Incluez-les uniquement si vous souhaitez servir des fichiers de compétences IA à la racine, via des chemins comme `your-domain.com/skills.md`, plutôt que sous votre sous-chemin de documentation, comme `your-domain.com/docs/skills.md`.
|
||
|
||
<div id="required-header-configuration">
|
||
### Configuration d’en-têtes requise
|
||
</div>
|
||
|
||
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
|
||
|
||
<Warning>
|
||
Assurez-vous que l’en-tête `Host` n’est pas transmis.
|
||
</Warning>
|
||
|
||
<div id="example-nginx-configuration">
|
||
### Exemple de configuration Nginx
|
||
</div>
|
||
|
||
```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";
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
<div id="custom-subpath">
|
||
## Sous-chemin personnalisé
|
||
</div>
|
||
|
||
Lorsque vous avez besoin d’un sous-chemin différent de `/docs` (par exemple `/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 |
|
||
|
||
<div id="required-header-configuration">
|
||
### Configuration d’en-têtes requise
|
||
</div>
|
||
|
||
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
|
||
|
||
<Warning>
|
||
Assurez-vous que l’en-tête `Host` n’est pas transmis
|
||
</Warning>
|
||
|
||
<div id="example-nginx-configuration">
|
||
### Exemple de configuration Nginx
|
||
</div>
|
||
|
||
```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;
|
||
|
||
# Disable caching for verification paths
|
||
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;
|
||
|
||
# Disable caching for verification paths
|
||
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";
|
||
}
|
||
|
||
# Ressources statiques avec mise en cache
|
||
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;
|
||
|
||
# Activer la mise en cache pour les ressources statiques
|
||
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";
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
<div id="troubleshooting">
|
||
## Résolution des problèmes
|
||
</div>
|
||
|
||
<div id="changes-not-appearing">
|
||
### Les modifications n’apparaissent pas
|
||
</div>
|
||
|
||
**Symptômes** : Vous publiez des mises à jour de la documentation, mais les modifications n’apparaissent pas sur votre site.
|
||
|
||
**Cause** : Vous avez **Host at `/docs`** activé dans votre Dashboard, mais votre reverse proxy pointe vers `mintlify.app` au lieu de `mintlify.dev`.
|
||
|
||
**Solution** : Mettez à jour la configuration de votre reverse proxy pour qu’il pointe vers `<your-subdomain>.mintlify.dev` au lieu de `<your-subdomain>.mintlify.app`.
|
||
|
||
<div id="404-error">
|
||
### Erreur 404
|
||
</div>
|
||
|
||
**Symptômes :** La documentation se charge, mais certaines fonctionnalités ne fonctionnent pas. Les appels à l’API échouent.
|
||
|
||
**Cause :** Le reverse proxy 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 sous-chemin différent)
|
||
|
||
<div id="performance-issues">
|
||
### Problèmes de performances
|
||
</div>
|
||
|
||
**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 avec sous-chemins personnalisés, 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. |