mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
fbdd913d8e
* Add translation tracker for stale translations audit Generated-By: mintlify-agent * translations: add missing pages and update content for es, fr, zh Phase 1: Add translations for 4 new API analytics pages (feedback-by-page, searches, views, visitors) in es, fr, and zh. Phase 2: Update 3 pages with content changes: - agent/workflows: add "Disable a workflow" subsection - ai/skillmd: add 24-hour generation note - editor/publish: add AI PR title tip, reformat publishing workflows, promote "Publish your changes" heading from h3 to h2 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * update descriptions * translations * translations * translations * Delete TRANSLATION_TRACKER.md * translations * a * a * translations * translations * translations * translations * translations * translations * translations * translations * Update use-cases.mdx * translations * translations * Update ai-native.mdx * Update accordions.mdx * Update accordions.mdx * Update accordions.mdx * translations * translations * Update fonts.mdx * translations * translations: update SEO descriptions for es, fr, zh (150 pages) Update the description: frontmatter field across 150 pages × 3 languages to match the current English descriptions updated on 2026-03-31. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
119 lines
3.6 KiB
Plaintext
119 lines
3.6 KiB
Plaintext
---
|
||
title: "Cloudflare 防火墙故障排查"
|
||
description: "排查通过 Cloudflare Workers 提供 Mintlify 文档时被拦截的请求并解决 Cloudflare WAF 规则冲突。"
|
||
keywords: ["Cloudflare WAF", "firewall rules", "Bot Fight Mode", "403 errors"]
|
||
---
|
||
|
||
如果你的文档站点在运行几秒后出现 500 错误，或导航变慢，可能是 Cloudflare 防火墙拦截了对 Mintlify 资源的请求。
|
||
|
||
<div id="symptoms">
|
||
## 症状
|
||
</div>
|
||
|
||
- 文档页面起初能加载，但 30–60 秒后崩溃并返回 500 错误
|
||
- 页面间的客户端导航缓慢或异常
|
||
- 对 `/mintlify-assets/*` 路径的请求在浏览器控制台中显示 403 错误
|
||
- 来自 Cloudflare 的安全挑战提示“数据格式错误”或“可疑的 URL 模式”
|
||
|
||
<div id="root-cause">
|
||
## 根本原因
|
||
</div>
|
||
|
||
由于以下原因，Cloudflare 的 Web Application Firewall（WAF）和 Bot Fight Mode 可能会将 Mintlify 的资源请求判定为可疑：
|
||
|
||
- 编码的 URL 参数中包含多个“%”符号
|
||
- 含有特殊字符的较长 query 字符串
|
||
- 来自空闲标签页的自动化请求
|
||
|
||
<div id="solution">
|
||
## 解决方案
|
||
</div>
|
||
|
||
创建一条 Cloudflare 防火墙规则，将 Mintlify 资产排除在安全检查之外。
|
||
|
||
<div id="create-the-firewall-exception">
|
||
### 创建防火墙例外
|
||
</div>
|
||
|
||
1. 登录你的 [Cloudflare 控制台](https://dash.cloudflare.com/)
|
||
2. 选择你的 domain
|
||
3. 前往 **Security > WAF**
|
||
4. 选择 **Create rule**
|
||
5. 按以下设置配置规则：
|
||
|
||
**Rule name:** 允许 Mintlify 资源
|
||
|
||
**When incoming requests match:**
|
||
|
||
- Field: `Hostname`
|
||
- Operator: `equals`
|
||
- Value: `docs.yourdomain.com`（替换为你的实际文档 domain）
|
||
|
||
**And:**
|
||
|
||
- Field: `URI Path`
|
||
- Operator: `starts with`
|
||
- Value: `/mintlify-assets/`
|
||
|
||
**Then:**
|
||
|
||
- Action: `Skip`
|
||
- Select: `All remaining custom rules`、`Managed rules` 和 `Super Bot Fight Mode`
|
||
|
||
6. 启用 **Log** 以跟踪匹配的请求
|
||
7. 选择 **Deploy**
|
||
|
||
<div id="verify-the-rule">
|
||
### 验证规则
|
||
</div>
|
||
|
||
部署后：
|
||
|
||
1. 在浏览器中打开文档站点
|
||
2. 将页面闲置 2–3 分钟
|
||
3. 在各页面之间切换
|
||
4. 在浏览器控制台中检查是否出现 403 错误
|
||
|
||
如果问题仍然存在，请核对规则配置：
|
||
|
||
- 确保主机名与文档的 domain 完全一致
|
||
- 确认 URI 路径使用 `starts with`（而非 `contains`）
|
||
- 不要在路径的值中包含通配符（`*`）
|
||
- 确认该规则已启用并完成部署
|
||
|
||
<div id="common-mistakes">
|
||
## 常见错误
|
||
</div>
|
||
|
||
- 将 `contains` 运算符用于 `/mintlify-assets/*` - `*` 会被视为普通字符，而非通配符
|
||
- 对 URI Path 使用 `equals` - 这只会匹配精确路径 `/mintlify-assets/`，不匹配子路径
|
||
- 忘记跳过 Bot Fight Mode - 必须在 skip 操作中显式包含
|
||
- 主机名错误 - 必须与实际的文档 domain 完全匹配
|
||
|
||
<div id="additional-troubleshooting">
|
||
## 其他故障排除
|
||
</div>
|
||
|
||
如果防火墙例外未能解决问题：
|
||
|
||
1. 在 Cloudflare 的 **Security > Events** 日志中检查被拦截的请求
|
||
2. 验证你的 Cloudflare Worker（若使用自定义子路径）是否正确转发了 `Host` 头
|
||
3. 暂时将 Security Level 设置为 “Essentially Off”，以确认问题是否由 Cloudflare 引起
|
||
4. 检查是否有自定义 Page Rules 会覆盖该防火墙例外
|
||
|
||
<div id="example-working-configuration">
|
||
## 可用配置示例
|
||
</div>
|
||
|
||
```
|
||
规则:允许 Mintlify 资源
|
||
状态:已启用
|
||
|
||
当传入请求匹配时:
|
||
(http.host eq "docs.flashnet.xyz" and starts_with(http.request.uri.path, "/mintlify-assets/"))
|
||
|
||
然后:
|
||
跳过:所有剩余的自定义规则、托管规则、超级机器人对抗模式
|
||
日志:已启用
|
||
```
|