mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
c1171a757b
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
314 lines
12 KiB
Plaintext
314 lines
12 KiB
Plaintext
---
|
||
title: "反向代理"
|
||
description: "配置自定义反向代理以提供文档服务。"
|
||
keywords: ["反向代理配置", "nginx", "代理路由", "请求头转发"]
|
||
---
|
||
|
||
<Note>
|
||
反向代理配置仅适用于 [Enterprise 方案](https://mintlify.com/pricing?ref=reverse-proxy)。
|
||
</Note>
|
||
|
||
要通过自定义反向代理提供文档服务，你需要配置路由规则、缓存策略和请求头转发。
|
||
|
||
实施反向代理时，请留意可能出现的 domain 验证、SSL 证书签发、认证流程、性能以及 Analytics 跟踪等问题。
|
||
|
||
<div id="choose-your-deployment-approach">
|
||
## 选择你的部署方式
|
||
</div>
|
||
|
||
Mintlify 根据你的子路径需求支持两种反向代理配置。
|
||
|
||
- **在 `/docs` 下托管**：使用 `mintlify.dev` 作为代理目标。在控制台的 [Custom domain setup](https://dashboard.mintlify.com/settings/deployment/custom-domain) 页面中开启 **Host at `/docs`** 开关。这种方式路由更少，配置更简单。
|
||
- **自定义子路径**：使用 `mintlify.app` 作为代理目标。这种方式支持任意子路径，但需要额外的路由规则。
|
||
|
||
<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`** 会停止在 `mintlify.app` 上执行缓存失效。你必须代理到 `mintlify.dev` 才能看到更新。
|
||
</Warning>
|
||
|
||
<div id="routing-configuration">
|
||
### 路由配置
|
||
</div>
|
||
|
||
将以下路径代理到你的 Mintlify 子域：
|
||
|
||
| 路径 | 目标地址 | 缓存 |
|
||
| --------------------------------- | ------------------------------------ | -------- |
|
||
| `/docs` | `<your-subdomain>.mintlify.dev/docs` | No cache |
|
||
| `/docs/*` | `<your-subdomain>.mintlify.dev/docs` | No cache |
|
||
| `/.well-known/vercel/*` | `<your-subdomain>.mintlify.dev` | No cache |
|
||
| `/.well-known/skills/*` (optional)| `<your-subdomain>.mintlify.dev/docs` | No cache |
|
||
| `/skill.md` (optional) | `<your-subdomain>.mintlify.dev/docs` | No cache |
|
||
|
||
`/.well-known/skills/*` 和 `/skill.md` 这两个路由是可选的。只有当你希望在站点根路径（例如 `your-domain.com/skills.md`）而不是在文档子路径下（例如 `your-domain.com/docs/skills.md`）提供 AI 技能文件时，才需要包含它们。
|
||
|
||
<div id="required-header-configuration">
|
||
### 必需的请求头配置
|
||
</div>
|
||
|
||
按以下请求头要求配置你的反向代理：
|
||
|
||
- **Origin**：包含目标子域 `<your-subdomain>.mintlify.dev`
|
||
- **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.dev;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.dev;
|
||
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.dev/docs;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.dev;
|
||
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.dev/docs;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.dev;
|
||
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.dev/docs;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.dev;
|
||
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.dev/docs/;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.dev;
|
||
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.app` | 不缓存 |
|
||
| `/.well-known/skills/*` | `<your-subdomain>.mintlify.app` | 不缓存 |
|
||
| `/skill.md` | `<your-subdomain>.mintlify.app` | 不缓存 |
|
||
| `/mintlify-assets/_next/static/*` | `<your-subdomain>.mintlify.app` | 启用缓存 |
|
||
| `/_mintlify/*` | `<your-subdomain>.mintlify.app` | 不缓存 |
|
||
| `/*` | `<your-subdomain>.mintlify.app` | 不缓存 |
|
||
| `/` | `<your-subdomain>.mintlify.app` | 不缓存 |
|
||
|
||
<div id="required-header-configuration">
|
||
### 必需的请求头配置
|
||
</div>
|
||
|
||
按以下请求头要求配置你的反向代理：
|
||
|
||
- **Origin**：包含目标子域 `<your-subdomain>.mintlify.app`
|
||
- **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.app;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.app;
|
||
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.app;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.app;
|
||
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";
|
||
}
|
||
|
||
# Skill manifest
|
||
location = /skill.md {
|
||
proxy_pass https://<your-subdomain>.mintlify.app;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.app;
|
||
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";
|
||
}
|
||
|
||
# Static assets with caching
|
||
location ~ ^/mintlify-assets/_next/static/ {
|
||
proxy_pass https://<your-subdomain>.mintlify.app;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.app;
|
||
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.app;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.app;
|
||
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.app;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.app;
|
||
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.app;
|
||
proxy_set_header Origin <your-subdomain>.mintlify.app;
|
||
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>
|
||
|
||
**症状**：你发布了文档更新，但这些更改并没有在你的网站上显示出来。
|
||
|
||
**原因**：你在控制台中启用了 **Host at `/docs`**，但你的反向代理指向的是 `mintlify.app` 而不是 `mintlify.dev`。
|
||
|
||
**解决方案**：将反向代理配置更新为指向 `<your-subdomain>.mintlify.dev`，而不是 `<your-subdomain>.mintlify.app`。
|
||
|
||
<div id="404-error">
|
||
### 404 错误
|
||
</div>
|
||
|
||
**现象**：文档可以加载，但部分功能不可用。API 调用失败。
|
||
|
||
**原因**：反向代理转发了 `Host` 头，或缺少 `Origin` 头。
|
||
|
||
**解决方案**：
|
||
|
||
- 停止转发 `Host` 头
|
||
- 将 `Origin` 头设置为你的 Mintlify 子域（对于 `/docs` 子路径使用 `mintlify.dev`，其他子路径使用 `mintlify.app`）
|
||
|
||
<div id="performance-issues">
|
||
### 性能问题
|
||
</div>
|
||
|
||
**表现**：页面加载缓慢，出现布局位移。
|
||
|
||
**原因**：缓存配置不正确。
|
||
|
||
**解决方案**：对于自定义子路径配置，仅对 `/mintlify-assets/_next/static/*` 路径启用缓存。`/docs` 子路径配置会自动处理缓存。 |