mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
6cd516c819
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
158 lines
7.3 KiB
Plaintext
158 lines
7.3 KiB
Plaintext
---
|
||
title: "内容安全策略（CSP）配置"
|
||
sidebarTitle: "CSP 配置"
|
||
description: "配置 CSP 标头，在严格安全策略（如反向代理、防火墙和受限网络）下允许加载 Mintlify 资源，同时保持安全性。"
|
||
keywords: ["内容安全策略", "CSP 指令", "安全标头", "XSS 防护"]
|
||
---
|
||
|
||
内容安全策略（CSP）是一项安全标准，通过控制网页可加载的资源来帮助防止跨站脚本（XSS）攻击。Mintlify 提供了默认的 CSP，可保护大多数站点。如果你在反向代理或防火墙后托管文档，并覆盖了默认的 CSP，则可能需要配置 CSP 标头以确保各项功能正常运行。
|
||
|
||
<div id="csp-directives">
|
||
## CSP 指令
|
||
</div>
|
||
|
||
以下 CSP 指令用于控制可加载的资源：
|
||
|
||
- `script-src`：控制可执行的脚本
|
||
- `style-src`：控制可加载的样式表
|
||
- `font-src`：控制可加载的字体
|
||
- `img-src`：控制可加载的图像、图标和徽标
|
||
- `connect-src`：控制可用于 API 调用和 WebSocket 连接的 URL
|
||
- `frame-src`：控制可在 frame 或 iframe 中嵌入的 URL
|
||
- `default-src`：未显式设置其他指令时的回退项
|
||
|
||
<div id="domain-whitelist">
|
||
## 域名白名单
|
||
</div>
|
||
|
||
| 域名 | 用途 | CSP 指令 | 是否必需 |
|
||
|:-------|:--------|:--------------|:-------|
|
||
| `d4tuoctqmanu0.cloudfront.net` | KaTeX CSS、字体 | `style-src`, `font-src` | 必需 |
|
||
| `*.mintlify.dev` | 文档内容 | `connect-src`, `frame-src` | 必需 |
|
||
| `*.mintlify.com` | 控制台、API、分析代理 | `connect-src` | 必需 |
|
||
| `leaves.mintlify.com` | AI 助手 API | `connect-src` | 必需 |
|
||
| `d3gk2c5xim1je2.cloudfront.net` | 图标、图像、徽标 | `img-src` | 必需 |
|
||
| `d1ctpt7j8wusba.cloudfront.net` | Mint 版本与发行文件 | `connect-src` | 必需 |
|
||
| `mintcdn.com` | 图像、网站图标 | `img-src`, `connect-src` | 必需 |
|
||
| `*.mintcdn.com` | 图像、网站图标 | `img-src`, `connect-src` | 必需 |
|
||
| `api.mintlifytrieve.com` | 搜索 API | `connect-src` | 必需 |
|
||
| `cdn.jsdelivr.net` | OG 图片的表情资源 | `script-src`, `img-src` | 必需 |
|
||
| `mintlify.s3.us-west-1.amazonaws.com` | 托管在 S3 上的图像 | `img-src` | 必需 |
|
||
| `fonts.googleapis.com` | Google 字体 | `style-src`, `font-src` | 可选 |
|
||
| `www.googletagmanager.com` | Google Analytics/GTM | `script-src`, `connect-src` | 可选 |
|
||
| `cdn.segment.com` | Segment 分析 | `script-src`, `connect-src` | 可选 |
|
||
| `plausible.io` | Plausible 分析 | `script-src`, `connect-src` | 可选 |
|
||
| `us.posthog.com` | PostHog 分析 | `connect-src` | 可选 |
|
||
| `tag.clearbitscripts.com` | Clearbit 追踪 | `script-src` | 可选 |
|
||
| `cdn.heapanalytics.com` | Heap 分析 | `script-src` | 可选 |
|
||
| `chat.cdn-plain.com` | Plain 聊天小部件 | `script-src` | 可选 |
|
||
| `chat-assets.frontapp.com` | Front 聊天小部件 | `script-src` | 可选 |
|
||
| `browser.sentry-cdn.com` | Sentry 错误监控 | `script-src`, `connect-src` | 可选 |
|
||
| `js.sentry-cdn.com` | Sentry JavaScript SDK | `script-src` | 可选 |
|
||
|
||
<div id="example-csp-configuration">
|
||
## 示例 CSP 配置
|
||
</div>
|
||
|
||
<Note>
|
||
仅包含你实际使用的服务的 domain。删除你尚未为文档配置的任何 Analytics 相关 domain。
|
||
</Note>
|
||
|
||
```text wrap
|
||
Content-Security-Policy:
|
||
default-src 'self';
|
||
script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net www.googletagmanager.com cdn.segment.com plausible.io
|
||
us.posthog.com tag.clearbitscripts.com cdn.heapanalytics.com chat.cdn-plain.com chat-assets.frontapp.com
|
||
browser.sentry-cdn.com js.sentry-cdn.com;
|
||
style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com;
|
||
font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com;
|
||
img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net mintlify.s3.us-west-1.amazonaws.com;
|
||
connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com
|
||
api.mintlifytrieve.com www.googletagmanager.com cdn.segment.com plausible.io us.posthog.com browser.sentry-cdn.com;
|
||
frame-src 'self' *.mintlify.dev;
|
||
```
|
||
|
||
|
||
<div id="common-configurations-by-proxy-type">
|
||
## 按代理类型划分的常见配置
|
||
</div>
|
||
|
||
大多数反向代理都支持添加自定义请求头。
|
||
|
||
<div id="cloudflare-configuration">
|
||
### Cloudflare 配置
|
||
</div>
|
||
|
||
创建一个 Response Header Transform 规则：
|
||
|
||
1. 在 Cloudflare 控制台，进入 **Rules > Overview**。
|
||
2. 选择 **Create rule > Response Header Transform Rule**。
|
||
3. 配置该规则：
|
||
|
||
- **Modify response header**：设置为 static
|
||
- **Header name**：`Content-Security-Policy`
|
||
- **Header value**：
|
||
```text wrap
|
||
default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net mintlify.s3.us-west-1.amazonaws.com; connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com api.mintlifytrieve.com; frame-src 'self' *.mintlify.dev;
|
||
```
|
||
|
||
4. 部署该规则。
|
||
|
||
<div id="aws-cloudfront-configuration">
|
||
### AWS CloudFront 配置
|
||
</div>
|
||
|
||
在 CloudFront 中添加一个响应标头策略：
|
||
|
||
```json
|
||
{
|
||
"ResponseHeadersPolicy": {
|
||
"Name": "MintlifyCSP",
|
||
"Config": {
|
||
"SecurityHeadersConfig": {
|
||
"ContentSecurityPolicy": {
|
||
"ContentSecurityPolicy": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net mintlify.s3.us-west-1.amazonaws.com; connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com api.mintlifytrieve.com; frame-src 'self' *.mintlify.dev;",
|
||
"Override": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
<div id="vercel-configuration">
|
||
### Vercel 配置
|
||
</div>
|
||
|
||
将以下内容添加到你的 `vercel.json`：
|
||
|
||
```json
|
||
{
|
||
"headers": [
|
||
{
|
||
"source": "/(.*)",
|
||
"headers": [
|
||
{
|
||
"key": "Content-Security-Policy",
|
||
"value": "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; font-src 'self' d4tuoctqmanu0.cloudfront.net fonts.googleapis.com; img-src 'self' data: blob: d3gk2c5xim1je2.cloudfront.net mintcdn.com *.mintcdn.com cdn.jsdelivr.net mintlify.s3.us-west-1.amazonaws.com; connect-src 'self' *.mintlify.dev *.mintlify.com d1ctpt7j8wusba.cloudfront.net mintcdn.com *.mintcdn.com api.mintlifytrieve.com; frame-src 'self' *.mintlify.dev;"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
|
||
<div id="troubleshooting">
|
||
## 疑难解答
|
||
</div>
|
||
|
||
在浏览器控制台中定位 CSP 违规：
|
||
|
||
1. 打开浏览器的开发者工具。
|
||
2. 切换到 **Console** 标签页。
|
||
3. 查找以下前缀的错误信息：
|
||
- `Content Security Policy: The page's settings blocked the loading of a resource`
|
||
- `Refused to load the script/stylesheet because it violates the following Content Security Policy directive`
|
||
- `Refused to connect to because it violates the following Content Security Policy directive` |