Traefik InFlightConn TCP 中间件详解：按来源 IP 限制并发连接数

inFlightConn 是 Traefik 提供的一款 TCP 中间件，用于在高负载场景下主动防止后端 Service 被并发连接压垮——它按客户端 IP 统计当前同时在线的 TCP 连接数，当某个 IP 的活跃连接数达到上限后，新到达的连接会被直接关闭。本文基于 Traefik v3 源码与官方文档，系统讲解该中间件的配置方式、amount 参数语义、底层按 IP 计数的实现机制，以及在各配置提供方（文件、Docker/Consul 标签、Kubernetes CRD）下的完整接入方法，帮助你在实际路由中正确启用连接数限流。

一、中间件定位与工作原理概述

在 TCP 中间件总览 中，Traefik 将 inFlightConn 归类为 Security / Request lifecycle（安全与连接生命周期） 类中间件，其用途被定义为 "Limits the number of simultaneous connections"（限制同时连接的数量）。

从源码实现看，其核心思路是以远程 IP 为粒度进行连接计数。中间件内部维护一张 map[string]int64，以来源 IP 为键、当前活跃连接数为值：

• 每个新 TCP 连接到达时，先从 RemoteAddr 中解析出客户端 IP；
• 若该 IP 已有连接数 ≥ amount，则立即拒绝并关闭连接；
• 否则计数器 +1，把连接放行给下一级处理器；
• 当连接结束时计数器 -1（inflight_conn.go）。

一个值得注意的细节是：这里的计数阈值不是全局并发上限，而是每个 IP 各自的并发上限。也就是说，不同来源 IP 之间互不影响，各自独立拥有 amount 个并发连接配额。这一点可以从官方文档标题与源码注释 "The connections are identified and grouped by remote IP" 得到确认。

二、配置示例（完整覆盖五种配置形态）

inFlightConn 的完整配置示例在官方路由参考文档中有五套对应不同配置提供方的写法，下面逐一给出，方便直接复制使用。

1. 结构化配置：YAML

在动态配置文件中，将 amount 设为允许的最大并发连接数（示例为 10）：

# 限制到 10 个同时连接
tcp:
  middlewares:
    test-inflightconn:
      inFlightConn:
        amount: 10

2. 结构化配置：TOML

# 限制到 10 个同时连接
[tcp.middlewares]
  [tcp.middlewares.test-inflightconn.inFlightConn]
    amount = 10

3. Docker / Swarm 标签（Labels）

基于容器的标签声明中间件时，注意键名大小写规范为 inflightconn，值为数字：

labels:
  - "traefik.tcp.middlewares.test-inflightconn.inflightconn.amount=10"

同样的标签格式也适用于其他基于标签/注解的提供方。仓库的参考样例中可以看到该键的标准形态：traefik.tcp.middlewares.tcpmiddleware03.inflightconn.amount=42（见 docker-labels.yml）。

4. Consul Catalog / KV 标签（Tags）

// 限制到 10 个同时连接
{
  //...
  "Tags" : [
    "traefik.tcp.middlewares.test-inflightconn.inflightconn.amount=10"
  ]
}

5. Kubernetes CRD（MiddlewareTCP）

在 Kubernetes 中，使用 traefik.io/v1alpha1 的 MiddlewareTCP 资源声明，并通过 IngressRouteTCP 挂载：

apiVersion: traefik.io/v1alpha1
kind: MiddlewareTCP
metadata:
  name: test-inflightconn
spec:
  inFlightConn:
    amount: 10

完整的 CRD 字段定义（inFlightConn.amount，类型为 integer/int64）可以在仓库的 traefik.io_middlewaretcps.yaml 中查到。

三、配置参数：amount

字段	说明	默认值	是否必填
amount	允许的最大同时连接数。当已有 amount 个连接处于打开状态时，中间件会直接关闭新到达的连接。	0	是

对应动态配置结构体为 TCPInFlightConn，其字段定义与文档完全一致，并带有 +kubebuilder:validation:Minimum=0 约束，即 Kubernetes CRD 层面校验最小值不能小于 0：

type TCPInFlightConn struct {
	// Amount defines the maximum amount of allowed simultaneous connections.
	// The middleware closes the connection if there are already amount connections opened.
	Amount int64 `json:"amount,omitempty" toml:"amount,omitempty" yaml:"amount,omitempty"`
}

关于 amount = 0 的行为说明

官方文档将默认值标为 0、且标记为必填。结合源码 inflight_conn.go 的判定逻辑（connections[ip] >= maxConnections 即拒绝），可以推断：若 amount 被设为 0，任何来源 IP 的首次连接请求都会因为“0 ≥ 0”而立即被拒绝，相当于放行全部拒绝所有连接。因此在实际使用中，请务必显式设置一个大于 0 的合理阈值。

四、接入 TCP Router：让中间件真正生效

单独声明中间件并不会生效，它必须被某个 TCP Router 引用。在结构化配置中通过 middlewares 字段引用，名称需带上提供方后缀（如 @file）：

tcp:
  routers:
    my-router:
      rule: "HostSNI(`example.com`)"
      service: my-service
      middlewares:
        - test-inflightconn@file   # 引用上面定义的中间件

  middlewares:
    test-inflightconn:
      inFlightConn:
        amount: 10

  services:
    my-service:
      loadBalancer:
        servers:
          - address: "10.0.0.10:4000"

Kubernetes 场景下则是在 IngressRouteTCP 的 spec.routes[].middlewares[].name 中填入 MiddlewareTCP 名称完成挂载，挂载方式与 TCP 中间件总览 中展示的 ipAllowList 示例结构一致。底层真正把中间件实例注入到 Router 处理器链的位置在 pkg/server/middleware/tcp/middlewares.go——每当一个 TCP 中间件被引用时，这里会根据其类型调用 inflightconn.New(...) 构建实例。

五、源码级的执行流程拆解

为了让读者对 "in-flight（在途连接）" 计数机制有准确的认知，下面依据 inflight_conn.go 逐段梳理其完整生命周期。

1. 中间件结构

type inFlightConn struct {
	name           string
	next           tcp.Handler
	maxConnections int64

	mu          sync.Mutex
	connections map[string]int64 // current number of connections by remote IP.
}

其中：

• maxConnections 即配置中的 amount；
• connections 是"IP → 当前活跃连接数"的映射表；
• mu 是一个互斥锁，保证多连接并发到达时计数器操作是线程安全的。

2. 每个连接的处理入口 ServeTCP

func (i *inFlightConn) ServeTCP(conn tcp.WriteCloser) {
	ip, _, err := net.SplitHostPort(conn.RemoteAddr().String())
	if err != nil {
		logger.Error().Err(err).Msg("Cannot parse IP from remote addr")
		conn.Close()
		return
	}
	if err = i.increment(ip); err != nil {
		logger.Error().Err(err).Msg("Connection rejected")
		conn.Close()
		return
	}
	defer i.decrement(ip)
	i.next.ServeTCP(conn)
}

流程要点：

1. 从连接的 RemoteAddr 中解析出纯 IP（去掉端口部分）；
2. 调用 increment 尝试将对应 IP 计数 +1：若计数已达上限则返回错误，中间件记录一条 Connection rejected 错误日志并立即关闭连接；
3. 若计数成功，用 defer 注册 decrement，保证无论后续业务处理正常结束还是异常退出，计数器都会被归还；
4. 最终将连接交给链路中的下一处理器 next.ServeTCP(conn)。

3. 计数器的加与减

func (i *inFlightConn) increment(ip string) error {
	i.mu.Lock()
	defer i.mu.Unlock()
	if i.connections[ip] >= i.maxConnections {
		return fmt.Errorf("max number of connections reached for %s", ip)
	}
	i.connections[ip]++
	return nil
}

func (i *inFlightConn) decrement(ip string) {
	i.mu.Lock()
	defer i.mu.Unlock()
	if i.connections[ip] <= 0 {
		return
	}
	i.connections[ip]--
}

可见计数逻辑是一个经典的"许可闸门"：所有加/减操作都处于 mu 临界区保护下，避免并发读写 map 造成数据竞争；decrement 还带有下限保护，确保计数不会减为负数。整体上它并不依赖任何外部存储，完全在 Traefik 进程内存中完成，因此开销极小。

4. 测试用例对语义的印证

仓库配套的单测 inflight_conn_test.go（TestInFlightConn_ServeTCP，中间件配置 Amount: 1）通过真实并发场景验证了如下行为，可以作为语义的权威佐证：

场景	结果
第一个来自 127.0.0.1 的连接	放行进入下一级处理
同一来源 IP 127.0.0.1 的第二个连接（第一个尚未结束）	触发 Close，被拒绝
此时来自另一 IP 127.0.0.2 的连接	仍可正常放行（验证"按 IP 独立计数"）
第一个连接结束后，127.0.0.1 再次发起连接	重新放行（验证 defer decrement 归还配额）

六、典型应用场景与使用建议

inFlightConn 通常与 Traefik 的 TCP 路由（HostSNI 规则、TLS 直通、四层负载均衡等场景）配合使用，以下是文档与实现所支持的一些务实用法：

1. 保护后端四层服务：当后端是数据库、消息队列、自定义二进制协议服务等无法用 HTTP 中间件约束的场景时，用 inFlightConn 限制单一来源 IP 的并发连接，避免突发流量打满服务端句柄。
2. 配合 IP 白名单/黑名单：TCP 中间件支持链式组合，可将 inFlightConn 与 IPAllowList 中间件 放在同一条链上，先过滤来源、再限制并发，实现更完整的访问控制（同协议中间件可组合成链，见 overview.md）。
3. 精确选择阈值：阈值应结合单 IP 业务所需的正常并发量设定。注意计数对象是"来源客户端 IP"而非"连接目的地"，NAT 出口环境（大量内网用户共享同一公网 IP）下阈值设置过小会误伤正常用户，需要结合网络拓扑评估。
4. 运行时观测：当连接被拒绝时，Traefik 会在日志中输出包含 Connection rejected 与 max number of connections reached for <ip> 的错误信息，可据此在日志侧配置告警与观测。

七、小结

inFlightConn 是 Traefik TCP 中间件体系中专门负责"连接级流量整形"的组件：通过 amount 字段声明每 IP 允许的并发连接数，由中间件在进程内以互斥锁保护的计数器完成放行/拒绝判定，是防御四层服务过载的轻量手段。配置入口随提供方不同而各异（YAML/TOML/容器标签/Consul Tags/Kubernetes MiddlewareTCP），但语义完全一致；挂载到 TCP Router 后才生效。建议结合本仓库的 源码实现、并发单测 与 TCP 中间件总览 深入验证你在实际环境中的配置组合，为四层代理链路加上可靠的并发闸门。