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

​
设置你的基础路径

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

​
在 /docs 子路径下托管

当你希望在域名的 /docs 路径下提供文档服务时，请使用此配置。 在配置反向代理之前：
  1. 在控制台中前往 Custom domain setup。
  2. 启用 Host at 开关。
  3. 输入你的域名。
  4. 输入 docs 作为你的基础路径。
  5. 选择 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/docsNo cache
/docs/*<your-subdomain>.mintlify.site/docs/*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.mdNo cache
/llms.txt (可选)<your-subdomain>.mintlify.site/docs/llms.txtNo cache
/llms-full.txt (可选)<your-subdomain>.mintlify.site/docs/llms-full.txtNo 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。 /.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）：
  1. 在控制台中前往 Custom domain setup 页面。
  2. 启用 Host at 开关并输入你的基础路径。例如 /docs 或 /help。
  3. 输入你的域名。
  4. 输入你的基础路径。
  5. 选择 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）

​
性能问题

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