Headers

Headers 中间件管理请求头和响应头。

默认情况下，代理请求时会自动添加以下请求头：

属性	HTTP 请求头
客户端 IP	`X-Forwarded-For`, `X-Real-Ip`
主机	`X-Forwarded-Host`
端口	`X-Forwarded-Port`
协议	`X-Forwarded-Proto`
代理服务器主机名	`X-Forwarded-Server`

配置示例¶

为请求和响应添加头¶

以下示例为代理请求添加 X-Script-Name 头，并为响应添加 X-Custom-Response-Header 头。

结构化 (YAML)

http:
  middlewares:
    testHeader:
      headers:
        customRequestHeaders:
          X-Script-Name: "test"
        customResponseHeaders:
          X-Custom-Response-Header: "value"

结构化 (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    [http.middlewares.testHeader.headers.customRequestHeaders]
        X-Script-Name = "test"
    [http.middlewares.testHeader.headers.customResponseHeaders]
        X-Custom-Response-Header = "value"

容器标签

labels:
  - "traefik.http.middlewares.testHeader.headers.customrequestheaders.X-Script-Name=test"
  - "traefik.http.middlewares.testHeader.headers.customresponseheaders.X-Custom-Response-Header=value"

服务标签

{
  //...
  "Tags": [
    "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test",
    "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header=value"
  ]
}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    customRequestHeaders:
      X-Script-Name: "test"
    customResponseHeaders:
      X-Custom-Response-Header: "value"

添加与移除头¶

以下示例在代理请求时添加 X-Script-Name 头，并移除其 X-Custom-Request-Header 头，同时移除响应中的 X-Custom-Response-Header 头。

结构化 (YAML)

http:
  middlewares:
    testHeader:
      headers:
        customRequestHeaders:
          X-Script-Name: "test" # Adds
          X-Custom-Request-Header: "" # Removes
        customResponseHeaders:
          X-Custom-Response-Header: "" # Removes

结构化 (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    [http.middlewares.testHeader.headers.customRequestHeaders]
        X-Script-Name = "test" # Adds
        X-Custom-Request-Header = "" # Removes
    [http.middlewares.testHeader.headers.customResponseHeaders]
        X-Custom-Response-Header = "" # Removes

容器标签

labels:
  - "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
  - "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Custom-Request-Header="
  - "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header="

服务标签

{
  "Tags" : [
    "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test",
    "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Custom-Request-Header=",
    "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header="
  ]
}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    customRequestHeaders:
      X-Script-Name: "test" # Adds
      X-Custom-Request-Header: "" # Removes
    customResponseHeaders:
      X-Custom-Response-Header: "" # Removes

使用安全头¶

安全相关的头（例如 HSTS 头、浏览器 XSS 过滤器等）可以像上述自定义头一样管理。此功能可以通过添加头，轻松启用安全特性。

结构化 (YAML)

http:
  middlewares:
    testHeader:
      headers:
        frameDeny: true
        browserXssFilter: true

结构化 (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    frameDeny = true
    browserXssFilter = true

容器标签

labels:
  - "traefik.http.middlewares.testHeader.headers.framedeny=true"
  - "traefik.http.middlewares.testHeader.headers.browserxssfilter=true"

服务标签

{
  "Tags" : [
    "traefik.http.middlewares.testheader.headers.framedeny=true",
    "traefik.http.middlewares.testheader.headers.browserxssfilter=true"
  ]
}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    frameDeny: true
    browserXssFilter: true

CORS 头¶

CORS（跨源资源共享）头可以像上述自定义头一样添加和配置。此功能可快速设置更高级的安全特性。如果设置了 CORS 头，中间件不会将预检请求传递给任何服务，而是直接生成响应并返回给客户端。
请注意，以下示例不具有权威性，也未涵盖所有情况，不应直接照搬到生产环境。

结构化 (YAML)

http:
  middlewares:
    testHeader:
      headers:
        accessControlAllowMethods:
          - GET
          - OPTIONS
          - PUT
        accessControlAllowHeaders:
          - "*"
        accessControlAllowOriginList:
          - https://foo.bar.org
          - https://example.org
        accessControlMaxAge: 100
        addVaryHeader: true

结构化 (TOML)

[http.middlewares]
  [http.middlewares.testHeader.headers]
    accessControlAllowMethods = ["GET", "OPTIONS", "PUT"]
    accessControlAllowHeaders = [ "*" ]
    accessControlAllowOriginList = ["https://foo.bar.org","https://example.org"]
    accessControlMaxAge = 100
    addVaryHeader = true

容器标签

labels:
  - "traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT"
  - "traefik.http.middlewares.testheader.headers.accesscontrolallowheaders=*"
  - "traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org"
  - "traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100"
  - "traefik.http.middlewares.testheader.headers.addvaryheader=true"

服务标签

{
  "Tags" : [
    "traefik.http.middlewares.testheader.headers.accesscontrolallowmethods=GET,OPTIONS,PUT",
     "traefik.http.middlewares.testheader.headers.accesscontrolallowheaders=*",
    "traefik.http.middlewares.testheader.headers.accesscontrolalloworiginlist=https://foo.bar.org,https://example.org",
    "traefik.http.middlewares.testheader.headers.accesscontrolmaxage=100",
    "traefik.http.middlewares.testheader.headers.addvaryheader=true"
  ]
}

Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    accessControlAllowMethods:
      - "GET"
      - "OPTIONS"
      - "PUT"
    accessControlAllowHeaders:
      - "*"
    accessControlAllowOriginList:
      - "https://foo.bar.org"
      - "https://example.org"
    accessControlMaxAge: 100
    addVaryHeader: true

配置选项¶

警告

如果自定义头与已有的头同名，将覆盖已有值。

安全头的详细文档参阅 unrolled/secure。

字段	说明	默认值	必填
`customRequestHeaders`	列出请求头的名称和值。	[]	否
`customResponseHeaders`	列出响应头的名称和值。	[]	否
`accessControlAllowCredentials`	指示请求是否可以包含用户凭据。	false	否
`accessControlAllowHeaders`	指定允许的请求头名称。	[]	否
`accessControlAllowMethods`	指定允许的请求方法。	[]	否
`accessControlAllowOriginList`	指定允许的来源。更多信息见此处。	[]	否
`accessControlAllowOriginListRegex`	允许匹配正则表达式的来源。更多信息见此处。	[]	否
`accessControlExposeHeaders`	指定在 CORS API 规范中，可以安全地向 API 暴露哪些头。	[]	否
`accessControlMaxAge`	预检请求的缓存时长，单位为秒。	0	否
`addVaryHeader`	与 `accessControlAllowOriginList` 配合使用，决定是否添加或修改 `Vary` 头，以表明服务器响应可能随 origin 头值的不同而变化。	false	否
`allowedHosts`	列出允许的域名。	[]	否
`hostsProxyHeaders`	指定代理主机名的头名称。	[]	否
`sslProxyHeaders`	定义一组头名称及其对应值，用于表示有效的 HTTPS 请求。使用其他代理时可能很有用（例如：`"X-Forwarded-Proto": "https"`）。	{}	否
`stsSeconds`	`Strict-Transport-Security` 头的最大有效期。	-	否
`stsIncludeSubdomains`	设置为 `true` 时，将 `includeSubDomains` 指令追加到 `Strict-Transport-Security` 头。	false	否
`stsPreload`	为 STS 头添加 preload 标志。	false	否
`forceSTSHeader`	为 HTTP 连接添加 STS 头。	false	否
`frameDeny`	将 `frameDeny` 设置为 `true`，可添加值为 `DENY` 的 `X-Frame-Options` 头。	false	否
`customFrameOptionsValue`	允许为 `X-Frame-Options` 头设置自定义值。这会覆盖 `FrameDeny` 选项。	""	否
`contentTypeNosniff`	将 `contentTypeNosniff` 设置为 true，可添加值为 `nosniff` 的 `X-Content-Type-Options` 头。	false	否
`browserXssFilter`	将 `browserXssFilter` 设置为 true，可添加值为 `1; mode=block` 的 `X-XSS-Protection` 头。	false	否
`customBrowserXSSValue`	允许为 `X-XSS-Protection` 头设置自定义值。这会覆盖 `BrowserXssFilter` 选项。	""	否
`contentSecurityPolicy`	允许为 `Content-Security-Policy` 头设置自定义值。	""	否
`contentSecurityPolicyReportOnly`	允许为 `Content-Security-Policy-Report-Only` 头设置自定义值。	""	否
`publicKey`	实现 HPKP 证书固定。	""	否
`referrerPolicy`	控制 `Referer` 头的转发。	""	否
`permissionsPolicy`	允许站点控制浏览器功能。	""	否
`isDevelopment`	开发时设置为 `true`，可减轻 `AllowedHosts`、SSL 和 STS 选项产生的非预期影响。测试通常使用 HTTP 而非 HTTPS，并在 `localhost` 上进行，而非生产域名。	false	否

`accessControlAllowOriginList` 允许的来源列表¶

accessControlAllowOriginList 通过返回不同的值，指示资源是否可以共享。

也可以配置通配来源 *，匹配所有请求。如果后端服务设置了此值，Traefik 会覆盖它。

此值可以包含允许的来源列表。

包括配置使用方法在内的更多信息，参阅：

Traefik 不再支持 null 值，因为已不再建议返回此值。

`accessControlAllowOriginListRegex` 允许的来源正则表达式列表¶

accessControlAllowOriginListRegex 对应 accessControlAllowOriginList 选项，但使用正则表达式而非来源值。它允许包含 accessControlAllowOriginList 中任意正则表达式匹配结果的所有来源。

提示

可以使用 Go Playground 或 Regex101 等在线工具测试正则表达式和替换规则。

在 YAML 中定义正则表达式时，任何需要转义的字符都必须转义两次：example\.com 应写成 example\\.com。

在生产环境使用 Traefik OSS？

如果你在工作中使用 Traefik，可以考虑为 Traefik OSS 增加企业级 API 网关能力或商业支持。

为 Traefik OSS 增加 API 网关能力快捷且平滑，无需推倒重来，现有配置也会完整保留。请通过这个简短视频了解实际效果。

Headers

配置示例¶

为请求和响应添加头¶

添加与移除头¶

使用安全头¶

CORS 头¶

配置选项¶

accessControlAllowOriginList 允许的来源列表¶

accessControlAllowOriginListRegex 允许的来源正则表达式列表¶

`accessControlAllowOriginList` 允许的来源列表¶

`accessControlAllowOriginListRegex` 允许的来源正则表达式列表¶