mintlify__docs/zh/deploy/reverse-proxy.mdx

---
title: "反向代理"
description: "使用 Nginx、Apache 或 Caddy 配置自定义反向代理，在你自己的域名子路径上提供 Mintlify 文档服务。"
keywords: ["反向代理配置", "nginx", "代理路由", "请求头转发"]
---

<Note>
  反向代理配置仅适用于 [Enterprise 方案](https://mintlify.com/pricing?ref=reverse-proxy)。
</Note>

要通过自定义反向代理提供文档服务，你需要配置路由规则、缓存策略和请求头转发。

实施反向代理时，请留意可能出现的 domain 验证、SSL 证书签发、认证流程、性能以及 Analytics 跟踪等问题。

<div id="choose-your-deployment-approach">
  ## 选择你的部署方式
</div>

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

- **在 `/docs` 下托管**：在控制台的 [Custom domain setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) 页面中开启 **Host at `/docs`** 开关。这种方式路由更少，配置更简单。
- **自定义子路径**：使用你选择的任意子路径。这种方式需要额外的路由规则。

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

<div id="host-at-docs-subpath">
  ## 在 `/docs` 子路径下托管
</div>

当你希望在 domain 的 `/docs` 路径下提供文档时，使用此配置。

在配置反向代理之前：

1. 在控制台中前往 [自定义 domain 设置](https://dashboard.mintlify.com/settings/deployment/custom-domain)。
2. 启用 **Host at `/docs`** 开关。
3. 输入你的 domain 并选择 **Add domain**。

<Warning>
  当你启用 **Host at `/docs`** 时，你的文档规范 URL 将变为 `<your-subdomain>.mintlify.site/docs`。将代理指向 `<your-subdomain>.mintlify.site`，缓存失效和更新才会生效。
</Warning>

<div id="routing-configuration">
  ### 路由配置
</div>

将以下路径代理到你的 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 文件时，才需要包含它们。

<div id="required-header-configuration">
  ### 必需的请求头配置
</div>

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

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

<Warning>
  确保不要转发 `Host` 请求头。
</Warning>

<div id="example-nginx-configuration">
  ### nginx 配置示例
</div>

```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";
    }
}
```


<div id="custom-subpath">
  ## 自定义子路径
</div>

当你需要使用 `/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` | 不缓存        |

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

<div id="required-header-configuration">
  ### 必需的请求头配置
</div>

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

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

<Warning>
  确保不要转发 `Host` 请求头
</Warning>

### Nginx 配置示例

```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";
    }
}
```


<div id="troubleshooting">
  ## 疑难解答
</div>

<div id="changes-not-appearing">
  ### 更改未显示
</div>

**症状**：你发布了文档更新，但这些更改并没有在你的网站上显示出来。

**原因**：你的反向代理指向了过时的主机名。

**解决方案**：将反向代理配置更新为指向 `<your-subdomain>.mintlify.site`。

<div id="404-error">
  ### 404 错误
</div>

**现象**：文档可以加载，但部分功能不可用。API 调用失败。

**原因**：反向代理转发了 `Host` 头，或缺少 `Origin` 头。

**解决方案**：

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

<div id="performance-issues">
  ### 性能问题
</div>

**表现**：页面加载缓慢，出现布局位移。

**原因**：缓存配置不正确。

**解决方案**：对于自定义子路径配置，仅对 `/mintlify-assets/_next/static/*` 路径启用缓存。`/docs` 子路径配置会自动处理缓存。