《Netty 高性能网络编程》2.3 ChannelOption 与 Socket 参数

本节目标：知道每个常用 ChannelOption 作用在哪一层、默认值应该怎么核对，并给 linkd-v2 的 server/client 各定一套可解释的起点参数。
适用版本：JDK 25 + Netty 4.2.19.Final。

承接的问题

2.1 的 LinkdServer 已经写了 .option(ChannelOption.SO_BACKLOG, 1024) 和 .childOption(ChannelOption.TCP_NODELAY, true)，但这两个参数为什么一个用 option、一个用 childOption，以及 1024 和 true 是从哪里来的，还没有解释。2.2 又看到 AUTO_READ、WRITE_BUFFER_WATER_MARK 这些名字，它们和 SO_KEEPALIVE、ALLOCATOR 混在一起时，很容易被当成同一类「性能参数」。

实际上它们作用在不同层：有的只影响监听 socket，有的影响每条 accepted 连接，有的只对客户端建连有效，有的控制 Netty 用户态缓冲区而不是内核 socket。把参数放到错误的层，代码不会报错，但行为不会改变。把默认值凭记忆写死，换一个 Netty 版本或操作系统就会失真。

这一节按「建连、传输行为、内存与写缓冲」三组拆开，每个参数只回答三个问题：设置在哪里、管什么、默认值边界在哪里。最后给出 linkd-v2 的 server/client 参数表和打印 ChannelConfig 的方法。

本机口径：Apple M1 Pro，10 核，32 GB，macOS 26.3 (25D125)；Temurin 25.0.5+8，Netty 4.2.19.Final。下面没有压测数字；参数值是 linkd-v2 的起点配置，不是「最优值」。

核心机制一：ChannelOption 的层级

ChannelOption<T> 是强类型常量，SO_BACKLOG 的类型是 ChannelOption<Integer>，TCP_NODELAY 是 ChannelOption<Boolean>，ALLOCATOR 是 ChannelOption<ByteBufAllocator>。option(...) 的签名会检查值类型，传字符串或错误类型在编译期就会失败；这也是它比「配置 Map<String, Object>」更安全的地方。

设置位置分四层：

ServerBootstrap 的 option 和 childOption 名字只差一个前缀，效果却完全不同。option 只改监听 socket；childOption 只改 accept 出来的连接。Bootstrap 没有子连接，所以只有 option。Channel.config().setOption 是运行期入口，但并非所有选项都能在 bind/connect 之后修改；设置前先查对应 ChannelConfig 的实现，不要假设都能热改。

核对实际值最可靠的方法是打印 ChannelConfig：

package com.plume.linkd.v2.server;

import io.netty.channel.Channel;
import io.netty.channel.ChannelOption;
import java.util.Map;

public final class OptionDump {

    private OptionDump() {
    }

    public static void print(String label, Channel channel) {
        System.out.println("== " + label + " ==");
        for (Map.Entry<ChannelOption<?>, Object> entry
                : channel.config().getOptions().entrySet()) {
            System.out.println(entry.getKey().name() + " = " + entry.getValue());
        }
    }
}

在 LinkdServer.bind 返回后调用：

Channel custom = bootstrap.bind(9093).sync().channel();
OptionDump.print("custom", custom);

示意输出（键的集合和顺序随 4.2 实现与平台变化，不是实测）：

== custom ==
SO_BACKLOG = 1024
SO_REUSEADDR = true
TCP_NODELAY = true
SO_KEEPALIVE = true
AUTO_READ = true
ALLOCATOR = PooledByteBufAllocator(directByDefault: true)

getOptions() 只列出当前 config 能返回的选项，不代表所有 ChannelOption 都存在；某个选项没出现在输出里，可能是平台不支持，也可能是实现没有暴露。要查单个值，用 channel.config().getOption(ChannelOption.SO_BACKLOG)，返回类型由泛型决定，不需要强制转换。

核心机制二：建连参数

SO_BACKLOG 只对监听 socket 有意义，设置在 ServerBootstrap.option。它是内核 accept 队列的长度提示，不是「最大连接数」，也不等于 worker 能同时处理的连接数。内核还有 somaxconn 之类的上限，实际生效值取两者较小者；队列满时新连接是被拒绝还是被忽略，取决于操作系统。linkd-v2 的起点是 1024，压测时再根据 accept 速率调整，不要把它当成容量上限。

SO_REUSEADDR 也设置在 ServerBootstrap.option。JDK 文档承诺的是：在 bind 之前开启，可以绑定仍有旧连接处于 TIME_WAIT 的地址；它不承诺两个同时监听的 socket 共用同一端口。macOS 上按这个语义使用即可，不要把 SO_REUSEADDR 当成 SO_REUSEPORT。后者在 NIO 传输上是否可用取决于 JDK 和平台，原生传输的细节放到第 12 章。

CONNECT_TIMEOUT_MILLIS 只对客户端 Bootstrap 有效，设置在 option。它覆盖 TCP 建连阶段，不覆盖应用层读超时，也不自动等于整个请求的预算。Bootstrap.connect(String, int) 会经过地址解析再发起连接；域名解析发生在 resolver 阶段，是否计入这个超时取决于 resolver 实现，不要把 CONNECT_TIMEOUT_MILLIS 当成「从调用到响应」的总时限。

核心机制三：传输行为参数

TCP_NODELAY 关闭 Nagle 算法。Nagle 会把小数据攒起来再发，牺牲延迟换包数；自定义协议的小帧、请求响应式交互通常不希望这种攒包，所以 linkd-v2 在 accepted 连接和客户端连接上都设为 true。代价是包数可能增加，网络利用率不一定更好；不要写成「开启就一定更快」，它只改变延迟与包数的取舍。监听 socket 上没有这个选项，写在 ServerBootstrap.option 里不会影响子连接。

SO_KEEPALIVE 打开操作系统的 TCP keepalive 探测。探测的空闲时间、间隔和次数由操作系统参数决定，ChannelOption 只能开关，不能设置这些时间；它也不是应用层心跳。linkd-v2 的 9093 协议有自己的 PING/PONG，心跳由第 7 章的 IdleStateHandler 负责，SO_KEEPALIVE 只作为「对端主机消失时内核最终能发现」的兜底。

AUTO_READ 控制 Netty 是否在 channel 激活后自动调用 read。默认配置下它是打开的，channel 会持续读取；设为 false 后，必须自己调用 ctx.read() 或 channel.read() 请求下一次读。这个开关是第 9 章读背压的基础：先关掉自动读，再按业务处理能力决定何时读下一批。

.childOption(ChannelOption.AUTO_READ, false)

对应 handler 里要显式驱动：

@Override
public void channelActive(ChannelHandlerContext ctx) {
    ctx.read();
}

@Override
public void channelReadComplete(ChannelHandlerContext ctx) {
    ctx.read();
}

AUTO_READ=false 最常见的故障是「连接建立了，但一个字节都收不到」：忘记调用 read()，或者只在 channelActive 调了一次、之后没有在 channelReadComplete 继续请求。相反，如果业务处理很慢却保持自动读，数据会在用户态排队，水位线才有意义；两者要配套使用。

核心机制四：内存与写缓冲参数

ALLOCATOR 指定 channel 使用的 ByteBufAllocator。PooledByteBufAllocator.DEFAULT 是池化分配器，UnpooledByteBufAllocator.DEFAULT 每次分配独立缓冲区；前者通常减少分配和 GC 压力，后者便于排查。注意 ByteBufAllocator.DEFAULT 的类型受系统属性 -Dio.netty.allocator.type 影响，不要假设它一定是 pooled；要确定行为，就显式写 PooledByteBufAllocator.DEFAULT 或打印 config。

RCVBUF_ALLOCATOR 控制每次读时用户态 ByteBuf 的分配策略，值类型是 RecvByteBufAllocator（模块 netty-transport）。4.2 自带 AdaptiveRecvByteBufAllocator（根据上次读到的字节数调整下一次分配）和 FixedRecvByteBufAllocator（固定大小）。它不等于内核的 SO_RCVBUF：前者决定 Netty 一次读准备多大的缓冲区，后者是内核接收缓冲区；调 RCVBUF_ALLOCATOR 不会直接改变 TCP 窗口通告。

WRITE_BUFFER_WATER_MARK 是写队列的高低水位，值是 WriteBufferWaterMark(low, high)。待写字节超过 high 时，channel.isWritable() 变为 false；降到 low 以下恢复 true。它是应用层背压信号，不是 TCP 发送窗口；第 9 章会用它决定是否继续读上游。4.2 提供 WriteBufferWaterMark.DEFAULT 作为默认值，具体数值以打印为准，不要背数字。

.childOption(ChannelOption.ALLOCATOR, PooledByteBufAllocator.DEFAULT)
.childOption(ChannelOption.WRITE_BUFFER_WATER_MARK,
        new WriteBufferWaterMark(32 * 1024, 128 * 1024))

low 和 high 不是协议常量。low 太低会让 isWritable() 在边界附近反复翻转，high 太高会让背压信号来得太晚；取值要结合单连接允许排队的字节数和一次可写事件能排空的量，14.1 会给出一套估算方法。

在 linkd-v2 里落地：server/client 参数表

先把共享常量集中到 linkd-core，避免 linkd-server 和 linkd-client 互相依赖：

package com.plume.linkd.v2.protocol;

import io.netty.channel.WriteBufferWaterMark;

public final class LinkdChannelOptions {

    public static final int BACKLOG = 1024;
    public static final WriteBufferWaterMark WATER_MARK =
            new WriteBufferWaterMark(32 * 1024, 128 * 1024);

    private LinkdChannelOptions() {
    }
}

服务端 9090/9093 的参数表：

客户端 9093 的参数表：

服务端装配：

ServerBootstrap bootstrap = new ServerBootstrap()
        .group(boss, worker)
        .channel(NioServerSocketChannel.class)
        .option(ChannelOption.SO_BACKLOG, LinkdChannelOptions.BACKLOG)
        .option(ChannelOption.SO_REUSEADDR, true)
        .childOption(ChannelOption.TCP_NODELAY, true)
        .childOption(ChannelOption.SO_KEEPALIVE, true)
        .childOption(ChannelOption.ALLOCATOR, PooledByteBufAllocator.DEFAULT)
        .childOption(ChannelOption.WRITE_BUFFER_WATER_MARK,
                LinkdChannelOptions.WATER_MARK)
        .childHandler(new CustomProtocolInitializer(registry));

客户端装配：

Bootstrap bootstrap = new Bootstrap()
        .group(group)
        .channel(NioSocketChannel.class)
        .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 1000)
        .option(ChannelOption.TCP_NODELAY, true)
        .option(ChannelOption.SO_KEEPALIVE, true)
        .option(ChannelOption.ALLOCATOR, PooledByteBufAllocator.DEFAULT)
        .option(ChannelOption.WRITE_BUFFER_WATER_MARK,
                LinkdChannelOptions.WATER_MARK)
        .handler(new ChannelInitializer<SocketChannel>() {
            @Override
            protected void initChannel(SocketChannel ch) {
                ch.pipeline().addLast(new LinkdFrameDecoder());
                ch.pipeline().addLast(new LinkdFrameEncoder());
            }
        });

两张表里唯一不对称的是 CONNECT_TIMEOUT_MILLIS：它只属于客户端建连，服务端没有对应参数。SO_BACKLOG 和 SO_REUSEADDR 只属于监听 socket；TCP_NODELAY、SO_KEEPALIVE、AUTO_READ、ALLOCATOR、RCVBUF_ALLOCATOR、WRITE_BUFFER_WATER_MARK 则作用在每条连接上，服务端要写在 childOption，客户端写在 option。

常见错误与边界

错误一：把连接级参数写在 ServerBootstrap.option 里。

// 反例：TCP_NODELAY 只改了监听 socket
ServerBootstrap bootstrap = new ServerBootstrap()
        .option(ChannelOption.TCP_NODELAY, true)
        .childHandler(initializer);

监听 socket 没有 Nagle 算法，这个设置不会作用到 accepted 连接。正确位置是 childOption；客户端因为只有一条连接，才用 option。

错误二：把 ChannelOption 当字符串配置。

// 反例：配置中心传来 "SO_BACKLOG"，运行期无法映射
Object value = config.get("SO_BACKLOG");

ChannelOption 是强类型常量，不是字符串键。配置中心到 ChannelOption 之间需要一层显式的映射表，并且校验值类型；直接反射字符串名既脆弱，也会绕过编译期检查。

错误三：把 SO_KEEPALIVE 当心跳。 TCP keepalive 的探测间隔由操作系统决定，应用无法通过 ChannelOption 设置；它只能在对端主机彻底失联时最终发现，不能代替 PING/PONG。linkd-v2 的心跳由 IdleStateHandler 和协议帧负责，SO_KEEPALIVE 只是兜底。

错误四：设了 AUTO_READ=false 却忘记 read()。 连接会保持打开但不再读取，客户端看到请求已发送、服务端却没有任何响应。关闭自动读之后，必须在 channelActive 和每次 channelReadComplete 里继续请求；否则第一次读完之后就停住了。

错误五：把 RCVBUF_ALLOCATOR 当成 SO_RCVBUF。 前者是 Netty 用户态读缓冲区的分配策略，后者是内核接收缓冲区；调整前者不会直接扩大 TCP 窗口。要改内核缓冲区，得用 SO_RCVBUF（平台支持时），但本节不把它列为默认配置。

边界：默认值不要凭记忆写死。 SO_BACKLOG、CONNECT_TIMEOUT_MILLIS、WRITE_BUFFER_WATER_MARK 的默认值在 Netty 版本和平台之间可能变化；ByteBufAllocator.DEFAULT 还会受 -Dio.netty.allocator.type 影响。用 OptionDump 打印一次，比背一个数字可靠。

小结

• ChannelOption 是强类型常量，设置位置决定作用对象：ServerBootstrap.option 管监听 socket，childOption 管每条连接，Bootstrap.option 管客户端连接。
• SO_BACKLOG 是 accept 队列提示，不是最大连接数；SO_REUSEADDR 按 JDK 语义复用 TIME_WAIT 地址，不是 SO_REUSEPORT。
• CONNECT_TIMEOUT_MILLIS 只覆盖客户端 TCP 建连，不覆盖读超时和整个请求预算。
• TCP_NODELAY 用小包换低延迟，SO_KEEPALIVE 是 OS 兜底而不是心跳，AUTO_READ=false 必须手动 read()。
• ALLOCATOR 控制 ByteBuf 分配器，RCVBUF_ALLOCATOR 控制用户态读缓冲策略，WRITE_BUFFER_WATER_MARK 提供应用层写背压信号。
• 默认值以 4.2 实现和 ChannelConfig 打印为准；linkd-v2 的 server/client 参数表只是起点，压测后按数据调整。

参数决定了单条连接的行为，下一节把视角拉到线程：EventLoopGroup 有哪些线程、一条 channel 为什么终身绑定一个 EventLoop、boss 与 worker 的线程数如何影响 accept 和读写。

阅读导航：上一节：2.2 Channel 生命周期与 ChannelFuture · 下一节：3.1 EventLoopGroup 与线程归属 。