节点端口文件配置

配置项作用 #

node.portsfile 配置项用于控制是否将节点实际绑定的端口信息写入文件。

启用后，节点会在日志目录中创建两个端口文件：

• transport.ports - 包含传输层服务的端口（通常为 9300）
• http.ports - 包含 HTTP 服务的端口（通常为 9200）

主要用于测试环境和外部工具集成，方便动态检测节点实际使用的端口。

配置项属性 #

• 配置路径: node.portsfile
• 数据类型: Boolean（布尔值）
• 默认值: false
• 是否可选: 是
• 作用域: NodeScope（节点级别）
• 动态更新: 否（需要重启节点生效）

配置项详解 #

工作机制 #

端口文件工作机制

启动流程 (node.portsfile: true):
├── 1. 绑定传输端口
│   ├── 尝试绑定配置的端口
│   ├── 或使用随机端口 (port=0)
│   └── 获取实际绑定的地址和端口
│
├── 2. 绑定 HTTP 端口
│   ├── 尝试绑定配置的端口
│   ├── 或使用随机端口
│   └── 获取实际绑定的地址和端口
│
├── 3. 写入端口文件
│   ├── logs/transport.ports
│   ├── logs/http.ports
│   └── 使用原子写入 (先写 .tmp 再重命名)
│
└── 4. 正常关闭时删除


禁用时 (node.portsfile: false):
├── 正常绑定端口
├── 不创建端口文件
└── 正常运行 ✅

文件内容格式 #

端口文件内容

logs/transport.ports:
192.168.1.100:9300
192.168.1.101:9300
[::1]:9300


logs/http.ports:
192.168.1.100:9200
192.168.1.101:9200
[::1]:9200


格式说明:
├── IPv4: address:port
│   └── 示例: 192.168.1.100:9300
├── IPv6: [address]:port
│   └── 示例: [::1]:9300
└── 多地址: 每行一个地址
    └── 绑定多个网络接口时


读取端口文件:
$ cat logs/http.ports
127.0.0.1:9200


提取端口号:
$ cat logs/http.ports | head -1 | cut -d: -f2
9200

动态端口检测 #

使用场景: 动态端口分配

配置:
http.port: 0  # 使用随机端口
transport.port: 0  # 使用随机端口
node.portsfile: true


启动后:
├── 系统分配随机端口
├── 端口写入文件
├── 外部工具读取文件
└── 获取实际端口


测试框架集成:
├── 启动测试集群
├── 配置随机端口
├── 读取 ports 文件
├── 连接到实际端口
└── 执行测试

文件写入机制 #

原子写入过程

1. 创建临时文件
   logs/http.ports.tmp


2. 写入内容
   127.0.0.1:9200


3. 同步到磁盘
   fsync()


4. 原子重命名
   rename("http.ports.tmp", "http.ports")


5. 关闭时删除
   shutdown hook → delete file


优势:
├── 原子操作: 不会出现部分写入
├── 并发安全: 读取者看到完整内容
└── 异常安全: 写入失败不影响旧文件

配置建议 #

生产环境（默认） #

node:
  portsfile: false  # 默认值

建议: 生产环境保持默认值 false。不需要端口文件。

测试环境 #

node:
  portsfile: true  # 启用端口文件

建议: 测试环境启用。方便测试框架检测端口。

开发环境 #

node:
  name: "dev-node"
  portsfile: true  # 便于调试

建议: 开发环境可启用。便于动态端口检测。

容器环境 #

node:
  portsfile: true  # 容器编排需要

建议: 容器环境启用。便于端口发现。

代码示例 #

easysearch.yml 基础配置 #

node:
  portsfile: false

测试集群配置 #

cluster:
  name: "test-cluster"

node:
  name: "test-node"
  portsfile: true

http:
  port: 0  # 使用随机端口

transport:
  port: 0  # 使用随机端口

多节点测试配置 #

# 节点 1
node:
  name: "node-1"
  portsfile: true

# 节点 2
node:
  name: "node-2"
  portsfile: true

完整开发配置 #

cluster:
  name: "dev-cluster"

node:
  name: "dev-node-1"
  portsfile: true

http:
  port: 9200

transport:
  port: 9300

path:
  logs: /var/log/easysearch

相关配置 #

测试框架集成 #

测试框架使用示例

Java 测试代码:

// 启动节点
Settings settings = Settings.builder()
    .put("node.portsfile", true)
    .put("http.port", 0)  // 随机端口
    .build();

Node node = new Node(settings).start();


// 读取实际端口
Path httpPortsFile = node.getNodeEnvironment()
    .logsDir()
    .resolve("http.ports");

List<String> lines = Files.readAllLines(httpPortsFile);
String[] parts = lines.get(0).split(":");
int actualPort = Integer.parseInt(parts[1]);


// 连接测试
RestClient client = RestClient.builder(
    new HttpHost("localhost", actualPort)
).build();


// 执行测试
// ...


// 关闭节点
node.close();


Gradle 测试集群:

testClusters {
  "test-cluster" {
    numberOfNodes = 3
    setting "node.portsfile", "true"
    setting "http.port", "0"

    test {
      // 读取端口文件
      def httpPorts = new File(projectDir, "build/testclusters/test-cluster/node0/logs/http.ports")
      def port = httpPorts.readLines().first().split(":")[1] as Integer

      // 使用端口测试
      useCluster testClusters."test-cluster"
    }
  }
}

使用场景 #

推荐启用 portsfile 的场景 #

• 自动化测试: 测试框架需要动态检测端口
• 容器编排: Docker/Kubernetes 环境的端口发现
• CI/CD 流水线: 自动化测试和部署
• 开发调试: 快速确定实际使用的端口
• 外部工具: 监控或管理工具需要端口信息

推荐禁用 portsfile 的场景 #

• 生产环境: 端口是固定的，不需要检测
• 标准部署: 使用固定端口配置
• 安全考虑: 不希望暴露端口信息

实际应用示例 #

端口发现应用

1. CI/CD 测试
   ├── 启动集群（随机端口）
   ├── 读取 ports 文件
   ├── 运行集成测试
   └── 清理


2. 容器编排
   ├── 启动容器
   ├── 读取内部端口
   ├── 映射到宿主机
   └── 注册到服务发现


3. 健康检查
   ├── 读取 ports 文件
   ├── 连接端口
   ├── 验证服务可用
   └── 报告健康状态


4. 服务发现
   ├── 读取所有节点 ports
   ├── 注册到发现服务
   └── 负载均衡

性能影响分析 #

性能影响 #

性能影响分析

启用端口文件:
├── 启动时
│   ├── 写入文件: 极小开销
│   ├── 磁盘 I/O: 几 KB
│   └── 延迟: < 1ms
├── 运行时
│   └── 无影响
└── 关闭时
    └── 删除文件: 极小开销


结论:
├── 性能影响: 可忽略
├── 开销: 仅启动/关闭时
└── 推荐测试环境启用 ✅

注意事项 #

1. 默认值: 默认值为 false，不创建端口文件。

2. 需要重启: 修改此配置需要重启节点。

3. 文件位置: 端口文件位于日志目录。

4. 自动清理: 正常关闭时自动删除文件。

5. 测试专用: 主要用于测试和开发环境。

6. 随机端口: 配合 port: 0 使用最有效。

7. 原子写入: 使用临时文件确保原子性。

8. 多地址: 绑定多个接口时会写入多行。

9. IPv6 格式: IPv6 地址使用方括号。

10. 文件权限: 需要日志目录写权限。

故障排查 #

端口文件常见问题

问题 1: 端口文件未生成

检查:
├── 确认 node.portsfile: true
├── 检查日志目录权限
└── 查看启动日志


解决:
├── 设置正确权限
├── 确保配置生效
└── 重启节点


问题 2: 端口文件内容为空

原因:
├── 端口绑定失败
├── 节点启动异常
└── 权限问题


解决:
├── 检查端口是否被占用
├── 查看节点日志
└── 确认配置正确


问题 3: 端口文件残留

原因:
├── 异常退出
├── 关闭钩子未执行
└── 文件未删除


解决:
├── 手动删除旧文件
├── 正常关闭节点
└── 或启动前清理

最佳实践 #

端口文件最佳实践

1. 测试环境
   node:
     portsfile: true

   http:
     port: 0

   transport:
     port: 0


2. 多节点测试
   ├── 每个节点使用随机端口
   ├── 读取各自的 ports 文件
   └── 避免端口冲突


3. 容器化
   ├── 内部使用固定或随机端口
   ├── 通过 ports 文件暴露
   ├── 外部映射到宿主机
   └── 动态端口发现


4. 框架集成
   ├── 启动后读取文件
   ├── 解析端口信息
   ├── 连接到实际端口
   └── 完成后清理


5. 生产环境
   ├── 禁用端口文件
   ├── 使用固定端口
   ├── 标准配置管理
   └── 避免额外开销