跳转至

security-headers: 用于发送安全头的 NGINX 模块

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

  • RedHat Enterprise Linux 7、8、9 和 10
  • CentOS 7、8、9
  • AlmaLinux 8、9
  • Rocky Linux 8、9
  • Amazon Linux 2 和 Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-security-headers

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-security-headers

通过在 /etc/nginx/nginx.conf 的顶部添加以下内容来启用该模块：

load_module modules/ngx_http_security_headers_module.so;

本文档描述了 nginx-module-security-headers v0.2.0，于 2026 年 2 月 3 日发布。

此 NGINX 模块以 正确的方式 (c) 添加安全头并移除不安全的头。

Test Build

概述

http {
    security_headers on;
    ...
}

运行 curl -IL https://example.com/ 将返回添加的安全头：

HTTP/1.1 200 OK
Server: nginx
Date: Tue, 21 May 2019 16:15:46 GMT
Content-Type: text/html; charset=UTF-8
Vary: Accept-Encoding
Accept-Ranges: bytes
Connection: keep-alive
X-Frame-Options: SAMEORIGIN
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Referrer-Policy: strict-origin-when-cross-origin
Cross-Origin-Resource-Policy: same-site
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

一般而言，该模块以更符合标准的方式发送安全 HTTP 头。例如，Strict-Transport-Security 头不应针对普通 HTTP 请求发送。该模块遵循这一建议。

关于 Strict-Transport-Security 的重要说明

该模块添加了多个安全头，包括 Strinct-Transport-Security。请注意，默认情况下，此头的值中会发送 preload。这意味着 Chrome 可能会将您的网站添加到其仅支持 HTTPS 的预加载域列表中。

这通常是您想要的，但请记住，在某些边缘情况下，您可能希望通过普通未加密的连接访问子域。

如果您完全确定与该模块一起使用的所有域和子域将主要在 HTTPS 上运行，则可以继续而无需额外步骤。

如果您 不确定 是否需要通过普通不安全的 HTTP 协议访问您的网站或其任何子域，请确保在启动 NGINX 之前在配置中设置 security_headers_hsts_preload off;，以避免您的域被 Chrome 预加载。

主要特性

  • 即插即用：可以通过在 NGINX 配置中设置 security_headers on; 来启用默认的安全头集
  • 仅针对相关类型发送 HTML-only 安全头，不会针对其他类型发送，例如 X-Frame-Options 对 CSS 是无用的
  • 与条件 GET 请求良好配合：安全头不会不必要地包含在其中
  • 不受 add_header 指令的缺陷影响
  • 隐藏 X-Powered-By 和其他常常泄露软件版本信息的头
  • 完全隐藏 Server 头，而不仅仅是版本信息

配置指令

security_headers

  • 语法: security_headers on | off
  • 默认值: off
  • 上下文: http, server, location

启用或禁用应用安全头。默认集包括：

  • X-Frame-Options: SAMEORIGIN
  • X-XSS-Protection: 0
  • Referrer-Policy: strict-origin-when-cross-origin
  • X-Content-Type-Options: nosniff
  • Cross-Origin-Resource-Policy: same-site

这些头的值（或其包含情况）可以通过下面的其他 security_headers_* 指令进行控制。

hide_server_tokens

  • 语法: hide_server_tokens on | off
  • 默认值: off
  • 上下文: http, server, location

启用隐藏泄露软件信息的头：

  • Server
  • X-Powered-By
  • X-Page-Speed
  • X-Varnish

值得注意的是，其中一些头具有功能性用途，例如 X-Page-Speed 文档 提到：

... 它用于防止在 PageSpeed 从也使用 PageSpeed 的源获取资源时出现无限循环和不必要的重写

因此，最好在面向外部的 NGINX 实例中指定 hide_server_tokens on;，例如实际浏览器访问的实例，而不是被 Varnish 或其他软件使用的实例。

在大多数情况下，您只需使用 security_headers on; 和 hide_server_tokens on;，无需任何调整。

要进行微调，请使用下面的特定于头的指令。特殊值 omit 禁用模块发送特定头（如果您希望让后端应用发送它）。

security_headers_xss

  • 语法: security_headers_xss off | on | block | omit
  • 默认值: off
  • 上下文: http, server, location

控制 X-XSS-Protection 头。特殊的 omit 值将禁用模块发送该头。off 值用于禁用 XSS 保护：X-XSS-Protection: 0。这是默认值，因为 现代浏览器不支持它，并且在支持的情况下，它引入了漏洞。

security_headers_frame

  • 语法: security_headers_frame sameorigin | deny | omit
  • 默认值: sameorigin
  • 上下文: http, server, location

控制 X-Frame-Options 头的包含和取值。特殊的 omit 值将禁用模块发送该头。

security_headers_referrer_policy

  • 语法: security_headers_referrer_policy no-referrer | no-referrer-when-downgrade | same-origin | origin | strict-origin | origin-when-cross-origin | strict-origin-when-cross-origin | unsafe-url | omit
  • 默认值: strict-origin-when-cross-origin
  • 上下文: http, server, location

控制 Referrer-Policy 头的包含和取值。特殊的 omit 值将禁用模块发送该头。

security_headers_corp

  • 语法: security_headers_corp same-site | same-origin | cross-origin | omit
  • 默认值: same-site
  • 上下文: http, server, location

控制 Cross-Origin-Resource-Policy 头的包含和取值。此头控制您的资源如何被其他源嵌入。特殊的 omit 值将禁用模块发送该头。

默认的 same-site 是一个安全的选择，可以防止跨站嵌入，同时允许同站请求。

security_headers_coop

  • 语法: security_headers_coop same-origin | same-origin-allow-popups | unsafe-none | omit
  • 默认值: omit
  • 上下文: http, server, location

控制 Cross-Origin-Opener-Policy 头的包含和取值。此头控制跨源的窗口打开者关系。特殊的 omit 值将禁用模块发送该头。

默认值为 omit，因为启用此头可能会破坏弹出窗口/window.opener 的通信模式。仅在您理解其影响时明确启用。

security_headers_coep

  • 语法: security_headers_coep require-corp | credentialless | unsafe-none | omit
  • 默认值: omit
  • 上下文: http, server, location

控制 Cross-Origin-Embedder-Policy 头的包含和取值。此头控制跨源资源的嵌入。特殊的 omit 值将禁用模块发送该头。

默认值为 omit，因为启用此头可能会破坏加载第三方资源（分析、CDN 资产、广告）而没有适当 CORS 头的站点。

跨源隔离

要启用 跨源隔离（这是 SharedArrayBuffer 和高分辨率定时器所需的），请配置所有三个跨源头：

security_headers on;
security_headers_corp same-origin;
security_headers_coop same-origin;
security_headers_coep require-corp;

警告：此配置将破坏加载任何未通过 CORS 明确允许的跨源资源。

GitHub

您可以在 nginx-module-security-headers 的 GitHub 仓库 中找到有关此模块的其他配置提示和文档。