反向代理 - Mintlify

反向代理配置仅适用于 Enterprise 方案。

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

选择你的部署方式

Mintlify 根据你的子路径需求支持两种反向代理配置。

在 /docs 下托管：在控制台的 Custom domain setup 页面中开启 Host at /docs 开关。这种方式路由更少，配置更简单。
自定义子路径：使用你选择的任意子路径。这种方式需要额外的路由规则。

两种配置都使用 mintlify.site 作为代理目标。

在 `/docs` 子路径下托管

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

在控制台中前往自定义 domain 设置。
启用 Host at /docs 开关。
输入你的 domain 并选择 Add domain。

当你启用 Host at /docs 时，你的文档规范 URL 将变为 <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
`/.well-known/vercel/*`	`<your-subdomain>.mintlify.site`	No cache
`/.well-known/skills/*` (optional)	`<your-subdomain>.mintlify.site/docs`	No cache
`/.well-known/agent-skills/*` (optional)	`<your-subdomain>.mintlify.site/docs`	No cache
`/skill.md` (optional)	`<your-subdomain>.mintlify.site/docs`	No cache
`/llms.txt` (optional)	`<your-subdomain>.mintlify.site/docs`	No cache
`/llms-full.txt` (optional)	`<your-subdomain>.mintlify.site/docs`	No cache

/.well-known/skills/*、/.well-known/agent-skills/*、/skill.md、/llms.txt 和 /llms-full.txt 这些路由是可选的。只有当你希望在站点根路径（例如 your-domain.com/llms.txt）而不是在文档子路径下（例如 your-domain.com/docs/llms.txt）提供 AI 文件时，才需要包含它们。

必需的请求头配置

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

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 验证路径
    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 技能路径
    location ^~ /.well-known/skills/ {
        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";
    }

    # Agent-skills discovery paths
    location ^~ /.well-known/agent-skills/ {
        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";
    }

    # 技能清单(可选)
    location = /skill.md {
        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";
    }

    # LLM 索引文件(可选)
    location = /llms.txt {
        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";
    }

    location = /llms-full.txt {
        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";
    }

    # 文档根路径
    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";
    }

    # 所有文档路径
    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）时，请使用以下路由配置。按以下缓存策略将这些路径代理到你的 Mintlify 子域：

Path	Destination	Caching
`/.well-known/vercel/*`	`<your-subdomain>.mintlify.site`	不缓存
`/.well-known/skills/*`	`<your-subdomain>.mintlify.site`	不缓存
`/.well-known/agent-skills/*`	`<your-subdomain>.mintlify.site`	不缓存
`/skill.md`	`<your-subdomain>.mintlify.site`	不缓存
`/llms.txt`	`<your-subdomain>.mintlify.site`	不缓存
`/llms-full.txt`	`<your-subdomain>.mintlify.site`	不缓存
`/mintlify-assets/_next/static/*`	`<your-subdomain>.mintlify.site`	启用缓存
`/_mintlify/*`	`<your-subdomain>.mintlify.site`	不缓存
`/*`	`<your-subdomain>.mintlify.site`	不缓存
`/`	`<your-subdomain>.mintlify.site`	不缓存

Mintlify 在根路径提供 llms.txt、llms-full.txt 和 skill.md。如果你的文档位于子路径下（例如 /help），你也可以在该子路径下提供这些文件（例如 /help/llms.txt）。为此，请添加 location 块将子路径重写到根路径。请参阅下方的 nginx 示例了解这两种模式。

必需的请求头配置

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

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;

        # 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.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;

        # Disable caching for verification paths
        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;
        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;

        # Disable caching for agent-skills paths
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Skill manifest
    location = /skill.md {
        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;

        # Disable caching for skill manifest
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # LLM 索引文件
    location = /llms.txt {
        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";
    }

    location = /llms-full.txt {
        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 文件并进行路径重写。
    # 将 "/help" 替换为你的子路径。这些块会重写子路径，
    # 使 Mintlify 接收到它期望的根路径。
    #
    # location = /help/llms.txt {
    #     proxy_pass https://<your-subdomain>.mintlify.site/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 = /help/llms-full.txt {
    #     proxy_pass https://<your-subdomain>.mintlify.site/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";
    # }
    #
    # location = /help/skill.md {
    #     proxy_pass https://<your-subdomain>.mintlify.site/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";
    # }

    # Static assets with caching
    location ~ ^/mintlify-assets/_next/static/ {
        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;

        # Enable caching for static assets
        add_header Cache-Control "public, max-age=86400";
    }

    # Mintlify-specific paths
    location ~ ^/_mintlify/ {
        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;

        # Disable caching for Mintlify paths
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Root path
    location = / {
        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 other documentation paths
    location / {
        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";
    }
}

疑难解答

更改未显示

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

404 错误

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

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

性能问题

表现：页面加载缓慢，出现布局位移。原因：缓存配置不正确。 解决方案：对于自定义子路径配置，仅对 /mintlify-assets/_next/static/* 路径启用缓存。/docs 子路径配置会自动处理缓存。

​选择你的部署方式

​在 /docs 子路径下托管

​路由配置

​必需的请求头配置

​nginx 配置示例

​自定义子路径

​必需的请求头配置

​Nginx 配置示例

​疑难解答

​更改未显示

​404 错误

​性能问题

选择你的部署方式

在 `/docs` 子路径下托管

路由配置

必需的请求头配置

nginx 配置示例

自定义子路径

必需的请求头配置

Nginx 配置示例

疑难解答

更改未显示

404 错误

性能问题