服务器配置

最小示例

Configuration config = new Configuration();
config.setHostname("127.0.0.1");
config.setPort(9092);
config.setContext("/socket.io");
config.setTransports(Transport.POLLING, Transport.WEBSOCKET);
config.setStoreFactory(new RedisStoreFactory(redissonClient));

默认设置适用于大多数用例；下面列出可选的额外重写项。

有关连接认证检查 此处.

网络与绑定

属性	类型	默认值	描述
主机名	字符串	null	绑定地址。若未设置，则绑定到 0.0.0.0 / ::0
端口	整型	-1	服务器端口（必须设置）
上下文	字符串	/socket.io	Socket.IO 上下文路径

config.setHostname("0.0.0.0");
config.setPort(9092);
config.setContext("/socket.io");

---

线程模型

属性	类型	默认值	说明
bossThreads	整型	0	当值为 0 时为 CPU * 2
workerThreads	整型	0	当值为 0 时为 CPU * 2

config.setBossThreads(2);
config.setWorkerThreads(16);

Boss 与 Worker 线程 Boss 线程接受连接；Worker 线程处理所有 I/O。 添加 boss 线程 仅 以增加 连接接收速率；使用 对于大多数情况为 1。 按吞吐量扩展 worker 线程——过多会导致上下文切换。

---

传输配置

属性	类型	默认值	描述
transports	List<Transport>	WEBSOCKET, POLLING	启用的传输方式
transportType	TransportType	AUTO	本机 IO 选择 (EPOLL / KQUEUE / IO_URING / NIO)
upgradeTimeout	整型（毫秒）	10000	轮询 → WebSocket 升级超时

config.setTransports(Transport.WEBSOCKET);
config.setTransportType(TransportType.EPOLL);

在 AUTO 传输模式下， socketio4j 在启动时会按以下顺序自动选择最合适的可用传输： IO_URING → EPOLL → KQUEUE → NIO.

如果所选传输在当前平台不可用，socketio4j 会安全地回退到 NIO 而不会导致启动失败。

---

心跳与超时

属性	默认值	描述
pingInterval	25000 毫秒	Ping 间隔
pingTimeout	60000 毫秒	Ping 超时（0 禁用）
firstDataTimeout	5000 毫秒	防止静默通道攻击

ℹ️ Ping 间隔与 Ping 超时 pingInterval 定义服务器发送心跳 ping 以保持连接存活的频率（NAT 保活）。 pingTimeout 定义服务器等待的时长 在没有 pong 的情况下 才将客户端视为已断开连接。

简而言之： interval = 检查的频率, timeout = 放弃前等待的时长.

config.setPingInterval(20000);
config.setPingTimeout(60000);
config.setFirstDataTimeout(5000);

NAT 超时与保活提示 pingInterval 必须 短于典型的 NAT 空闲超时 （通常为 30–60 秒）以在路由器和移动网络后保持连接存活。

较低的值可提高 NAT 存活率并更快检测到失效对端，但 会增加网络和 CPU 开销。 较高的值则降低开销，但有导致 在 NAT 和负载均衡器上出现静默断开 的风险。

---

负载与帧限制

属性	默认值	描述
maxHttpContentLength	64 KB	最大 HTTP 请求大小
maxFramePayloadLength	64 KB	最大 WebSocket 帧大小

config.setMaxHttpContentLength(256 * 1024);
config.setMaxFramePayloadLength(256 * 1024);

---

CORS 与 HTTP 行为

属性	默认值	描述
enableCors	true	启用 CORS
origin	null	Access-Control-Allow-Origin
allowHeaders	null	Access-Control-Allow-Headers
addVersionHeader	true	添加 Server 头
allowCustomRequests	false	允许非 Socket.IO 请求

config.setEnableCors(true);
config.setOrigin("https://example.com");
config.setAllowHeaders("Authorization,Content-Type");

---

压缩

属性	默认值	描述
httpCompression	true	GZIP / Deflate
websocketCompression	true	permessage-deflate

config.setHttpCompression(true);
config.setWebsocketCompression(true);

---

缓冲与 ACK 处理

属性	默认值	描述
preferDirectBuffer	true	使用 Netty 直接缓冲区
ackMode	AUTO_SUCCESS_ONLY	自动 ACK 行为

config.setPreferDirectBuffer(true);
config.setAckMode(AckMode.AUTO);

Ack 行为

• Ack 最多发送 一次 并且 仅在请求时发送

• 手动 ack 始终抑制自动 ack

• AUTO → 始终自动确认并附带 [] （即使发生异常）

• AUTO_SUCCESS_ONLY → 仅在成功时自动确认并附带 [] 只有在成功时

• 手动 → 开发者需完全负责发送 ack

---

会话与安全

属性	默认值	描述
randomSession	false	随机化会话 ID
needClientAuth	false	TLS 客户端认证

config.setRandomSession(true);
config.setNeedClientAuth(true);

---

JSON 序列化

属性	默认值	描述
jsonSupport	自动检测	默认基于 Jackson

config.setJsonSupport(new JacksonJsonSupport());

---

授权

属性	默认值	描述
authorizationListener	允许所有	握手授权

config.setAuthorizationListener(data -> {
    return AuthorizationResult.SUCCESS;
});

---

异常处理

属性	默认值	描述
exceptionListener	DefaultExceptionListener	全局异常钩子

config.setExceptionListener(new ExceptionListener() {
    @Override
    public void onEventException(Exception e, Object... args) {
        log.error("Socket.IO error", e);
    }
});

---

存储 / 集群

config.setStoreFactory(new RedisStoreFactory(redissonClient));

请查看 适配器 页面以获取详细说明。

---

SSL / TLS

SocketSslConfig ssl = new SocketSslConfig();
ssl.setKeyStore("keystore.jks");
ssl.setKeyStorePassword("changeit");
/**
//仅在 mTLS/零信任 场景下使用，通常不用于 wss
ssl.setTrustStore("truststore.jks");
ssl.setTrustStorePassword("changeit");
*/
config.setSocketSslConfig(ssl);

---

HTTP 解码器调优

属性	默认值
maxInitialLineLength	Netty 默认值
maxHeaderSize	Netty 默认值
maxChunkSize	Netty 默认值

HttpRequestDecoderConfiguration http = new HttpRequestDecoderConfiguration();
http.setMaxHeaderSize(16 * 1024);
config.setHttpRequestDecoderConfiguration(http);

---

📌 提示：配置在内部会被克隆以保证不可变性。请在服务器启动前将其视为一次性写入。