diff --git a/es.json b/es.json index 5353ac6dc..7f8a8c8fc 100644 --- a/es.json +++ b/es.json @@ -199,7 +199,8 @@ "es/deploy/github", "es/deploy/ghes", "es/deploy/gitlab", - "es/deploy/gitlab-self-hosted" + "es/deploy/gitlab-self-hosted", + "es/deploy/self-host" ] }, { diff --git a/es/deploy/self-host.mdx b/es/deploy/self-host.mdx new file mode 100644 index 000000000..9118b70ee --- /dev/null +++ b/es/deploy/self-host.mdx @@ -0,0 +1,261 @@ +--- +title: "Autoalojamiento" +description: "Ejecuta Mintlify dentro de tu propia nube o entorno on-premises, en AWS o en cualquier plataforma de Kubernetes, incluidas Azure, Google Cloud, Oracle Cloud y OpenShift." +keywords: ["self-host", "self-hosted", "on-prem", "deploy", "AWS", "CDK", "Helm", "Kubernetes", "OpenShift", "air gap", "enterprise"] +--- + + + El autoalojamiento requiere un [plan Enterprise](https://mintlify.com/pricing?ref=self-host). Ponte en contacto con tu equipo de cuenta para dimensionar un despliegue. + + +El autoalojamiento ejecuta Mintlify dentro de tu propia cuenta en la nube o centro de datos, de modo que tu contenido, tu pipeline de compilación, las analíticas y los logs se mantienen dentro de los límites de tu red. Está diseñado para equipos con requisitos de residencia de datos, cumplimiento normativo o air-gap que un despliegue alojado en la nube no puede satisfacer. + +Cada despliegue autoalojado es un compromiso definido con tu equipo de cuenta, no una instalación autoservicio. Esta página describe qué aprovisionas, cómo se ejecuta el despliegue y las contrapartidas frente al alojamiento en la nube para que puedas evaluar el autoalojamiento antes de comprometerte con él. + +
+ ## Plataformas compatibles +
+ +| Plataforma | Método | +| --- | --- | +| Amazon Web Services | Aplicación de AWS Cloud Development Kit (CDK) | +| Microsoft Azure | Helm chart en Azure Kubernetes Service (AKS) | +| Google Cloud | Helm chart en Google Kubernetes Engine (GKE) | +| Oracle Cloud | Helm chart en Oracle Container Engine for Kubernetes (OKE) | +| Red Hat OpenShift | Helm chart | +| Cualquier Kubernetes | Helm chart | + +
+ ## Cómo se compara el autoalojamiento con el alojamiento en la nube +
+ +La redacción funciona igual en ambos modelos de alojamiento. Tu equipo mantiene el contenido con el editor o con su flujo de trabajo de Git, y cada cambio pasa por el proceso de revisión de tu repositorio. Lo que cambia es quién opera la plataforma y dónde residen los datos. + +| Área | Alojado en la nube | Autoalojado | +| --- | --- | --- | +| Tiempo hasta el lanzamiento | El mismo día | Compromiso definido, normalmente semanas | +| Infraestructura | Mintlify opera todo | Tú operas el clúster, la red y los almacenes de datos. Mintlify entrega versiones con guías de actualización y da soporte a la capa de aplicación | +| Actualizaciones de la plataforma | Continuas y automáticas | Versiones que tú revisas y despliegas en tu propio calendario | +| Frontera de datos | Se procesan en la nube de Mintlify | El contenido, las compilaciones, las analíticas y los logs permanecen dentro de tu red, sin egreso a terceros | +| Funciones de IA | Activadas por defecto | Se entregan desactivadas hasta que tu equipo de seguridad o de gobernanza de IA las aprueba. Pueden ejecutarse contra tu propio endpoint de modelo, tu propia clave de API o la nube de Mintlify | +| Integraciones | Catálogo completo | Las integraciones que dependen de servicios de la nube de Mintlify no están disponibles | +| Supervisión | Gestionada por Mintlify | Conectas tu propia stack de observabilidad | + +Los despliegues autoalojados suelen empezar acotados y ampliarse. Un camino habitual es empezar con documentación pública y luego añadir contenido autenticado, el editor web y las funciones de IA a medida que completas las revisiones de seguridad. + +
+ ## Funciones +
+ +Todo lo esencial para redactar, compilar y servir documentación se incluye en un despliegue autoalojado. + +| Función | Disponibilidad | Notas | +| --- | :---: | --- | +| Sitio de documentación | | Renderizado completo, componentes y personalización de tema | +| Editor web | | Redacción desde el navegador | +| Flujo de trabajo respaldado por Git | | GitHub, GitHub Enterprise Server, GitLab incluida la versión autogestionada, Bitbucket o una API proxy de propiedad interna | +| Búsqueda | | Se ejecuta dentro de tu despliegue. El índice se reconstruye al publicar | +| Contenido autenticado | | Control de acceso a través de tu proveedor de identidad | +| SSO del dashboard | | OIDC o SAML | +| Analíticas | | Se recopilan y almacenan dentro de tu red | +| Widgets de analítica y soporte de terceros | | Se configuran con tus propias claves y se sirven desde el sitio de documentación | +| Exportación estática | | Paquetes autocontenidos para servir en entornos air-gapped | +| Versiones y rollback | | Cada versión fija versiones de imagen. Vuelve atrás redesplegando la versión anterior | +| Asistente y agente de IA | Opcional | Se entregan desactivados. Se ejecutan contra tu propio endpoint de modelo, tu propia clave de API o la nube de Mintlify | + +Solo las superficies más pequeñas que dependen de servicios operados por Mintlify están limitadas a la nube: la aplicación de Slack, los conectores de terceros para automatizaciones del agente y las integraciones de generación de SDK. + +
+ ## Arquitectura +
+ +Un despliegue autoalojado es un conjunto de servicios con dependencias claras. Aprovisiona primero los almacenes de datos, luego los servicios que dependen de ellos y por último el borde. + +```mermaid +flowchart TD + U[Users] --> CDN[CDN and WAF] + CDN --> ING[Load balancer or ingress] + ING --> WEB[Docs site] + ING --> API[Dashboard and API] + API --> BUILD[Build workers] + BUILD --> GIT[Git source] + WEB --> OBJ[(Object storage)] + BUILD --> OBJ + API --> MONGO[(MongoDB)] + API --> PG[(PostgreSQL)] + API --> REDIS[(Redis)] + API --> SEARCH[Search and indexing] + API --> IDP[Identity provider] + API -. optional .-> AI[AI assistant services] +``` + +| Recurso | Propósito | Requerido | +| --- | --- | :---: | +| Balanceador de carga o ingress | Terminación TLS y enrutamiento | | +| Sitio de documentación | Sirve la documentación renderizada | | +| Dashboard y API | Administración, autenticación y orquestación de compilaciones | | +| Workers de compilación | Compilan y publican los sitios de documentación | | +| MongoDB | Almacén de contenido | | +| PostgreSQL | Metadatos de despliegue y de usuario | | +| Redis | Cola de compilación y caché | | +| Almacenamiento de objetos | Paquetes de sitios compilados y exportaciones estáticas | | +| Búsqueda e indexación | Búsqueda de la documentación. El índice se reconstruye al publicar | | +| Proveedor de identidad | SSO OIDC o SAML para el dashboard y el contenido autenticado | | +| Servicios de asistente de IA | Funciones de asistente y agente | Opcional | + +La fuente de tu documentación puede ser GitHub, GitHub Enterprise Server, GitLab (incluida la versión autogestionada) o Bitbucket. + +Si tu organización no puede conceder credenciales de repositorio a un servicio de terceros, puedes anteponer a tu hosting de Git una API proxy de propiedad interna; los entornos totalmente air-gapped utilizan la [exportación estática](/es/api/static-export/overview) sin ninguna conexión a Git. + +
+ ### Dimensionamiento +
+ +Como punto de partida, un despliegue de producción se ejecuta con aproximadamente 45 a 60 vCPU, 160 a 220 GB de memoria y alrededor de 1 TB de almacenamiento en estado sólido repartido entre los servicios, mientras que los entornos no productivos utilizan aproximadamente la mitad. Tu equipo de cuenta dimensiona el despliegue contigo según el número de páginas, el tráfico y las funciones que actives. + +
+ ## Configura tu plataforma +
+ + + + Los despliegues en AWS usan una aplicación de AWS CDK que aprovisiona y actualiza toda la stack en tu cuenta. La aplicación de CDK fija las imágenes de contenedor a versiones concretas, por lo que cada despliegue es reproducible y revisable. + + ### Qué aportas tú + + | Componente | Requisito | Notas | + | --- | --- | --- | + | Cómputo | Clúster de Amazon ECS | Ejecuta los servicios de Mintlify | + | Almacén de contenido | Amazon DocumentDB | Compatible con MongoDB | + | Almacén de metadatos | Amazon RDS for PostgreSQL | Metadatos de despliegue y de usuario | + | Caché y cola | Amazon ElastiCache for Redis | Cola de compilación y caché | + | Almacenamiento de objetos | Amazon S3 | Paquetes de sitios compilados y exportaciones estáticas | + | CDN | Amazon CloudFront | Sirve el sitio de documentación en el borde | + | Red | VPC con subredes públicas y privadas, Application Load Balancer | Aísla las cargas de trabajo | + | TLS y DNS | AWS Certificate Manager, Amazon Route 53 | HTTPS y enrutamiento para tu dominio | + | Secretos | AWS Secrets Manager | Credenciales de base de datos y secretos de firma | + | Identidad | Proveedor OIDC o SAML | SSO del dashboard | + + ### Configuración + + + + Tu equipo de cuenta revisa la topología de tu red, tu hosting de Git, tu proveedor de identidad y tus requisitos de cumplimiento y, después, entrega la aplicación de CDK y el acceso a imágenes de contenedor versionadas. + + + Configura tu dominio, certificado y red en el contexto de CDK, revisa el change set y despliega. + + ```bash + cdk diff + cdk deploy --all + ``` + + + Concede al despliegue acceso a tus repositorios de documentación y conecta tu proveedor de identidad. + + + Verifica las compilaciones y la búsqueda en tu dominio de staging y, a continuación, apunta el DNS de producción al despliegue. + + + + + + Los despliegues en Kubernetes usan el Helm chart enterprise de Mintlify y se ejecutan en cualquier clúster de Kubernetes certificado. El mismo chart cubre Kubernetes gestionado en cualquier nube y clústeres on-premises: + + - **Azure**: AKS, con Microsoft Entra ID para SSO y servicios de datos gestionados de Azure. + - **Google Cloud**: GKE, con Cloud SQL, Memorystore y Cloud Storage. + - **Oracle Cloud**: OKE, con bases de datos gestionadas de OCI y OCI Object Storage. + - **OpenShift**: incluye contextos de seguridad compatibles con OpenShift y usa Routes para el ingress. + + ### Qué aportas tú + + | Componente | Requisito | Notas | + | --- | --- | --- | + | Clúster | Clúster de Kubernetes u OpenShift | Aloja el release de Helm | + | Almacén de contenido | MongoDB | Gestionado o dentro del clúster | + | Almacén de metadatos | PostgreSQL | Gestionado o dentro del clúster | + | Caché y cola | Redis | Cola de compilación y caché | + | Almacenamiento de objetos | Bucket compatible con S3 | Paquetes de sitios compilados y exportaciones estáticas | + | Ingress | Controlador de ingress o Route de OpenShift con TLS | Sirve HTTPS. Se recomienda un WAF por delante | + | Registro | Registro de contenedores privado | Aloja las imágenes entregadas | + | Identidad | Proveedor OIDC o SAML | SSO del dashboard | + + ### Configuración + + + + Tu equipo de cuenta revisa tu clúster, tu hosting de Git, tu proveedor de identidad y tus requisitos de cumplimiento y, después, entrega el Helm chart, una plantilla de values e imágenes de contenedor versionadas para tu registro. + + + Levanta MongoDB, PostgreSQL, Redis y almacenamiento de objetos, gestionados por tu proveedor de nube o dentro del clúster. + + + Apunta el archivo de values a tus almacenes de datos, ingress y registro, y luego instala el release. + + ```bash + helm upgrade --install mintlify ./mintlify-enterprise \ + --namespace mintlify --create-namespace -f values.yaml + ``` + + + Concede al despliegue acceso a tus repositorios de documentación, conecta tu proveedor de identidad, verifica en staging y apunta el DNS de producción al despliegue. + + + + + +
+ ## Actualizaciones +
+ +Las actualizaciones de plataforma y las actualizaciones de contenido evolucionan de forma independiente. Tú controlas cuándo cambia la plataforma, y tu documentación se mantiene al día por sí sola. + +
+ ### Actualizaciones de la plataforma +
+ +Mintlify entrega versiones con guías de actualización y notas de la versión a través de tu equipo de cuenta. Cada versión fija versiones concretas de imagen, de modo que puedes probar un release en un entorno no productivo antes de desplegarlo y volver a la versión anterior si es necesario. + + + +```bash AWS (CDK) +# revisa el change set del nuevo release y despliégalo +cdk diff +cdk deploy --all +``` + +```bash Kubernetes (Helm) +# actualiza a un release entregado o vuelve atrás +helm upgrade mintlify ./mintlify-enterprise \ + --namespace mintlify -f values.yaml +helm rollback mintlify +``` + + + +Las actualizaciones se despliegan sin tiempo de inactividad. Se levantan nuevas tareas o pods, superan las comprobaciones de salud y reemplazan a los anteriores. + +
+ ### Actualizaciones de contenido +
+ +El contenido fluye a través de tu fuente de Git, no a través de los releases de plataforma. Cuando haces push a tu repositorio de documentación, los workers de compilación reconstruyen el sitio y lo publican automáticamente en el almacenamiento de objetos. Los cambios de contenido nunca requieren un despliegue de plataforma. + +
+ ## Despliegues air-gapped +
+ +Los entornos sin ruta para webhooks de Git sirven la documentación como [paquetes de exportación estática](/es/api/static-export/overview). Se publican compilaciones autocontenidas de tu sitio en el almacenamiento de objetos y se sirven a través de tu CDN. Regenera el paquete cuando cambie el contenido, o automatiza el ciclo con una GitHub Action. Las funciones de IA que requieren acceso de red saliente se desactivan en despliegues air-gapped. + +
+ ## Próximos pasos +
+ + + + Dimensiona un despliegue autoalojado en tu plataforma y planifica tu lanzamiento. + + + Genera paquetes autocontenidos de tu documentación para servirlos en entornos air-gapped. + + diff --git a/fr.json b/fr.json index 362f9091c..7f2852a6a 100644 --- a/fr.json +++ b/fr.json @@ -199,7 +199,8 @@ "fr/deploy/github", "fr/deploy/ghes", "fr/deploy/gitlab", - "fr/deploy/gitlab-self-hosted" + "fr/deploy/gitlab-self-hosted", + "fr/deploy/self-host" ] }, { diff --git a/fr/deploy/self-host.mdx b/fr/deploy/self-host.mdx new file mode 100644 index 000000000..db5be244c --- /dev/null +++ b/fr/deploy/self-host.mdx @@ -0,0 +1,261 @@ +--- +title: "Auto-hébergement" +description: "Exécutez Mintlify dans votre propre cloud ou environnement on-premises, sur AWS ou n'importe quelle plateforme Kubernetes, y compris Azure, Google Cloud, Oracle Cloud et OpenShift." +keywords: ["self-host", "self-hosted", "on-prem", "deploy", "AWS", "CDK", "Helm", "Kubernetes", "OpenShift", "air gap", "enterprise"] +--- + + + L'auto-hébergement nécessite un [plan Enterprise](https://mintlify.com/pricing?ref=self-host). Contactez votre équipe de compte pour cadrer un déploiement. + + +L'auto-hébergement exécute Mintlify dans votre propre compte cloud ou data center, afin que votre contenu, votre pipeline de build, vos analyses et vos logs restent à l'intérieur des limites de votre réseau. Il est conçu pour les équipes ayant des exigences de résidence des données, de conformité ou d'air-gap auxquelles un déploiement hébergé dans le cloud ne peut pas répondre. + +Chaque déploiement auto-hébergé est un engagement cadré avec votre équipe de compte, et non une installation en libre-service. Cette page décrit ce que vous provisionnez, comment le déploiement fonctionne et les compromis par rapport à l'hébergement cloud, afin que vous puissiez évaluer l'auto-hébergement avant de vous y engager. + +
+ ## Plateformes prises en charge +
+ +| Plateforme | Méthode | +| --- | --- | +| Amazon Web Services | Application AWS Cloud Development Kit (CDK) | +| Microsoft Azure | Helm chart sur Azure Kubernetes Service (AKS) | +| Google Cloud | Helm chart sur Google Kubernetes Engine (GKE) | +| Oracle Cloud | Helm chart sur Oracle Container Engine for Kubernetes (OKE) | +| Red Hat OpenShift | Helm chart | +| Tout Kubernetes | Helm chart | + +
+ ## Comparaison de l'auto-hébergement et de l'hébergement cloud +
+ +La rédaction fonctionne de la même manière dans les deux modèles d'hébergement. Votre équipe entretient le contenu avec l'éditeur ou son workflow Git, et chaque modification suit le processus de revue de votre dépôt. Ce qui change, c'est qui exploite la plateforme et où résident les données. + +| Domaine | Hébergé dans le cloud | Auto-hébergé | +| --- | --- | --- | +| Délai de mise en service | Le jour même | Engagement cadré, généralement plusieurs semaines | +| Infrastructure | Mintlify exploite tout | Vous exploitez le cluster, le réseau et les magasins de données. Mintlify livre des versions numérotées avec des guides de mise à niveau et prend en charge la couche applicative | +| Mises à jour de la plateforme | Continues et automatiques | Versions numérotées que vous examinez et déployez selon votre propre calendrier | +| Frontière des données | Traitées dans le cloud de Mintlify | Le contenu, les builds, les analyses et les logs restent à l'intérieur de votre réseau, sans sortie vers des tiers | +| Fonctionnalités d'IA | Activées par défaut | Livrées désactivées jusqu'à ce que votre équipe de sécurité ou de gouvernance de l'IA les approuve. Peuvent s'exécuter sur votre propre endpoint de modèle, votre propre clé API ou le cloud Mintlify | +| Intégrations | Catalogue complet | Les intégrations qui dépendent des services cloud de Mintlify ne sont pas disponibles | +| Supervision | Gérée par Mintlify | Vous branchez votre propre stack d'observabilité | + +Les déploiements auto-hébergés commencent en général de manière restreinte et s'étendent. Un cheminement courant consiste à démarrer avec de la documentation publique, puis à ajouter du contenu authentifié, l'éditeur web et les fonctionnalités d'IA à mesure que vous validez les revues de sécurité. + +
+ ## Fonctionnalités +
+ +Tout ce qui est essentiel à la rédaction, au build et à la diffusion de la documentation est inclus dans un déploiement auto-hébergé. + +| Fonctionnalité | Disponibilité | Notes | +| --- | :---: | --- | +| Site de documentation | | Rendu complet, composants et personnalisation du thème | +| Éditeur web | | Rédaction depuis le navigateur | +| Workflow adossé à Git | | GitHub, GitHub Enterprise Server, GitLab y compris self-managed, Bitbucket, ou une API proxy détenue en interne | +| Recherche | | S'exécute à l'intérieur de votre déploiement. L'index est reconstruit à la publication | +| Contenu authentifié | | Contrôle d'accès via votre fournisseur d'identité | +| SSO du dashboard | | OIDC ou SAML | +| Analyses | | Collectées et stockées à l'intérieur de votre réseau | +| Widgets d'analyse et de support tiers | | Configurés avec vos propres clés, servis depuis le site de documentation | +| Export statique | | Bundles autonomes pour une diffusion en air-gapped | +| Versions et rollback | | Chaque version fige les versions d'image. Revenez en arrière en redéployant la version précédente | +| Assistant et agent d'IA | Optionnel | Livrés désactivés. S'exécutent sur votre propre endpoint de modèle, votre propre clé API ou le cloud Mintlify | + +Seules quelques surfaces plus restreintes qui dépendent de services exploités par Mintlify sont réservées au cloud : l'application Slack, les connecteurs tiers pour les automatisations de l'agent et les intégrations de génération de SDK. + +
+ ## Architecture +
+ +Un déploiement auto-hébergé est un ensemble de services avec des dépendances claires. Provisionnez d'abord les magasins de données, puis les services qui en dépendent, puis la périphérie. + +```mermaid +flowchart TD + U[Users] --> CDN[CDN and WAF] + CDN --> ING[Load balancer or ingress] + ING --> WEB[Docs site] + ING --> API[Dashboard and API] + API --> BUILD[Build workers] + BUILD --> GIT[Git source] + WEB --> OBJ[(Object storage)] + BUILD --> OBJ + API --> MONGO[(MongoDB)] + API --> PG[(PostgreSQL)] + API --> REDIS[(Redis)] + API --> SEARCH[Search and indexing] + API --> IDP[Identity provider] + API -. optional .-> AI[AI assistant services] +``` + +| Ressource | Rôle | Requis | +| --- | --- | :---: | +| Équilibreur de charge ou ingress | Terminaison TLS et routage | | +| Site de documentation | Sert la documentation rendue | | +| Dashboard et API | Administration, authentification et orchestration des builds | | +| Workers de build | Compilent et publient les sites de documentation | | +| MongoDB | Magasin de contenu | | +| PostgreSQL | Métadonnées de déploiement et d'utilisateurs | | +| Redis | File d'attente de build et cache | | +| Stockage d'objets | Bundles de sites compilés et exports statiques | | +| Recherche et indexation | Recherche dans la documentation. L'index est reconstruit à la publication | | +| Fournisseur d'identité | SSO OIDC ou SAML pour le dashboard et le contenu authentifié | | +| Services d'assistant d'IA | Fonctionnalités d'assistant et d'agent | Optionnel | + +La source de votre documentation peut être GitHub, GitHub Enterprise Server, GitLab (y compris self-managed) ou Bitbucket. + +Si votre organisation ne peut pas fournir d'identifiants de dépôt à un service tiers, vous pouvez à la place placer votre hébergement Git derrière une API proxy détenue en interne, et les environnements totalement air-gapped utilisent l'[export statique](/fr/api/static-export/overview) sans aucune connexion Git. + +
+ ### Dimensionnement +
+ +Comme point de départ, un déploiement de production s'exécute sur environ 45 à 60 vCPU, 160 à 220 Go de mémoire et environ 1 To de stockage SSD réparti entre les services, les environnements hors production tournant à environ la moitié. Votre équipe de compte dimensionne le déploiement avec vous en fonction du nombre de pages, du trafic et des fonctionnalités que vous activez. + +
+ ## Mettre en place votre plateforme +
+ + + + Les déploiements AWS utilisent une application AWS CDK qui provisionne et met à jour l'ensemble de la stack dans votre compte. L'application CDK fige les images de conteneur sur des versions spécifiques, de sorte que chaque déploiement est reproductible et vérifiable. + + ### Ce que vous fournissez + + | Composant | Exigence | Notes | + | --- | --- | --- | + | Calcul | Cluster Amazon ECS | Exécute les services Mintlify | + | Magasin de contenu | Amazon DocumentDB | Compatible MongoDB | + | Magasin de métadonnées | Amazon RDS for PostgreSQL | Métadonnées de déploiement et d'utilisateurs | + | Cache et file d'attente | Amazon ElastiCache for Redis | File d'attente de build et cache | + | Stockage d'objets | Amazon S3 | Bundles de sites compilés et exports statiques | + | CDN | Amazon CloudFront | Sert le site de documentation en périphérie | + | Réseau | VPC avec sous-réseaux publics et privés, Application Load Balancer | Isole les charges de travail | + | TLS et DNS | AWS Certificate Manager, Amazon Route 53 | HTTPS et routage pour votre domaine | + | Secrets | AWS Secrets Manager | Identifiants de base de données et secrets de signature | + | Identité | Fournisseur OIDC ou SAML | SSO du dashboard | + + ### Configuration + + + + Votre équipe de compte examine votre topologie réseau, votre hébergement Git, votre fournisseur d'identité et vos exigences de conformité, puis livre l'application CDK et l'accès aux images de conteneur numérotées. + + + Définissez votre domaine, votre certificat et votre réseau dans le contexte CDK, examinez le change set et déployez. + + ```bash + cdk diff + cdk deploy --all + ``` + + + Accordez au déploiement l'accès à vos dépôts de documentation et connectez votre fournisseur d'identité. + + + Vérifiez les builds et la recherche sur votre domaine de staging, puis pointez votre DNS de production vers le déploiement. + + + + + + Les déploiements Kubernetes utilisent le Helm chart enterprise de Mintlify et fonctionnent sur n'importe quel cluster Kubernetes certifié. Le même chart couvre Kubernetes managé sur tous les clouds et les clusters on-premises : + + - **Azure** : AKS, avec Microsoft Entra ID pour le SSO et les services de données managés Azure. + - **Google Cloud** : GKE, avec Cloud SQL, Memorystore et Cloud Storage. + - **Oracle Cloud** : OKE, avec les bases de données managées OCI et OCI Object Storage. + - **OpenShift** : livre des contextes de sécurité compatibles OpenShift et utilise les Routes pour l'ingress. + + ### Ce que vous fournissez + + | Composant | Exigence | Notes | + | --- | --- | --- | + | Cluster | Cluster Kubernetes ou OpenShift | Héberge la release Helm | + | Magasin de contenu | MongoDB | Managé ou dans le cluster | + | Magasin de métadonnées | PostgreSQL | Managé ou dans le cluster | + | Cache et file d'attente | Redis | File d'attente de build et cache | + | Stockage d'objets | Bucket compatible S3 | Bundles de sites compilés et exports statiques | + | Ingress | Contrôleur d'ingress ou Route OpenShift avec TLS | Sert HTTPS. Un WAF en amont est recommandé | + | Registre | Registre de conteneurs privé | Héberge les images livrées | + | Identité | Fournisseur OIDC ou SAML | SSO du dashboard | + + ### Configuration + + + + Votre équipe de compte examine votre cluster, votre hébergement Git, votre fournisseur d'identité et vos exigences de conformité, puis livre le Helm chart, un modèle de values et des images de conteneur numérotées pour votre registre. + + + Mettez en place MongoDB, PostgreSQL, Redis et le stockage d'objets, managés par votre fournisseur cloud ou dans le cluster. + + + Pointez le fichier values vers vos magasins de données, votre ingress et votre registre, puis installez la release. + + ```bash + helm upgrade --install mintlify ./mintlify-enterprise \ + --namespace mintlify --create-namespace -f values.yaml + ``` + + + Accordez au déploiement l'accès à vos dépôts de documentation, connectez votre fournisseur d'identité, vérifiez en staging et pointez le DNS de production vers le déploiement. + + + + + +
+ ## Mises à jour +
+ +Les mises à jour de la plateforme et les mises à jour du contenu évoluent indépendamment. Vous contrôlez le moment où la plateforme change, et votre documentation reste à jour d'elle-même. + +
+ ### Mises à jour de la plateforme +
+ +Mintlify livre des versions numérotées avec des guides de mise à niveau et des notes de version, via votre équipe de compte. Chaque version fige des versions d'image spécifiques, ce qui vous permet de tester une release dans un environnement hors production avant de la déployer et de revenir à la version précédente si besoin. + + + +```bash AWS (CDK) +# examinez le change set pour la nouvelle version, puis déployez-la +cdk diff +cdk deploy --all +``` + +```bash Kubernetes (Helm) +# mettez à niveau vers une version livrée, ou revenez en arrière +helm upgrade mintlify ./mintlify-enterprise \ + --namespace mintlify -f values.yaml +helm rollback mintlify +``` + + + +Les mises à jour se déploient sans interruption de service. De nouvelles tâches ou de nouveaux pods démarrent, passent les health checks et remplacent les anciens. + +
+ ### Mises à jour du contenu +
+ +Le contenu passe par votre source Git, pas par les releases de la plateforme. Lorsque vous poussez sur votre dépôt de documentation, les workers de build reconstruisent le site et le publient automatiquement dans le stockage d'objets. Les changements de contenu ne nécessitent jamais un déploiement de plateforme. + +
+ ## Déploiements air-gapped +
+ +Les environnements sans chemin de webhook Git servent la documentation sous forme de [bundles d'export statique](/fr/api/static-export/overview). Des builds autonomes de votre site sont publiés dans le stockage d'objets et servis via votre CDN. Régénérez le bundle quand le contenu change, ou automatisez la boucle avec une GitHub Action. Les fonctionnalités d'IA qui nécessitent un accès réseau sortant sont désactivées dans les déploiements air-gapped. + +
+ ## Étapes suivantes +
+ + + + Cadrez un déploiement auto-hébergé sur votre plateforme et planifiez votre lancement. + + + Générez des bundles autonomes de votre documentation pour une diffusion en air-gapped. + + diff --git a/zh.json b/zh.json index 21fd853c0..0d1f7b074 100644 --- a/zh.json +++ b/zh.json @@ -196,7 +196,8 @@ "zh/deploy/github", "zh/deploy/ghes", "zh/deploy/gitlab", - "zh/deploy/gitlab-self-hosted" + "zh/deploy/gitlab-self-hosted", + "zh/deploy/self-host" ] }, { diff --git a/zh/deploy/self-host.mdx b/zh/deploy/self-host.mdx new file mode 100644 index 000000000..130a7f420 --- /dev/null +++ b/zh/deploy/self-host.mdx @@ -0,0 +1,261 @@ +--- +title: "自托管" +description: "在你自己的云或本地环境中运行 Mintlify，可部署在 AWS 或任何 Kubernetes 平台上，包括 Azure、Google Cloud、Oracle Cloud 和 OpenShift。" +keywords: ["self-host", "self-hosted", "on-prem", "deploy", "AWS", "CDK", "Helm", "Kubernetes", "OpenShift", "air gap", "enterprise"] +--- + + + 自托管需要 [Enterprise 套餐](https://mintlify.com/pricing?ref=self-host)。请联系你的客户团队来规划部署。 + + +自托管将 Mintlify 运行在你自己的云账户或数据中心中，因此你的内容、构建流水线、分析数据和日志都会保留在你的网络边界内。它面向那些有数据驻留、合规或气隙（air-gap）需求，而云托管部署无法满足的团队。 + +每次自托管部署都是与你的客户团队共同确定范围的合作项目，而不是自助安装。本页描述你需要配置的内容、部署的运行方式以及与云托管相比的取舍，帮助你在决定采用自托管之前进行评估。 + +
+ ## 支持的平台 +
+ +| 平台 | 方式 | +| --- | --- | +| Amazon Web Services | AWS Cloud Development Kit (CDK) 应用 | +| Microsoft Azure | 在 Azure Kubernetes Service (AKS) 上使用 Helm chart | +| Google Cloud | 在 Google Kubernetes Engine (GKE) 上使用 Helm chart | +| Oracle Cloud | 在 Oracle Container Engine for Kubernetes (OKE) 上使用 Helm chart | +| Red Hat OpenShift | Helm chart | +| 任意 Kubernetes | Helm chart | + +
+ ## 自托管与云托管的对比 +
+ +在两种托管模式下，内容创作的方式是相同的。你的团队通过编辑器或其 Git 工作流维护内容，每次变更都会经过你仓库的评审流程。变化的是由谁来运行平台，以及数据存放在哪里。 + +| 方面 | 云托管 | 自托管 | +| --- | --- | --- | +| 上线时间 | 当天即可 | 需按范围协作，通常需要数周 | +| 基础设施 | 由 Mintlify 运行全部内容 | 由你运行集群、网络和数据存储。Mintlify 提供带升级指南的版本化发布，并为应用层提供支持 | +| 平台更新 | 持续、自动 | 由你审阅并按自己的节奏部署的版本化发布 | +| 数据边界 | 在 Mintlify 云端处理 | 内容、构建、分析和日志都保留在你的网络内，没有向第三方的外发流量 | +| AI 功能 | 默认开启 | 交付时默认禁用，直到你的安全或 AI 治理团队批准后才启用。可以对接你自己的模型端点、你自己的 API key 或 Mintlify 云 | +| 集成 | 完整目录 | 依赖 Mintlify 云服务的集成不可用 | +| 监控 | 由 Mintlify 管理 | 由你接入自己的可观测性技术栈 | + +自托管部署通常从较小的范围开始，然后逐步扩展。常见的路径是先从公共文档入手，随着安全评审的完成，再逐步添加认证内容、Web 编辑器和 AI 功能。 + +
+ ## 功能 +
+ +创作、构建和分发文档所需的所有核心功能都包含在自托管部署中。 + +| 功能 | 可用性 | 说明 | +| --- | :---: | --- | +| 文档站点 | | 完整渲染、组件和主题定制 | +| Web 编辑器 | | 基于浏览器的内容创作 | +| 基于 Git 的工作流 | | GitHub、GitHub Enterprise Server、GitLab（包括自管版）、Bitbucket，或内部拥有的代理 API | +| 搜索 | | 在你的部署内运行。发布时重建索引 | +| 认证内容 | | 通过你的身份提供方进行访问控制 | +| 控制台 SSO | | OIDC 或 SAML | +| 分析 | | 在你的网络内采集和存储 | +| 第三方分析和支持挂件 | | 使用你自己的密钥进行配置，通过文档站点提供服务 | +| 静态导出 | | 用于气隙环境的自包含 bundle | +| 版本化发布和回滚 | | 每个版本都固定镜像版本。通过重新部署上一个版本进行回滚 | +| AI 助手和智能体 | 可选 | 默认禁用交付。可对接你自己的模型端点、你自己的 API key 或 Mintlify 云 | + +只有少数依赖 Mintlify 运营服务的小范围功能仅限云端提供：Slack 应用、用于智能体自动化的第三方连接器，以及 SDK 生成集成。 + +
+ ## 架构 +
+ +自托管部署是一组具有清晰依赖关系的服务。先配置数据存储，再配置依赖它们的服务，最后配置边缘。 + +```mermaid +flowchart TD + U[Users] --> CDN[CDN and WAF] + CDN --> ING[Load balancer or ingress] + ING --> WEB[Docs site] + ING --> API[Dashboard and API] + API --> BUILD[Build workers] + BUILD --> GIT[Git source] + WEB --> OBJ[(Object storage)] + BUILD --> OBJ + API --> MONGO[(MongoDB)] + API --> PG[(PostgreSQL)] + API --> REDIS[(Redis)] + API --> SEARCH[Search and indexing] + API --> IDP[Identity provider] + API -. optional .-> AI[AI assistant services] +``` + +| 资源 | 用途 | 必需 | +| --- | --- | :---: | +| 负载均衡器或 ingress | TLS 终止和路由 | | +| 文档站点 | 提供渲染后的文档 | | +| 控制台和 API | 管理、认证和构建编排 | | +| 构建 worker | 构建并发布文档站点 | | +| MongoDB | 内容存储 | | +| PostgreSQL | 部署和用户元数据 | | +| Redis | 构建队列和缓存 | | +| 对象存储 | 构建产物和静态导出 | | +| 搜索和索引 | 文档搜索。发布时重建索引 | | +| 身份提供方 | 用于控制台和认证内容的 OIDC 或 SAML SSO | | +| AI 助手服务 | 助手和智能体功能 | 可选 | + +你的文档源可以是 GitHub、GitHub Enterprise Server、GitLab（包括自管版）或 Bitbucket。 + +如果你的组织无法向第三方服务授予仓库凭据，也可以在 Git 托管前放置一个内部拥有的代理 API；而完全气隙的环境则使用[静态导出](/zh/api/static-export/overview)，无需任何 Git 连接。 + +
+ ### 规格评估 +
+ +作为起点，一个生产环境部署大约需要 45 到 60 个 vCPU、160 到 220 GB 内存，以及各服务合计约 1 TB 的固态存储，非生产环境大约为生产环境的一半。你的客户团队会根据页面数量、流量和你启用的功能与你共同确定部署规格。 + +
+ ## 搭建你的平台 +
+ + + + AWS 部署使用 AWS CDK 应用，在你的账户中配置并更新整个技术栈。CDK 应用将容器镜像固定到特定版本，因此每次部署都是可复现且可评审的。 + + ### 你需要提供的资源 + + | 组件 | 要求 | 说明 | + | --- | --- | --- | + | 计算 | Amazon ECS 集群 | 运行 Mintlify 服务 | + | 内容存储 | Amazon DocumentDB | 与 MongoDB 兼容 | + | 元数据存储 | Amazon RDS for PostgreSQL | 部署和用户元数据 | + | 缓存和队列 | Amazon ElastiCache for Redis | 构建队列和缓存 | + | 对象存储 | Amazon S3 | 构建产物和静态导出 | + | CDN | Amazon CloudFront | 在边缘提供文档站点 | + | 网络 | 带公共和私有子网的 VPC，Application Load Balancer | 隔离工作负载 | + | TLS 和 DNS | AWS Certificate Manager、Amazon Route 53 | 为你的域名提供 HTTPS 和路由 | + | 密钥 | AWS Secrets Manager | 数据库凭据和签名密钥 | + | 身份 | OIDC 或 SAML 提供方 | 控制台 SSO | + + ### 配置步骤 + + + + 你的客户团队会审阅你的网络拓扑、Git 托管、身份提供方和合规要求，然后交付 CDK 应用以及版本化容器镜像的访问权限。 + + + 在 CDK 上下文中设置你的域名、证书和网络，审阅 change set 并进行部署。 + + ```bash + cdk diff + cdk deploy --all + ``` + + + 授予部署访问你文档仓库的权限，并接入你的身份提供方。 + + + 在预发环境域名上验证构建和搜索，然后将生产 DNS 指向该部署。 + + + + + + Kubernetes 部署使用 Mintlify 的企业版 Helm chart，可运行在任何经过认证的 Kubernetes 集群上。同一个 chart 同时覆盖各家云上的托管 Kubernetes 和本地集群： + + - **Azure**：AKS，使用 Microsoft Entra ID 进行 SSO，并使用 Azure 托管数据服务。 + - **Google Cloud**：GKE，使用 Cloud SQL、Memorystore 和 Cloud Storage。 + - **Oracle Cloud**：OKE，使用 OCI 托管数据库和 OCI Object Storage。 + - **OpenShift**：附带兼容 OpenShift 的安全上下文，并使用 Routes 作为 ingress。 + + ### 你需要提供的资源 + + | 组件 | 要求 | 说明 | + | --- | --- | --- | + | 集群 | Kubernetes 或 OpenShift 集群 | 承载 Helm release | + | 内容存储 | MongoDB | 托管或集群内运行 | + | 元数据存储 | PostgreSQL | 托管或集群内运行 | + | 缓存和队列 | Redis | 构建队列和缓存 | + | 对象存储 | S3 兼容的 bucket | 构建产物和静态导出 | + | Ingress | 支持 TLS 的 ingress 控制器或 OpenShift Route | 提供 HTTPS。建议在前面加一个 WAF | + | 镜像仓库 | 私有容器镜像仓库 | 存放交付的镜像 | + | 身份 | OIDC 或 SAML 提供方 | 控制台 SSO | + + ### 配置步骤 + + + + 你的客户团队会审阅你的集群、Git 托管、身份提供方和合规要求，然后交付 Helm chart、values 模板以及供你镜像仓库使用的版本化容器镜像。 + + + 搭建 MongoDB、PostgreSQL、Redis 和对象存储，可由你的云厂商托管或运行在集群内。 + + + 将 values 文件指向你的数据存储、ingress 和镜像仓库，然后安装 release。 + + ```bash + helm upgrade --install mintlify ./mintlify-enterprise \ + --namespace mintlify --create-namespace -f values.yaml + ``` + + + 授予部署访问你文档仓库的权限，接入你的身份提供方，在预发环境验证后，将生产 DNS 指向该部署。 + + + + + +
+ ## 更新 +
+ +平台更新和内容更新是相互独立的。你控制平台何时变更，而你的文档也会独立地保持最新。 + +
+ ### 平台更新 +
+ +Mintlify 通过你的客户团队交付带有升级指南和发布说明的版本化发布。每个版本都固定特定的镜像版本，因此你可以先在非生产环境中测试某个 release，然后再进行部署，如有需要还可以回滚到上一个版本。 + + + +```bash AWS (CDK) +# 审阅新版本的 change set，然后进行部署 +cdk diff +cdk deploy --all +``` + +```bash Kubernetes (Helm) +# 升级到已交付的版本，或进行回滚 +helm upgrade mintlify ./mintlify-enterprise \ + --namespace mintlify -f values.yaml +helm rollback mintlify +``` + + + +更新过程零停机。新的任务或 pod 会启动、通过健康检查，然后替换掉旧的实例。 + +
+ ### 内容更新 +
+ +内容通过你的 Git 源流转，而不是通过平台发布进行。当你向文档仓库推送提交时，构建 worker 会重新构建站点并自动发布到对象存储。内容变更从不需要平台部署。 + +
+ ## 气隙部署 +
+ +没有 Git webhook 通路的环境将文档作为[静态导出 bundle](/zh/api/static-export/overview) 进行分发。你站点的自包含构建被发布到对象存储，并通过你的 CDN 提供服务。内容变更时重新生成 bundle，或者使用 GitHub Action 自动化整个流程。在气隙部署中，需要外部网络访问的 AI 功能会被禁用。 + +
+ ## 后续步骤 +
+ + + + 在你的平台上规划自托管部署，并制定上线计划。 + + + 生成文档的自包含 bundle，以在气隙环境中提供服务。 + +