跳转至

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.3.0，于 2026 年 2 月 15 日发布。

此 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
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 的重要说明

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

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

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

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

主要特性

  • 即插即用：默认的安全头部集可以通过在 NGINX 配置中设置 security_headers on; 启用
  • 仅为相关类型发送 HTML 安全头部，不会为其他类型发送，例如 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
  • Referrer-Policy: strict-origin-when-cross-origin
  • X-Content-Type-Options: nosniff
  • Cross-Origin-Resource-Policy: same-site

默认情况下，已弃用的 X-XSS-Protection 头部会被主动移除。

这些头部的值（或其包含）可以通过下面的其他 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 | unset
  • 默认: unset
  • 上下文: http, server, location

控制 X-XSS-Protection 头部。

  • unset（默认）：主动从响应中移除该头部，包括任何由上游服务器设置的头部。这是推荐的设置，因为该头部已被弃用并且在支持它的浏览器中引入了 XSS 漏洞。
  • omit：不添加或移除该头部；允许上游头部不变。
  • off：发送 X-XSS-Protection: 0 明确禁用浏览器 XSS 过滤。
  • on：发送 X-XSS-Protection: 1。
  • block：发送 X-XSS-Protection: 1; mode=block。

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 仓库 中找到此模块的其他配置提示和文档。