mintlify__docs/zh/deploy/reverse-proxy.mdx

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

import SubpathSetupSteps from "/snippets/zh/subpath-setup-steps.mdx";

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

在实施反向代理时，请留意可能出现的域名验证、SSL 证书签发、认证流程、性能以及分析追踪相关的问题。

<div id="set-your-base-path">
  ## 设置你的基础路径
</div>

在控制台的 [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) 页面上设置你的基础路径，然后将反向代理配置为把该路径路由到 Mintlify。默认基础路径是 `/docs`，但你可以使用任何你选择的基础路径，例如 `/help` 或 `/resources`。

在所有配置中，均使用 `mintlify.site` 作为代理目标。

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

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

在配置反向代理之前：

1. 在控制台中前往 [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain)。
2. 启用 **Host at** 开关。
3. 输入你的域名。
4. 输入 `docs` 作为你的基础路径。
5. 选择 **Add domain**。

<Warning>
  当你在子路径下托管时，你的文档规范 URL 将变为 `<your-subdomain>.mintlify.site<your-base-path>`，例如 `<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/.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`。

`/.well-known/skills/*`、`/.well-known/agent-skills/*`、`/skill.md`、`/llms.txt` 和 `/llms-full.txt` 路由是可选的。只有当你还希望在域名的根路径下提供这些文件时（例如 `your-domain.com/llms.txt`）才需要包含它们。请注意，每个根路径都会映射到你 Mintlify 子域上基础路径下的文件。

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

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

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

<SubpathSetupSteps />

Mintlify 会重新构建你的文档以在你的基础路径下提供服务，因此 `<your-subdomain>.mintlify.site<your-base-path>` 会提供你的内容。

按照与 `/docs` 子路径相同的[路由配置](#routing-configuration)、[请求头要求](#required-header-configuration)和 nginx 模式来配置你的反向代理，只需将 `/docs` 替换为你的基础路径。

<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/*` 路径，仅对这些静态资源启用缓存。