TCP 地址重用配置

配置项作用 #

network.tcp.reuse_address 配置项用于控制是否启用 TCP 套接字的 SO_REUSEADDR 选项。

启用后允许端口在 TIME_WAIT 状态下被重用，避免"地址已在使用"错误，便于服务器快速重启。

配置项属性 #

配置路径: network.tcp.reuse_address
数据类型: Boolean（布尔值）
默认值: 平台相关
- Linux/MacOS: true
- Windows: false
是否可选: 是
作用域: NodeScope（节点级别）
动态更新: 否（需要重启节点生效）

配置项详解 #

工作机制 #

SO_REUSEADDR 作用

未启用 (false):

端口使用:
├── 绑定端口 9300
├── 使用后关闭
├── 进入 TIME_WAIT (通常 60 秒)
└── 在此期间无法重用 ❌

快速重启问题:
├── 节点关闭
├── 立即重启
├── 端口仍在 TIME_WAIT
└── 绑定失败 ❌


启用 (true):

端口使用:
├── 绑定端口 9300
├── 使用后关闭
├── 进入 TIME_WAIT
└── 可以立即重用 ✅

快速重启:
├── 节点关闭
├── 立即重启
├── 强制重用端口
└── 绑定成功 ✅

TIME_WAIT 状态 #

TCP 连接关闭流程

正常关闭:
活跃节点          被动节点
    │                 │
    ├── FIN ─────────→ │
    │←──────── ACK ──┤
    │                 │
    │←──────── FIN ──┤
    ├── ACK ─────────→ │
    │                 │
    ↓                 ↓
  CLOSED          CLOSED


被动端直接关闭
活跃端进入 TIME_WAIT:
├── 等待 2×MSL (通常 60 秒)
├── 确保远程收到最后的 ACK
└── 防止延迟的包干扰


SO_REUSEADDR:
├── 允许在此状态下绑定
├── 跳过 TIME_WAIT 等待
└── 立即可重用 ✅

平台差异 #

不同平台的默认值

Linux/MacOS:
默认值: true
├── Unix 系统传统
├── 适合服务器应用
└── 推荐启用 ✅


Windows:
默认值: false
├── Windows 系统特性
├── 避免安全问题
└── 推荐保持默认 ⚠️


代码实现:
if (Constants.WINDOWS) {
    defaultReuseAddress = false;
} else {
    defaultReuseAddress = true;
}

配置建议 #

Linux/MacOS 生产环境（默认） #

network:
  tcp:
    reuse_address: true  # 默认值

建议: 保持默认值 true。适合服务器应用。

Windows 生产环境（默认） #

network:
  tcp:
    reuse_address: false  # 默认值

建议: 保持默认值 false。Windows 推荐配置。

跨平台统一配置 #

network:
  tcp:
    reuse_address: true  # 统一启用

建议: 跨平台统一设置，便于维护。

开发测试环境 #

network:
  tcp:
    reuse_address: true  # 便于快速重启

建议: 设置为 true。便于频繁重启。

代码示例 #

easysearch.yml 基础配置 #

network:
  tcp:
    reuse_address: true

Linux 服务器配置 #

network:
  tcp:
    reuse_address: true
    no_delay: true
    keep_alive: true

Windows 客户端配置 #

network:
  tcp:
    reuse_address: false  # Windows 默认

完整 TCP 配置 #

network:
  tcp:
    reuse_address: true
    no_delay: true
    keep_alive: true
    keep_idle: 300
    keep_interval: 300

配置项	作用	默认值
`network.tcp.reuse_address`	地址重用	平台相关
`network.tcp.no_delay`	禁用 Nagle	true
`network.tcp.keep_alive`	Keepalive	true

功能影响分析 #

reuse_address 设置	优点	缺点
false	安全性高，避免地址冲突	快速重启可能失败
true	支持快速重启	可能地址冲突

应用场景对比 #

启用 reuse_address 的场景

场景 1: 快速重启
节点崩溃:
├── 进程退出
├── 端口进入 TIME_WAIT
├── 自动重启脚本
└── 立即重启成功 ✅


场景 2: 多实例
同一主机多实例:
├── 实例 A: 绑定 9300
├── 实例 B: 绑定 9301
├── 实例 A 重启
├── 端口 9300 可用
└── 重启成功 ✅


场景 3: 故障转移
主节点故障:
├── 主节点退出
├── 端口 TIME_WAIT
├── 备节点接管
├── 绑定相同端口
└── 接管成功 ✅

使用场景 #

平台特定建议 #

Linux/MacOS:
reuse_address: true ✅
├── 服务器操作系统
├── 传统 Unix 行为
├── 广泛使用
└── 强烈推荐


Windows:
reuse_address: false ✅
├── 客户端操作系统
├── Windows 安全特性
├── 默认设置
└── 推荐保持


跨平台应用:
建议显式配置:
├── 统一行为
├── 便于维护
└── 避免平台差异

端口绑定顺序 #

Socket 设置顺序很重要

正确顺序:
1. socket()
2. setReuseAddress() ← 必须在 bind 之前
3. bind()
4. listen() 或 connect()


错误顺序:
1. socket()
2. bind()
3. setReuseAddress() ← 太晚了 ❌
4. listen() 或 connect()


Easysearch 实现:
正确处理:
├── 先设置 reuse_address
├── 再绑定端口
└── 确保顺序正确 ✅

安全考虑 #

安全风险分析

风险场景:
reuse_address = true
    │
    ↓
旧连接仍存在:
├── 原进程的数据包到达
├── 被新进程接收
├── 数据混乱
└── 潜在安全问题 ⚠️


风险缓解:
├── 确保旧进程完全退出
├── 使用进程管理工具
├── 等待 TIME_WAIT
└── 监控连接状态


最佳实践:
├── 服务器环境: 可以启用
├── 多租户: 谨慎使用
├── 公网: 评估风险
└── 测试充分

注意事项 #

默认值: 默认值因平台而异。
需要重启: 修改此配置需要重启节点。
平台差异: Linux 和 Windows 默认值不同。
快速重启: 启用后支持快速重启。
地址冲突: 可能导致地址冲突（很少见）。
设置时机: 必须在 bind 之前设置。
应用场景: 主要用于服务器端套接字。
兼容性: 与所有平台兼容。
测试建议: 配置变更后应测试重启流程。
生产环境: 生产环境通常推荐启用（Linux/MacOS）。

绑定流程 #

端口绑定完整流程

1. 创建 Socket
   socket()
       │
       ↓


2. 设置 Socket 选项
   setReuseAddress(true) ← 必须在 bind 前
       │
       ↓


3. 绑定端口
   bind(port)
       │
       ├──── 成功 → 继续执行 ✅
       │
       └──── 失败 →
              ├──── 可重用 ──→ 重试
              └──── 不可用 ──→ 放弃


4. 开始监听
   listen()