一、先说结论:静态站点上的 CSP 是配置工程,不是编码工程
我给自己这台单机跑的几个站加过三轮内容安全策略,前两轮都以「改了、感觉没坏、过两天撤了」收场。第三轮才稳定下来,原因不是学会了什么高深写法,而是流程变了:先观测再拒绝,先只读再执行,先报告再拦截。如果你的站点是 WordPress、Typecho 或者任意 PHP 模板站,没有大量前端工程化设施,那么下面这套流程可以直接照抄,唯一需要改的是域名清单。
先把一个前提讲清楚。CSP 挡的是「浏览器执行了不该执行的代码」,挡不住「服务器把不该给的数据给出了」。上一批我写源站隐藏时反复强调过,CSP 属于纵深防御里最靠外的一层护栏,它的价值是当某个输出点漏了转义、某条第三方脚本被挂马、某个富文本编辑器被绕过时,浏览器还有一道自主决定权。它不能替代输出转义,也不能替代上传校验。把 CSP 当万能安全策略,最后一定是「开了、报了、关掉」三段式。
还有一个决定成败的前提:CSP 必须以响应头下发。写在 HTML 的 meta 标签里虽然也能生效,但只覆盖 script-src、style-src 这类资源指令,frame-ancestors 和 report-uri 在 meta 里被忽略,而且 meta 生效之前的那段 HTML 已经解析执行过了。我第一轮就是图省事写在模板 head 里,结果 frame-ancestors 完全不生效,白折腾了一晚。
二、三个头不是一回事:CSP、安全响应头与 iframe 限制的边界
很多人把几个头混成一个「安全头」概念,混着混着就配出了互相打架的组合。先分清各自的职责范围:
- Content-Security-Policy:决定页面里哪些资源可以加载、哪些内联代码可以执行、表单能提交到哪里、谁能把本页嵌进 iframe(
frame-ancestors)、混合内容如何处理(upgrade-insecure-requests)。它是这套头里能力最强、也最容易配错的一个。 - X-Frame-Options:只管一件事,能不能被嵌。取值只有 DENY / SAMEORIGIN 和早已废弃的 ALLOW-FROM。它和
frame-ancestors功能重叠,现代浏览器优先看 CSP,老浏览器只认 XFO,所以两个都保留是合理的,但两者的语义必须一致。我见过X-Frame-Options: SAMEORIGIN配frame-ancestors 'none'的组合,结果是新浏览器全禁、旧浏览器允许同源嵌,团队谁也说不清到底允不允许。 - X-Content-Type-Options: nosniff:禁止浏览器按内容猜测类型。这一条几乎没有副作用,属于「不加没道理」的级别。
- Referrer-Policy:控制跨站跳转时带多少来源信息。对个人站尤其重要,因为上游图片、统计、广告脚本都会拿走 referer。
- Permissions-Policy:关掉不需要的硬件与浏览器能力(摄像头、麦克风、地理位置、剪贴板读取)。它的默认值在补丁版本之间还会变,显式写出来只花一行。
- HSTS:上一批已经成篇讲过,属于传输层的「写完就收不回」的那一类,和 CSP 不同批次上线,不要放在同一次变更里做。
把这几个头分开配置,最直接的好处是:出问题时能定位到具体某一个头。全塞在一行里,回滚时你根本不知道自己撤掉的是哪一条保护。
三、add_header 的整组替换:为什么配了却看不到头
CSP 配了不生效,我在站上实际遇到的原因八成是同一个:Nginx 的 add_header 继承规则。只要某个 location 里出现了一条 add_header,父级(server、http)的所有 add_header 全部失效,不是合并,是整组替换。这条规则和常见的「子块会继承父块」直觉完全相反,而且它不报错。
我给一个真实的翻车现场。http 块里写了五条安全头,然后在图片缓存那个 location 里加了一句 add_header Cache-Control "public, max-age=31536000" 想延长缓存。改完那个 location 的五条安全头就全没了,但因为静态图片本身不需要 CSP 执行,谁也没发现,直到有一次安全扫描报告里同一个目录下的 PDF 文件既没 nosniff 也没 CSP,才知道漏了。上一批讲静态缓存时提过这个坑,这次把它补成完整写法:
# 反例:location 里有 add_header,父级五条安全头全部失效
location ~* \.(jpg|png|webp|css|js)$ {
add_header Cache-Control "public, max-age=31536000";
}
# 正例:用 include 把安全头在需要的每一层都带进来
# /etc/nginx/snippets/security-headers.conf
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
add_header Content-Security-Policy-Report-Only "default-src 'self'; script-src 'self'" always;
location ~* \.(jpg|png|webp|css|js)$ {
include snippets/security-headers.conf;
add_header Cache-Control "public, max-age=31536000";
}另一个细节是 always 参数。不加它,add_header 只在状态码为 200、201、204、206、301、302、303、304、307、308 时才下发。也就是说 404 页面、500 错误页、被 403 拦掉的请求都不会带头。而错误页恰恰是最该有 CSP 的地方——模板出错时容易把未渲染的源码或错误栈吐出去。所有安全头的 add_header 一律加 always,这是硬规则。
验证方法很简单,一次 curl 拿全:
curl -sS -D - -o /dev/null "https://www.example.com/" | grep -i -E 'content-security|x-frame|x-content|referrer|permissions'
curl -sS -D - -o /dev/null "https://www.example.com/not-exist-page" | grep -i 'content-security'
curl -sS -D - -o /dev/null "https://www.example.com/static/app.js" | grep -i -E 'content-security|cache-control'三条都出结果才算真的配上了。只有首页有、错误页和静态资源没有,就是 add_header 被整组替换的典型症状。
四、第一轮只开 Report-Only:把违规报告当成一门数据课
直接上强制模式是我第二轮失败的原因。当时想把 default-src 直接锁到 'self',改完当天站点看起来正常,因为被拦掉的是「不明显」的东西:一个内联的事件处理属性、一个统计脚本的二次加载、一个字体文件的跨域请求。三天后陆续有人反馈评论发不出去、图看不全,我才灰溜溜地全站撤掉。
正确做法是 Content-Security-Policy-Report-Only,它只报告不拦截。把它挂上去,然后耐心等一到两周。这一周要做的事只有一件:搞清楚你的站点到底依赖多少第三方与多少内联。
报告收集有个现实问题:个人站没有现成的报告平台,也不想为了 CSP 报告去搭一套 Sentry。我的做法是在站点根目录放一个极简的接收脚本,收 application/csp-report 与更新的 application/reports+json 两种 Content-Type,落到每天一个文件里,供后续聚合。要点有四条:
- 限行长度。一条违规报告动辄一两千字节,恶意或被污染的报告可以把目录放大到几个 G。落盘前按 4KB 截断,超长直接丢弃。
- 必须限速。报告接口是公网可写的,必须在 Nginx 层按 IP 限速,否则它就是一个免费的日志写入放大器。
- 目录必须在 web 根之外,文件名里不要含任何用户可控内容,路径按日期生成。
- 只存不改。接收端绝不做任何解析失败就报错的逻辑,一律回 204。
Nginx 侧的两行配置能挡住大半滥用:
location = /csp-report {
limit_req zone=cspreports burst=5 nodelay;
client_max_body_size 64k;
include fastcgi_params;
fastcgi_pass unix:/run/php/php-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root/csp-report.php;
}限速区在 http 块里定义,例如 limit_req_zone $binary_remote_addr zone=cspreports:10m rate=10r/m;。一分钟十条对一个正常访客足够,对脚本刷报告则太慢。
五、报告怎么聚合:按类型分组,别按时间读
一周攒下来通常是几万条原始报告,直接看没法看。真正有用的是三个维度的聚合:
- 按 violated-directive 分组计数。这一栏告诉你最该先处理的是哪条指令。如果
script-src-elem占九成,说明第三方脚本是主要矛盾;如果style-src-attr占九成,说明模板里有大量内联 style 属性,需要换成 class。 - 按 blocked-uri 的主机名分组。这一栏告诉你到底要放行哪些域名。这里有个坑:
blocked-uri常常是inline、eval、data这类伪值,不是 URL,聚合时要先分类再取主机名,否则统计结果一片空白让人误以为没问题。 - 按页面路径分组。哪一个模板引入了最多违规,一目了然。通常是评论框、分享按钮、广告位三个位置。
用一条 awk 就能出前两个维度,不需要写分析系统:
cat csp-2026-11-*.json | grep -oE '"violated-directive":"[^"]+"' | sort | uniq -c | sort -rn | head -20
cat csp-2026-11-*.json | grep -oE '"blocked-uri":"[^"]+"' | sort | uniq -c | sort -rn | head -30聚合完成后的判断标准很粗暴:当某一类违规连续三天为 0,就可以把对应指令从 Report-Only 挪进强制列表。不要一次性把整条策略从报告切到强制,按指令分批切,每次只切一两条,出问题第一时间知道是谁。
六、内联脚本的哈希怎么算准:两行命令与三个返工点
报告里出现 script-src-attr 或 script-src-elem 违规,且 blocked-uri 是 inline,说明有内联脚本。业余站点的正确顺序不是「先上 'unsafe-inline'」,而是先判断这个内联脚本有没有被注入的可能:
- 模板里写死的、内容完全静态的内联脚本 → 用哈希(
'sha256-...')放行,这是最干净的方式。 - 内容里由用户输入拼接出来的内联脚本 → 它本身就是 XSS 风险点,正确做法是重构掉,而不是加 nonce 或哈希。
- 第三方给的嵌入片段(统计、广告、客服) → 要么外链成文件加域名白名单,要么用 nonce,不要在模板里保留
'unsafe-inline'。
哈希算不准是最常见的返工点,因为浏览器的哈希对象在浏览器里和你想象的不一样:
# 对脚本正文取哈希,注意前后不能有额外空白
printf '%s' '(function(){var a=1;})();' | openssl dgst -sha256 -binary | openssl base64 -A两个必须知道的规则。第一,哈希针对的是标签内部的内容,不包含 script 标签本身;第二,浏览器不会帮你去掉首尾空白,模板里一个手滑的空格或换行,哈希就对不上。实测时最稳的做法不是手动算,而是在浏览器里让它自己报出来:先故意把哈希写错,报告里会带上 script-sample 或直接告诉你哪一条不匹配,把正确值复制回来即可。我第一次手算三个哈希全错,就是因为模板里有两个换行。
nonce 方案在静态站和整页缓存下会踩死。这一点必须单独强调:nonce 必须每次响应唯一,如果你的页面被 CDN 或反向代理缓存,同一个 nonce 会发给所有访客,等于没有效力;更糟的是缓存可能把带 nonce 的页面发给后来者,而 policy 头来自另一个响应,两侧对不上,全站脚本被拦。所以:页面有整页缓存时用哈希,不用 nonce。这也是我把这套方案定为「哈希优先」的原因。
七、第三方与广告:把白名单当成一份需要维护的资产
报告里第二多的往往是第三方域名。这里的原则是:白名单越短越好,但必须写全写细,允许写宽反而更危险。
- 不要写成
https:。「允许所有 https 脚本」是给攻击者开的一道门:只要能注入一个指向任意 https 地址的 script 标签,CSP 就形同虚设。这一条我见过太多人为了省事加上。 - 统计脚本通常需要多个域名。以常见统计为例,加载脚本、上报数据、下发配置常常是不同主机,报告会一个一个告诉你,照着加就行。
- 广告位是白名单膨胀的主要来源。广告脚本必然会再加载别的脚本,形成链式依赖。可行的做法是给广告单独一个容器 iframe(配合
child-src或frame-src白名单),让广告脚本的加载发生在 iframe 自己的 document 里,不去污染主文档的 CSP。这个改法比无脑放行十几个域名干净得多。 - 把自己站点的静态资源走同一域名。如果历史原因用过 CDN 域名,那就把 CDN 域名写进白名单,同时确保它不会成为新的内容注入点。
白名单本身要当成配置资产来管:写在 nginx/snippets/security-headers.conf 里进 Git,每次增加域名都在提交信息里写明原因与报告依据。半年后回头看,你能知道每一条是谁为什么加的,也就敢删。没有这份依据的白名单,只会越来越长,最后被迫改成 script-src *。
八、上线后的验收:六个动作,一条都不能省
策略切到强制模式之后,我固定做六件事:
- 三个页面类型的头都要看:首页、文章页、404 页。命令见第三节。
- 实测一个受保护的动作。评论提交、搜索、登录,各点一次。很多站点评论区用的是第三方,CSP 一严格就静默失败,页面看起来正常但提交无反应。
- 看浏览器控制台,不是只看页面。被拦的脚本在页面上表现往往是「某个功能点了没反应」,只有控制台有那条红色拒绝信息。用无痕窗口测一次,避免缓存与插件干扰。
- 确认报告接口还在收。切强制模式后违规应当大幅下降但不应归零;归零有两种可能,一种是真干净了,一种是报告接口挂了或限速过严,要去数文件字节数。
- 把策略头复制到测试站一份。下次改模板在测试站先看报告,比在线上试探安全得多。
- 写下回滚方法。
sed -i注释掉一行 +nginx -t+ reload 即可,但必须写清楚在哪个文件哪一行,出问题时不要现场找。
九、四个我已经踩过、希望你绕开的坑
坑一:CSP 和 CDN 各下发一份头。源站加了 CSP,CDN 面板里也有一个「安全头」开关,结果是响应里出现两条 Content-Security-Policy,浏览器按取交集处理,两边一不一致就是各种莫名其妙的功能失效。curl -D - 出来数一下同名头的条数,必须只有一条。
坑二:只给首页加了策略。用 location = / 精确匹配只覆盖首页,文章页走的是另一条规则。安全头应该是全站默认行为,写法是放在 server 块(或 include 到每个 location),不是给某个路径加。
坑三:把 X-Frame-Options 当成嵌站限制的唯一手段。如果站点需要被某个合作方嵌入,XFO 只有 SAMEORIGIN 与 DENY 两个值,做不了白名单,只能用 frame-ancestors 指定来源。反过来,允许被嵌的页面要单独配,不要让整站都放开。
坑四:改完不重载,或者重载了但 CDN 没刷。这听起来低级,但我第二次上线时确实遇到:Nginx reload 成功、源站 curl 正确、访客看到的还是旧头,因为 CDN 边缘缓存了响应头。验证顺序应该是:本机直连源站 IP 加 Host 头看一次,再走域名看一次,两次都对了才算上线。
十、小结:让 CSP 变成日常观察而不是一次性大工程
这套流程跑完三个站,我最大的收获不是记住了多少指令,而是把 CSP 从「一次性加固动作」变成了「日常观察的一栏」。现在的状态是:策略头统一放在 snippets 文件里进 Git;每周花五分钟看一眼报告文件的字节数与前十条违规;白名单每季度复查一次,删掉三个月没出现过的域名。整个过程没有一次上线事故,也没有一次被迫全站撤除。
如果你的站还没做过,建议的最小起点是:先只加 X-Content-Type-Options、Referrer-Policy、X-Frame-Options 与 Permissions-Policy 四个低风险的,再用一条 default-src 'self' 的 Report-Only 策略挂一周。等报告里的违规收敛到你认得出来的那几个来源,再谈强制。把顺序反过来,几乎一定会重演我前两轮的「开了又撤」。