首页
/ Traefik 入口点（EntryPoints）配置全解：监听地址、协议选择与 HTTP/TLS/HTTP3 行为定制

Traefik 入口点（EntryPoints）配置全解：监听地址、协议选择与 HTTP/TLS/HTTP3 行为定制

2026-09-04 11:11:16作者：凤尚柏Louis
traefik
The Cloud Native Application Proxy
项目地址：https://gitcode.com/GitHub_Trending/tr/traefik

Traefik 的 EntryPoint（入口点）是静态配置中定义“接收入站连接”的抽象：它决定 Traefik 监听哪个端口、使用 TCP 还是 UDP 协议，以及每个端口上的 HTTP 行为（重定向、TLS、中间件、超时、转发头信任等）。本文以 Traefik 官方文档 入口点配置参考 为主体，结合 静态配置结构体 与 服务器入口点实现 深入讲解每个配置项的含义、默认值与源码级行为，帮助你在部署时准确规划 80/443/8080/UDP 等各类入口点，并为 HTTP/3、PROXY protocol、reusePort 等进阶场景做出正确配置。

入口点是什么：接收连接的第一层抽象

在 Traefik 的路由与负载均衡体系中，EntryPoint 回答两个问题：哪个端口接收数据包、以及它们是 TCP 还是 UDP。每个入口点以名称标识（如 web、websecure），路由器（Router）通过 entryPoints 规则属性绑定到一个或多个入口点；未显式指定入口点的路由器则附着到“默认入口点列表”（见下文 asDefault 一节）。

从源码结构看，整个入口点体系由 pkg/config/static/entrypoints.go 中的 EntryPoint 结构体承载：

// EntryPoint holds the entry point configuration.
type EntryPoint struct {
    Address          string                `description:"Entry point address." ...`
    AllowACMEByPass  bool                  `description:"Enables handling of ACME TLS and HTTP challenges with custom routers." ...`
    ReusePort        bool                  `description:"Enables EntryPoints from the same or different processes listening on the same TCP/UDP port." ...`
    AsDefault        bool                  `description:"Adds this EntryPoint to the list of default EntryPoints to be used on routers that don't have any Entrypoint defined." ...`
    Transport        *EntryPointsTransport `description:"Configures communication between clients and Traefik." ...`
    ProxyProtocol    *ProxyProtocol        `description:"Proxy-Protocol configuration." ...`
    ForwardedHeaders *ForwardedHeaders     `description:"Trust client forwarding headers." ...`
    HTTP             HTTPConfig            `description:"HTTP configuration." ...`
    HTTP2            *HTTP2Config          `description:"HTTP/2 configuration." ...`
    HTTP3            *HTTP3Config          `description:"HTTP/3 configuration." ...`
    UDP              *UDPConfig            `description:"UDP configuration." ...`
    Observability    *ObservabilityConfig  `description:"Observability configuration." ...`
}

EntryPoints 本身是一个 map[string]*EntryPoint，即静态配置中 entryPoints 字段是“名称 → 配置”的映射。每个入口点在服务器启动时由 pkg/server/server_entrypoint_tcp.go 中的 NewTCPEntryPoints 遍历构建：先调用 GetProtocol() 解析地址中的协议部分，非 tcp 的条目（即 UDP 入口点）交由 UDP 入口点体系处理，TCP 条目则创建对应的 TCPEntryPoint 并逐个启动监听。

完整配置示例：YAML、TOML 与 Helm

一个典型的生产配置是：web（80 端口）永久重定向到 websecure（443 端口），并在 443 入口点上默认启用 TLS 与两个全局中间件。

YAML 静态配置：

entryPoints:
  web:
    address: :80
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
          permanent: true
    observability:
      accessLogs: false
      metrics: false
      tracing: false

  websecure:
    address: :443
    http:
      tls: {}
      middlewares:
        - default-auth@kubernetescrd
        - default-strip@kubernetescrd

TOML 静态配置（等价写法）：

[entryPoints]
  [entryPoints.web]
    address = ":80"
    [entryPoints.web.http]
      [entryPoints.web.http.redirections.entryPoint]
        to = "websecure"
        scheme = "https"
        permanent = true
    [entryPoints.web.observability]
      accessLogs = false
      metrics = false
      tracing = false

  [entryPoints.websecure]
    address = ":443"
    [entryPoints.websecure.http]
      middlewares = ["default-auth@kubernetescrd", "default-strip@kubernetescrd"]
      [entryPoints.websecure.http.tls]

Helm Chart Values 写法：

## Values file
ports:
  web:
    port: :80
  websecure:
    port: :443
    tls:
      enabled: true
    middlewares:
      - default-auth@kubernetescrd
      - default-strip@kubernetescrd
additionalArguments:
  - --entryPoints.web.http.redirections.entryPoint.to=websecure
  - --entryPoints.web.http.redirections.entryPoint.scheme=https
  - --entryPoints.web.http.redirections.entryPoint.permanent=true
  - --entryPoints.web.observability.accessLogs=false
  - --entryPoints.web.observability.metrics=false
  - --entryPoints.web.observability.tracing=false

提示：在 Helm Chart 中，web（端口 80）、websecure（端口 443）、traefik（端口 8080）与 metrics（端口 9100）这 4 个入口点默认即被创建；其中 web 与 websecure 默认通过 Service 对外暴露。上述默认行为都可以在 Helm Chart 中覆盖。

仓库中的示例配置文件 traefik.sample.toml 也给出了最小入口点定义：[entryPoints.web] address = ":80" 与 [entryPoints.websecure] address = ":443"，可直接作为静态配置的起点。

配置项总览（含默认值）

以下表格完整继承官方参考文档中的字段说明，默认值与 pkg/config/static/entrypoints.go 中各 SetDefaults() 方法一一对应。

基础选项

字段 说明 默认值 必填
address 定义监听入站连接与数据包的端口（可选主机名），同时定义使用的协议（TCP 或 UDP）。未指定协议时默认为 TCP。格式：[host]:port[/tcp|/udp] - 是
asDefault 标记该 entryPoint 进入默认入口点列表。该列表被用于（默认情况下）未定义自身 entryPoints 选项的 HTTP/TCP 路由器 false 否
allowACMEByPass 允许使用自定义路由器处理 ACME TLS 与 HTTP 验证，替代内部 ACME 路由器 false 否
reusePort 利用 SO_REUSEPORT 套接字选项，允许同一或不同进程中的入口点监听同一 TCP/UDP 端口；同时让内核像负载均衡器一样在入口点之间分发入站连接 false 否

地址中的协议部分由 GetProtocol() 解析：地址按 / 切分，缺失协议时返回 tcp，非法协议则报错，因此入口点启动失败会在构建阶段（NewTCPEntryPoints）以 error while building entryPoint %s 的形式暴露。

HTTP 行为（http.*）

字段 说明 默认值 必填
http.redirections.entryPoint.to 启用（永久）重定向的目标，可以是入口点名（如 websecure）或端口（如 :443） - 是（启用重定向时）
http.redirections.entryPoint.scheme 重定向使用的目标 scheme https 否
http.redirections.entryPoint.permanent 是否使用永久重定向 true 否
http.redirections.entryPoint.priority 附加到该入口点上路由器的默认优先级 MaxInt-1（32 位为 2147483646，64 位为 9223372036854775806） 否
http.encodedCharacters 定义请求路径中允许哪些编码字符（子项见“编码字符”一节） false（组开关） 否
http.encodedCharacters.allowEncodedSlash 是否允许路径中的编码斜杠 %2f/%2F true 否
http.encodedCharacters.allowEncodedBackSlash 是否允许编码反斜杠 %5c/%5C true 否
http.encodedCharacters.allowEncodedNullCharacter 是否允许编码空字符 %00 true 否
http.encodedCharacters.allowEncodedSemicolon 是否允许编码分号 %3b/%3B true 否
http.encodedCharacters.allowEncodedPercent 是否允许编码百分号 %25 true 否
http.encodedCharacters.allowEncodedQuestionMark 是否允许编码问号 %3f/%3F true 否
http.encodedCharacters.allowEncodedHash 是否允许编码井号 %23 true 否
http.encodeQuerySemicolons 启用查询串分号编码，避免未编码分号被 Traefik 当作查询参数分隔符；启用后未编码分号将以编码形式转发给后端 false 否
http.underscoreHeadersStrategy 处理带下划线请求头的策略：keep、delete、reject keep 否
http.sanitizePath 是否启用请求路径净化（/./、/../ 与多斜杠序列） true 否
http.maxHeaderBytes 请求头的最大字节数 1048576 否
http.middlewares 默认前置到该入口点上每个路由器的中间件列表（见“入口点级中间件”一节） - 否
http.tls 为附着到该入口点的每个路由器启用 TLS。未设置证书时会由 Traefik 生成自签默认证书（生产环境不建议使用自签证书） - 否
http.tls.options 为附着路由器应用默认 TLS 选项，可被各路由器覆盖。详见 TLS 选项文档 - 否
http.tls.certResolver 为附着路由器应用默认证书解析器，可被各路由器覆盖。详见证书解析器概览 - 否

默认值可以在源码中验证：HTTPConfig.SetDefaults() 设置 SanitizePath = new(true)、MaxHeaderBytes = http.DefaultMaxHeaderBytes（即 1048576）、UnderscoreHeadersStrategy = UnderscoreHeadersStrategyKeep；RedirectEntryPoint.SetDefaults() 设置 Scheme = "https"、Permanent = true、Priority = math.MaxInt - 1；EncodedCharacters.SetDefaults() 将全部 7 个编码字符开关置为 true。

HTTP/2 与 HTTP/3

字段 说明 默认值
http2.maxConcurrentStreams 每个连接中客户端允许发起的并发流数量，必须大于零 250
http2.maxDecoderHeaderTableSize 解码侧 HPACK 头压缩表的最大尺寸（控制服务器愿意维护的头缓存上限，对端可使用更小值） 4096
http2.maxEncoderHeaderTableSize 编码侧 HPACK 头压缩表的最大尺寸（控制服务端发送响应头时的头缓存上限） 4096
http3 在入口点启用 HTTP/3。HTTP/3 要求 TCP 入口点，因为 HTTP/3 总是先以 TCP 连接开始再升级到 UDP；多数场景下它与 TLS 流量使用同一入口点 -
http3.advertisedPort 作为 HTTP/3 authority 宣告的 UDP 端口，默认为入口点地址的端口；当对外端口与 Traefik 实际监听端口不同（如经端口映射）时，可用于覆盖 alt-svc 头中的 authority -

HTTP/2 的三项默认值在 HTTP2Config.SetDefaults() 中设定，注释还引用了 Go x/net http2 服务器中的对应默认值来源。

转发头信任（forwardedHeaders.*）

字段 说明 默认值
forwardedHeaders.connection 允许在移除前穿过中间件链的 Connection 头列表 -
forwardedHeaders.addXForwardedSchemeHeaders 在 X-Forwarded-Proto 之外额外添加兼容性头 X-Forwarded-Scheme 与 X-Scheme false
forwardedHeaders.insecure 信任所有来源的 X-Forwarded-* 信息。官方建议仅用于测试，不要用于生产 false
forwardedHeaders.trustedIPs 仅信任来自这些 IP 或 CIDR 的 X-Forwarded-* 信息 -
forwardedHeaders.notAppendXForwardedFor 设为 true 时，Traefik 不把客户端 RemoteAddr 追加到 X-Forwarded-For，已有头原样保留；无该头则不新增 false

PROXY protocol（proxyProtocol.*）

字段 说明 默认值
proxyProtocol.trustedIPs 对信任 IP 启用 PROXY protocol。Traefik 支持 PROXY protocol 1 与 2 两个版本。启用后该入口点可同时接受带与不带 PROXY protocol 头的连接，版本自动识别 -
proxyProtocol.insecure 信任所有入站连接的 PROXY protocol 头（trustedIPs 将失去作用）。官方建议仅用于测试 -

传输超时与生命周期（transport.*）

字段 说明 默认值
transport.respondingTimeouts.readTimeout 读取完整请求（含 body）的最大时长；对 UDP 入口点无效。为零表示无超时。可用 Go time.ParseDuration 格式或裸数字（视为秒） 60s
transport.respondingTimeouts.writeTimeout 响应写出的最大时长，覆盖从请求头读取结束到响应写出结束的区间。为零表示无超时 0s
transport.respondingTimeouts.idleTimeout 空闲（keep-alive）连接保持空闲多久后自行关闭。为零表示无超时 180s
transport.lifeCycle.graceTimeOut 停止前给予活跃请求完成的机会时长，期间不接收新请求 10s
transport.lifeCycle.requestAcceptGraceTimeout 在启动优雅终止（由 graceTimeOut 定义）之前继续接收请求的时长，用于给下游负载均衡器留出时间将 Traefik 摘除 0s
transport.keepAliveMaxRequests Traefik 在发送 Connection: Close（HTTP/2 下发送 GOAWAY）之前可处理的请求数上限。零表示不限制 0
transport.keepAliveMaxTime Traefik 在发送 Connection: Close（HTTP/2 下发送 GOAWAY）之前处理请求的最大时长。零表示不限制 0s
udp.timeout 空闲 UDP 会话释放相关资源前的等待时长，必须大于零 3s

上述默认值均可在 pkg/config/static/static_config.go 中逐一对应：DefaultGraceTimeout = 10 * time.Second、DefaultIdleTimeout = 180 * time.Second、DefaultReadTimeout = 60 * time.Second、DefaultUDPTimeout = 3 * time.Second，并分别在 RespondingTimeouts.SetDefaults()、LifeCycle.SetDefaults()、UDPConfig.SetDefaults() 中生效。

可观测性默认值（observability.*）

字段 说明 默认值
observability.accessLogs 附着到该入口点的路由器是否默认产生访问日志（路由器自身定义 observability 配置时会以此为准退出默认） true
observability.metrics 附着路由器是否默认产生 metrics true
observability.tracing 附着路由器是否默认产生 traces true
observability.traceVerbosity 附着路由器的 tracing 详细程度，取值 minimal（默认）或 detailed，路由器可用自身配置覆盖 minimal

traceVerbosity 的两种取值含义：

  • minimal：每个被路由器处理的请求产生一个 server span 和一个 client span；
  • detailed：为每个被执行的中间件额外创建 span。

默认值见 ObservabilityConfig.SetDefaults()：三项开关均为 new(true)，TraceVerbosity 为 otypes.MinimalVerbosity。

asDefault：默认入口点列表如何计算

当某个 HTTP/TCP 路由器没有声明自己的 entryPoints 时，它附着到“默认入口点列表”。规则如下：

  • 若没有任何入口点设置 asDefault: true，默认列表包含所有 HTTP/TCP 入口点；
  • 若至少有一个入口点设置 asDefault: true，默认列表只包含这些被标记的入口点；
  • 部分内置入口点始终被排除，即名为 traefik 的内部入口点；
  • asDefault 对 UDP 入口点无效——未定义 entryPoints 的 UDP 路由器会附着到所有可用的 UDP 入口点。

这段逻辑与 cmd/traefik/traefik.go 中 getDefaultsEntrypoints 的实现完全一致：

func getDefaultsEntrypoints(staticConfiguration *static.Configuration) []string {
    var defaultEntryPoints []string

    // Determines if at least one EntryPoint is configured to be used by default.
    var hasDefinedDefaults bool
    for _, ep := range staticConfiguration.EntryPoints {
        if ep.AsDefault {
            hasDefinedDefaults = true
            break
        }
    }

    for name, cfg := range staticConfiguration.EntryPoints {
        // By default all entrypoints are considered.
        // If at least one is flagged, then only flagged entrypoints are included.
        if hasDefinedDefaults && !cfg.AsDefault {
            continue
        }
        protocol, err := cfg.GetProtocol()
        if err != nil {
            log.Error().Err(err).Msg("Invalid protocol")
        }
        if protocol != "udp" && name != static.DefaultInternalEntryPointName {
            defaultEntryPoints = append(defaultEntryPoints, name)
        }
    }
    slices.Sort(defaultEntryPoints)
    return defaultEntryPoints
}

源码印证了三点：UDP 入口点（protocol != "udp" 的取反）被排除、名为 traefik 的内置入口点被排除、以及结果会按名称排序以保证确定性。

allowACMEByPass：让用户路由器接管 ACME 验证

默认情况下，Traefik 会创建一个具有最高优先级（MaxInt）的内部路由器来处理 ACME HTTP 与 TLS 验证，确保证书验证总能成功，但副作用是用户自定义路由器无法拦截同一入口点上的验证请求。

当在某入口点上设置 allowACMEByPass: true 时：

  • 内部 ACME HTTP 验证路由器创建时不再带显式高优先级，允许用户定义的路由器处理验证请求；
  • 该入口点上启用 TLS-ALPN 验证的透传，允许用户定义的 TLS 路由器处理 TLS 验证。

这在需要自定义 ACME 验证处理时很有用，例如使用专门的服务来解 HTTP-01 或 TLS-ALPN-01 验证。

两点值得注意：

  • 当未配置任何 TLS 验证解析器时，allowACMEByPass 会隐式地针对所有入口点的 TLS 透传生效；
  • 当 allowACMEByPass 启用且入口点配置了 HTTP 重定向（http.redirections.entryPoint）时，重定向路由器会自动排除 ACME 验证路径 /.well-known/acme-challenge/，使用户定义的 ACME 验证路由器不会因重定向而被绕过。

配置示例：

entryPoints:
  web:
    address: ":80"
    allowACMEByPass: true

[entryPoints.web]
  address = ":80"
  allowACMEByPass = true

--entryPoints.web.address=:80
--entryPoints.web.allowACMEByPass=true

入口点级中间件（http.middlewares）

  • 可以为每个入口点挂载一组中间件；
  • 中间件仅在 rule 匹配时生效，且在请求转发到服务之前执行；
  • 中间件按声明顺序依次应用；
  • 中间件默认应用于经由该入口点暴露的每个路由器（IngressRoute 或 Ingress 上声明的中间件会在入口点声明的中间件之后应用）；
  • 中间件必须使用全限定名引用，即包含 provider 命名空间 后缀的 <middleware-name>@<provider-name>，具体取值取决于声明该中间件的 provider：
Provider 格式 示例
File <middleware-name>@file strip@file
Docker <middleware-name>@docker strip@docker
Kubernetes CRD <middleware-namespace>-<middleware-name>@kubernetescrd default-auth@kubernetescrd

YAML 示例：

entryPoints:
  web:
    address: :80
    http:
      middlewares:
        - default-auth@kubernetescrd
        - strip@file

Helm Chart Values 等价写法：

ports:
  web:
    port: :80
    http:
      middlewares:
        - default-auth@kubernetescrd
        - strip@file

encodeQuerySemicolons：查询串分号的两种解释

该选项控制未编码分号在查询串中的语义，行为对照：

encodeQuerySemicolons 请求查询串 转发后的查询串
false foo=bar;baz=bar foo=bar&baz=bar
true foo=bar;baz=bar foo=bar%3Bbaz=bar
false foo=bar&baz=bar;foo foo=bar&baz=bar&foo
true foo=bar&baz=bar;foo foo=bar&baz=bar%3Bfoo

默认 false 时，未编码分号会被 Traefik 当作查询参数分隔符；开启后，未编码分号将被编码为 %3B 再传给后端，从而避免后端把分号误读为分隔符。

underscoreHeadersStrategy：带下划线的请求头

该选项（默认 keep）定义请求头名中含下划线时的处理方式：

  • keep：带下划线的请求头原样转发（默认）；
  • delete：任何头名包含下划线的请求头在路由前被静默移除；
  • reject：携带下划线头的请求直接被 400 Bad Request 拒绝。

三个常量定义于 pkg/config/static/entrypoints.go 顶部：UnderscoreHeadersStrategyKeep、UnderscoreHeadersStrategyDelete、UnderscoreHeadersStrategyReject。

背景：下划线本身是合法的 HTTP 头名字符，但 Go 的标准库只按连字符做头名规范化，因此一个以连字符形式管理某头的中间件（例如 ForwardAuth 的 authResponseHeaders 选项管理 X-Auth-User）看不到也删不掉它的下划线变体（X_Auth_User）。

安全提示：同时把两种形式映射到同一变量的后端（CGI、WSGI、PHP 等）可能因下划线变体被伪造。暴露此类后端时建议将策略设为 delete 或 reject。更多细节见 Headers with Underscores 安全文档。

entryPoints:
  websecure:
    address: ':443'
    http:
      underscoreHeadersStrategy: delete

[entryPoints.websecure]
  address = ":443"

  [entryPoints.websecure.http]
    underscoreHeadersStrategy = "delete"

--entryPoints.websecure.address=:443
--entryPoints.websecure.http.underscoreHeadersStrategy=delete

sanitizePath：请求路径净化

sanitizePath（默认 true）决定是否净化请求路径：移除 /./、/../ 与多斜杠序列。关闭后，传入路径原样传给后端——这在对接不编码路径的遗留客户端时可能有用，但注意 base64 内容内含 / 字符，若未做 URL 编码，sanitizePath: false 可能导致不安全的路由行为。

行为对照：

sanitizePath 请求路径 实际请求路径
false /./foo/bar /./foo/bar
true /./foo/bar /foo/bar
false /foo/../bar /foo/../bar
true /foo/../bar /bar
false /foo/bar// /foo/bar//
true /foo/bar// /foo/bar/
false /./foo/../bar// /./foo/../bar//
true /./foo/../bar// /bar/

安全提示：将 sanitizePath 设为 false 并不安全，应确保每个请求都正确进行了 URL 编码。

编码字符（http.encodedCharacters）

从安全角度，可以配置 Traefik 控制请求路径中编码字符的处理。默认情况下，Traefik 不拒绝含有某些编码字符的请求，而这些字符可能被用于路径穿越等攻击。

两点说明：

  • 该检查只作用于请求路径（按 RFC 3986 第 3 节的定义），不作用于查询参数；
  • 当后端不完全遵循 RFC 3986、特别是对路径中编码的保留字符做了额外解码时，建议将相关开关设为 false，避免“双重解释”（split-view）问题，帮助防止路径穿越等绕过安全控制的行为。

默认允许通过的编码字符清单：

编码字符 字符
%2f 或 %2F /（斜杠）
%5c 或 %5C \（反斜杠）
%00 NULL（空字符）
%3b 或 %3B ;（分号）
%25 %（百分号）
%3f 或 %3F ?（问号）
%23 #（井号）

七个开关对应 EncodedCharacters 结构体的 7 个布尔字段，默认全部为 true。

转发头信任（Forwarded Headers）

trustedIPs：只信任特定来源

entryPoints:
  web:
    address: ":80"
    forwardedHeaders:
      trustedIPs:
        - "127.0.0.1/32"
        - "192.168.1.7"

[entryPoints]
  [entryPoints.web]
    address = ":80"

    [entryPoints.web.forwardedHeaders]
      trustedIPs = ["127.0.0.1/32", "192.168.1.7"]

--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.trustedIPs=127.0.0.1/32,192.168.1.7

insecure：无条件信任（仅限测试）

entryPoints:
  web:
    address: ":80"
    forwardedHeaders:
      insecure: true

[entryPoints]
  [entryPoints.web]
    address = ":80"

    [entryPoints.web.forwardedHeaders]
      insecure = true

--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.insecure

connection：允许穿过中间件链的 Connection 头

按 RFC 7230，Traefik 遵循客户端请求中的 Connection 选项：移除请求 Connection 头中列出的所有头字段，以及当 Connection 头为空时移除该头字段本身。移除发生在 Traefik 开始处理请求之时，因此被移除的头在请求穿过中间件链时已不可用。connection 选项用于列出允许先穿过中间件链、之后再被移除的 Connection 头：

entryPoints:
  web:
    address: ":80"
    forwardedHeaders:
      connection:
        - foobar

[entryPoints]
  [entryPoints.web]
    address = ":80"

    [entryPoints.web.forwardedHeaders]
      connection = ["foobar"]

--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.connection=foobar

addXForwardedSchemeHeaders：兼容性方案头

在 X-Forwarded-Proto 之外额外添加 X-Forwarded-Scheme 与 X-Scheme 两个兼容性头，主要用于从 ingress-nginx 迁移、且应用仍依赖这些遗留头的场景。启用后，这些头与 X-Forwarded-Proto 取相同值：

entryPoints:
  websecure:
    address: ":443"
    forwardedHeaders:
      addXForwardedSchemeHeaders: true

[entryPoints]
  [entryPoints.websecure]
    address = ":443"

    [entryPoints.websecure.forwardedHeaders]
      addXForwardedSchemeHeaders = true

--entryPoints.websecure.address=:443
--entryPoints.websecure.forwardedHeaders.addXForwardedSchemeHeaders=true

HTTP/3：与 TCP 入口点共用端口的 UDP 监听

由于 HTTP/3 实际使用 UDP，当一个 TCP 入口点（端口 N）启用了 HTTP/3 后，底层自动启动的 HTTP/3 服务器会同时监听 UDP 端口 N。这意味着端口 N 不能再被另一个 UDP 入口点使用。另外，由于 HTTP/3 强制要求 TLS，只有启用了 TLS 的路由器才能配合 HTTP/3 使用。

入口点侧唯一的 HTTP/3 配置项是 http3.advertisedPort：用于覆盖 alt-svc 头中宣告的 UDP authority 端口（例如 Traefik 监听 8443、而公网端口是 443 的场景）。

ProxyProtocol 与负载均衡器

proxyProtocol.trustedIPs 决定了对哪些来源 IP 做远端客户端地址替换：在此填写你的负载均衡器 IP 或 CIDR。

把 Traefik 放在另一个负载均衡器之后时，务必在两侧都配置 PROXY protocol。只在一侧配置可能给系统引入安全风险（使请求伪造成为可能），因为伪造的 PROXY protocol 头会被用于替换客户端地址。

reusePort：同端口多进程监听与灰度升级

用法示例

同一入口点、同一主机上的多进程：

entryPoints:
  web:
    address: ":80"
    reusePort: true

Helm 写法：

## Values file
additionalArguments:
  - --entryPoints.web.reusePort=true

同一入口点、不同主机（跨主机复用 80 端口）：

entryPoints:
  web:
    address: ":80"
    reusePort: true
  privateWeb:
    address: "192.168.1.2:80"
    reusePort: true

additionalArguments:
  - --entryPoints.web.reusePort=true
  - --entryPoints.privateWeb.address=192.168.1.2:80
  - --entryPoints.privateWeb.reusePort=true

实现层面，server_entrypoint_listenconfig_unix.go 在构建 net.ListenConfig 时，若 configuration.ReusePort 为真则注入 controlReusePort 控制函数，通过 unix.SetsockoptInt(fd, unix.SOL_SOCKET, unixSOREUSEPORT, 1) 打开 SO_REUSEPORT 选项；FreeBSD 平台使用 SO_REUSEPORT_LB 变体。

支持的平台

reusePort 目前仅在 Linux、FreeBSD、OpenBSD 与 Darwin 上生效（源码的构建标签即为 linux || freebsd || openbsd || darwin），其他平台会被忽略。

另外注意：Linux 内核存在一个已知缺陷，使用 reusePort 时可能引发意外的 TCP 连接失败，可参考 LWN 上对该问题的分析。

对 Traefik 自身的金丝雀部署

将 reusePort 与 transport.lifeCycle.graceTimeOut 联用，可以对 Traefik 本身做金丝雀部署——例如升级 Traefik 版本或重载静态配置而不产生服务中断：新进程先绑定同一端口（SO_REUSEPORT 允许内核分发连接），旧进程进入优雅终止阶段（graceTimeOut 给予活跃请求完成机会）后退出，从而实现零停机切换。

内置入口点的自动创建

除了显式声明的入口点，Traefik 还会按需自动创建：

  • 若未定义任何用户入口点，会创建一个名为 http 的默认入口点（地址 :80）；
  • 当启用了 API insecure 模式、ping 或 Prometheus metrics 使用默认内部入口点、或 REST provider insecure 模式时，会自动创建名为 traefik 的内部入口点（地址 :8080），该名称由常量 DefaultInternalEntryPointName 定义，并且如上所述它永远不会进入默认入口点列表。

这段逻辑位于 static_config.go 的 SetEffectiveConfiguration() 中，可在该文件内 Creates the default entry point if needed 与 Creates the internal traefik entry point if needed 两处注释附近阅读。

小结：入口点配置的落地要点

  1. 先用 address 把端口与协议钉死：格式 [host]:port[/tcp|/udp]，缺省协议为 TCP；UDP 入口点记得设置 udp.timeout（默认 3s）控制空闲会话回收；
  2. 80 → 443 场景用 http.redirections.entryPoint（默认 https + 永久 + 极高优先级），443 入口点用 http.tls 打开 TLS，并按需叠加 http.tls.options / http.tls.certResolver；
  3. 全局横切需求（鉴权、剥离路径等）优先挂在入口点的 http.middlewares 上，用全限定名引用，并注意其先于 IngressRoute/Ingress 上的中间件执行；
  4. 安全基线：forwardedHeaders.insecure 与 proxyProtocol.insecure 仅用于测试；暴露 CGI/WSGI/PHP 类后端时把 underscoreHeadersStrategy 设为 delete 或 reject；后端不完全遵循 RFC 3986 时收紧 http.encodedCharacters 各项；
  5. 运维能力：transport.lifeCycle 两项配合 reusePort 实现 Traefik 自身零停机升级；observability.* 三个开关与 traceVerbosity 可按入口点粒度控制日志、指标与 trace 的默认行为；
  6. Kubernetes/Helm 用户记住 Helm 默认创建 web/websecure/traefik/metrics 四个入口点，覆盖默认行为通过 ports 与 additionalArguments 完成。

文中所有默认值与行为均可在当前仓库中查证：配置结构与默认值见 pkg/config/static/entrypoints.go，全局常量与自动创建的入口点见 pkg/config/static/static_config.go，默认入口点列表计算见 cmd/traefik/traefik.go，SO_REUSEPORT 实现见 pkg/server/server_entrypoint_listenconfig_unix.go，入口点监听构建见 pkg/server/server_entrypoint_tcp.go。

traefik
The Cloud Native Application Proxy
项目地址：https://gitcode.com/GitHub_Trending/tr/traefik
登录后查看全文

相关内容推荐

1 Traefik 云原生应用代理入门：Entrypoints、Routers、Services 与 Providers 核心概念全解2 Traefik 在 Kubernetes 中的快速上手：从 k3d 本地集群到 IngressRoute 与 Gateway API 双模路由实践3 Traefik 快速上手：在 Docker 与 Kubernetes 中部署云原生应用代理4 Traefik 入门 FAQ：HTTP 状态码、TLS 证书与路由配置排查指南5 Pangolin项目UDP端口配置问题解析与解决方案6 5分钟上手！Helm+Traefik打造云原生流量入口最佳实践7 Traefik 结合 Docker 快速入门：用 Docker Compose 部署网关、暴露 Dashboard 并验证容器路由8 Caddy HTTP/3技术解析与实践指南：从配置到优化的完整路径9 Traefik ACME 单域名证书自动化实战：tls.certresolver 在 Docker、Swarm、Kubernetes 与 File 各 Provider 下的配置详解10 mitmproxy.net.server_spec 模块深度解析：ServerSpec 类型与 parse() 解析规则
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

Tesseract.js FAQ 深度解读：项目边界、框架集成、oem/psm 差异排查与 .traineddata 缓存机制graphify 技术解析：把任意代码库与文档变成可查询的知识图谱Folo mobile e2e：用 Maestro 在 iOS 模拟器与 Android 模拟器上跑通认证流程的实战指南TanStack Query ESLint 规则详解：prefer-query-options 如何强制 queryKey 与 queryFn 同处定义fastlane 内置 Actions 目录解析：自动检测机制与自定义 Action 创建指南LiteLLM Rust 工作区深度解析：四 Crate 架构、messages() 调用链与 Python 互操作设计freeCodeCamp 课程挑战文件解析：以 "Say Hello to HTML Elements" 为例看懂挑战 MD 文件的结构、字段与测试断言机制llama.cpp CANN 后端实战指南：在华为 Ascend NPU 上编译、运行与调优大模型推理Strix GCP 云安全技能解析：IAM 提权、GCS 暴露与元数据滥用的系统化测试方法docling 中的 Python 异常处理模式：EAFP 边界、B904 异常链与反模式

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.12 K
2.72 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
528
588
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
906
1.82 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
docsdocs
暂无描述
Markdown
891
5.78 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.53 K
1.01 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.34 K
1.45 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
987
504
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
540
384