反向代理

要通过自定义反向代理提供文档服务，你需要配置路由规则、缓存策略和请求头转发。在实施反向代理时，请留意可能出现的域名验证、SSL 证书签发、认证流程、性能以及分析追踪相关的问题。

设置你的基础路径

在控制台的 Custom domain setup 页面上设置你的基础路径，然后将反向代理配置为把该路径路由到 Mintlify。默认基础路径是 /docs，但你可以使用任何你选择的基础路径，例如 /help 或 /resources。仓库中存放文档的目录并不会配置公开基础路径。例如，将文档存放在 /docs 目录下并不能替代在控制台中将 /docs 设置为基础路径。在所有配置中，均使用 mintlify.site 作为代理目标。

在 `/docs` 子路径下托管

当你希望在域名的 /docs 路径下提供文档服务时，请使用此配置。在配置反向代理之前：

在控制台中前往 Custom domain setup。
启用 Host at 开关。
输入你的域名。
输入 docs 作为你的基础路径。
选择 Add domain。

当你在子路径下托管时，你的文档规范 URL 将变为 <your-subdomain>.mintlify.site<your-base-path>，例如 <your-subdomain>.mintlify.site/docs。请将代理指向 <your-subdomain>.mintlify.site，缓存失效和更新才会生效。

路由配置

将以下路径代理到你的 Mintlify 子域：

路径	目标地址	缓存
`/docs`	`<your-subdomain>.mintlify.site/docs`	No cache
`/docs/*`	`<your-subdomain>.mintlify.site/docs/*`	No cache
`/docs/_llms/*`	`<your-subdomain>.mintlify.site/docs/_llms/*`	No cache
`/.well-known/vercel/*`	`<your-subdomain>.mintlify.site/.well-known/vercel/*`	No cache
`/.well-known/skills/*` (可选)	`<your-subdomain>.mintlify.site/docs/.well-known/skills/*`	No cache
`/.well-known/agent-skills/*` (可选)	`<your-subdomain>.mintlify.site/docs/.well-known/agent-skills/*`	No cache
`/skill.md` (可选)	`<your-subdomain>.mintlify.site/docs/skill.md`	No cache
`/llms.txt` (可选)	`<your-subdomain>.mintlify.site/docs/llms.txt`	No cache
`/llms-full.txt` (可选)	`<your-subdomain>.mintlify.site/docs/llms-full.txt`	No cache

你的代理必须在文档路径上转发所有 HTTP 方法。Mintlify 会以 POST 请求的形式将分析事件发送到 /docs/_mintlify/api/v1/e，因此仅允许 GET 和 HEAD 请求的代理会悄无声息地导致仪表板中的分析数据失效。 Mintlify 会在你的基础路径下提供这些文件，例如 <your-subdomain>.mintlify.site/docs/llms.txt，因此它们可以通过你的主要子路径路由，在你域名的子路径下访问，例如 your-domain.com/docs/llms.txt。 /docs/* 路由同样覆盖位于 /docs/_llms/* 下生成的 llms.txt 索引。如果你的代理使用更细粒度的路径允许列表，而不是转发所有 /docs/* 请求，请包含 /docs/_llms/*，以便代理能够跟随 /docs/llms.txt 中链接的每个索引。不要仅将 /docs/llms.txt 重写为托管在根路径的 /llms.txt。请将 /docs 设置为部署基础路径，并转发完整的 /docs/* 路由。这样可以让页面链接与生成的 /docs/_llms/* 索引链接保持在同一个公开前缀下。 /.well-known/skills/*、/.well-known/agent-skills/*、/skill.md、/llms.txt 和 /llms-full.txt 路由是可选的。只有当你还希望在域名的根路径下提供这些文件时（例如 your-domain.com/llms.txt）才需要包含它们。请注意，每个根路径都会映射到你 Mintlify 子域上基础路径下的文件。

必需的请求头配置

按以下请求头要求配置你的反向代理：

Origin：包含目标子域 <your-subdomain>.mintlify.site
X-Forwarded-For：保留客户端 IP 信息
X-Forwarded-Proto：保留原始协议（HTTP/HTTPS）
X-Real-IP：转发真实的客户端 IP 地址
User-Agent：转发用户代理

确保不要转发 Host 请求头。

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;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # AI skills paths
    location ^~ /.well-known/skills/ {
        proxy_pass https://<your-subdomain>.mintlify.site/docs/.well-known/skills/;
        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/.well-known/agent-skills/;
        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";
    }

    # Skill manifest (optional)
    location = /skill.md {
        proxy_pass https://<your-subdomain>.mintlify.site/docs/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";
    }

    # LLM index files (optional)
    location = /llms.txt {
        proxy_pass https://<your-subdomain>.mintlify.site/docs/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 = /llms-full.txt {
        proxy_pass https://<your-subdomain>.mintlify.site/docs/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";
    }

    # Documentation root
    location = /docs {
        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";
    }

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

自定义子路径

要使用 /docs 之外的子路径（例如 /help 或 /resources）：

在控制台中前往 Custom domain setup 页面。
启用 Host at 开关并输入你的基础路径。例如 /docs 或 /help。
输入你的域名。
输入你的基础路径。
选择 Add domain。

Mintlify 会重新构建你的文档以在你的基础路径下提供服务，因此 <your-subdomain>.mintlify.site<your-base-path> 会提供你的内容。按照与 /docs 子路径相同的路由配置、请求头要求和 nginx 模式来配置你的反向代理，只需将 /docs 替换为你的基础路径。

疑难解答

更改未显示

症状：你发布了文档更新，但这些更改并没有在你的网站上显示出来。原因：你的反向代理指向了过时的主机名。 解决方案：将反向代理配置更新为指向 <your-subdomain>.mintlify.site。

404 错误

症状：文档可以加载，但部分功能不可用。API 调用失败。原因：反向代理转发了 Host 头，或缺少 Origin 头。 解决方案：

停止转发 Host 头
将 Origin 头设置为你的 Mintlify 子域（<your-subdomain>.mintlify.site）

生成的 `/_llms/` 链接返回 404

症状：llms.txt 文件可以加载，但 /_llms/ 下的链接返回 404 或缺少你的公开子路径。原因：公开子路径与在 Mintlify 中配置的基础路径不匹配，或者代理仅转发了 llms.txt 而没有转发其生成的索引路由。 解决方案：

在 Mintlify 控制台中将公开子路径设置为基础路径。仓库中同名的目录并不会配置基础路径。
转发完整的 <base-path>/* 路由，或在细粒度允许列表中添加 <base-path>/_llms/*。
重新部署文档，然后同时验证 <base-path>/llms.txt 和一个链接的 <base-path>/_llms/*.md URL。

性能问题

症状：页面加载缓慢，出现布局位移。原因：缓存配置不正确。 解决方案：为文档路径禁用缓存。如果你代理了 /mintlify-assets/_next/static/* 路径，仅对这些静态资源启用缓存。

快速入门

创建内容

管理站点

Agent

Assistant

面向 Agent 的内容

搜索与 SEO

编写 API 文档

集成

参考

设置你的基础路径

在 `/docs` 子路径下托管

路由配置

必需的请求头配置

nginx 配置示例

自定义子路径

疑难解答

更改未显示

404 错误

生成的 `/_llms/` 链接返回 404

性能问题

​设置你的基础路径

​在 /docs 子路径下托管

​路由配置

​必需的请求头配置

​nginx 配置示例

​自定义子路径

​疑难解答

​更改未显示

​404 错误

​生成的 /_llms/ 链接返回 404

​性能问题

设置你的基础路径

在 `/docs` 子路径下托管

路由配置

必需的请求头配置

nginx 配置示例

自定义子路径

疑难解答

更改未显示

404 错误

生成的 `/_llms/` 链接返回 404

性能问题