自托管
在你自己的云或本地环境中运行 Mintlify，可部署在 AWS 或任何 Kubernetes 平台上，包括 Azure、Google Cloud、Oracle Cloud 和 OpenShift。
自托管需要 Enterprise 套餐。请联系你的客户团队来规划部署。
自托管将 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 生成集成。
自托管部署是一组具有清晰依赖关系的服务。先配置数据存储，再配置依赖它们的服务，最后配置边缘。
| 资源 | 用途 | 必需 |
|---|---|---|
| 负载均衡器或 ingress | TLS 终止和路由 | |
| 文档站点 | 提供渲染后的文档 | |
| 控制台和 API | 管理、认证和构建编排 | |
| 构建 worker | 构建并发布文档站点 | |
| MongoDB | 内容存储 | |
| PostgreSQL | 部署和用户元数据 | |
| Redis | 构建队列和缓存 | |
| 对象存储 | 构建产物和静态导出 | |
| 搜索和索引 | 文档搜索。发布时重建索引 | |
| 身份提供方 | 用于控制台和认证内容的 OIDC 或 SAML SSO | |
| AI 助手服务 | 助手和智能体功能 | 可选 |
你的文档源可以是 GitHub、GitHub Enterprise Server、GitLab（包括自管版）或 Bitbucket。
如果你的组织无法向第三方服务授予仓库凭据，也可以在 Git 托管前放置一个内部拥有的代理 API；而完全气隙的环境则使用静态导出，无需任何 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 |
配置步骤
Scope the deployment
你的客户团队会审阅你的网络拓扑、Git 托管、身份提供方和合规要求，然后交付 CDK 应用以及版本化容器镜像的访问权限。
Configure and deploy
在 CDK 上下文中设置你的域名、证书和网络，审阅 change set 并进行部署。
cdk diff
cdk deploy --allConnect Git and SSO
授予部署访问你文档仓库的权限，并接入你的身份提供方。
Cut over
在预发环境域名上验证构建和搜索，然后将生产 DNS 指向该部署。
平台更新和内容更新是相互独立的。你控制平台何时变更，而你的文档也会独立地保持最新。
Mintlify 通过你的客户团队交付带有升级指南和发布说明的版本化发布。每个版本都固定特定的镜像版本，因此你可以先在非生产环境中测试某个 release，然后再进行部署，如有需要还可以回滚到上一个版本。
# 审阅新版本的 change set，然后进行部署
cdk diff
cdk deploy --all更新过程零停机。新的任务或 pod 会启动、通过健康检查，然后替换掉旧的实例。
内容通过你的 Git 源流转，而不是通过平台发布进行。当你向文档仓库推送提交时，构建 worker 会重新构建站点并自动发布到对象存储。内容变更从不需要平台部署。
没有 Git webhook 通路的环境将文档作为静态导出 bundle 进行分发。你站点的自包含构建被发布到对象存储，并通过你的 CDN 提供服务。内容变更时重新生成 bundle，或者使用 GitHub Action 自动化整个流程。在气隙部署中，需要外部网络访问的 AI 功能会被禁用。