mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
dbe23faeb2
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
253 lines
11 KiB
Plaintext
253 lines
11 KiB
Plaintext
---
|
||
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`。
|
||
|
||
仓库中存放文档的目录并不会配置公开基础路径。例如，将文档存放在 `/docs` 目录下并不能替代在控制台中将 `/docs` 设置为基础路径。
|
||
|
||
在所有配置中，均使用 `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 |
|
||
| `/docs/_llms/*` | `<your-subdomain>.mintlify.site/docs/_llms/*` | 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`。
|
||
|
||
`/docs/*` 路由同样覆盖位于 `/docs/_llms/*` 下生成的 `llms.txt` 索引。如果你的代理使用更细粒度的路径允许列表，而不是转发所有 `/docs/*` 请求，请包含 `/docs/_llms/*`，以便代理能够跟随 `/docs/llms.txt` 中链接的每个索引。
|
||
|
||
不要仅将 `/docs/llms.txt` 重写为托管在根路径的 `/llms.txt`。请将 `/docs` 设置为部署基础路径，并转发完整的 `/docs/*` 路由。这样可以让页面链接与生成的 `/docs/_llms/*` 索引链接保持在同一个公开前缀下。
|
||
|
||
`/.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="generated-_llms-links-return-404">
|
||
### 生成的 `/_llms/` 链接返回 404
|
||
</div>
|
||
|
||
**症状**：`llms.txt` 文件可以加载，但 `/_llms/` 下的链接返回 404 或缺少你的公开子路径。
|
||
|
||
**原因**：公开子路径与在 Mintlify 中配置的基础路径不匹配，或者代理仅转发了 `llms.txt` 而没有转发其生成的索引路由。
|
||
|
||
**解决方案**：
|
||
|
||
- 在 Mintlify 控制台中将公开子路径设置为基础路径。仓库中同名的目录并不会配置基础路径。
|
||
- 转发完整的 `<base-path>/*` 路由，或在细粒度允许列表中添加 `<base-path>/_llms/*`。
|
||
- 重新部署文档，然后同时验证 `<base-path>/llms.txt` 和一个链接的 `<base-path>/_llms/*.md` URL。
|
||
|
||
<div id="performance-issues">
|
||
### 性能问题
|
||
</div>
|
||
|
||
**症状**：页面加载缓慢，出现布局位移。
|
||
|
||
**原因**：缓存配置不正确。
|
||
|
||
**解决方案**：为文档路径禁用缓存。如果你代理了 `/mintlify-assets/_next/static/*` 路径，仅对这些静态资源启用缓存。
|