---
title: "节点 ID 种子配置"
date: 2026-01-19
lastmod: 2026-01-19
description: "node.id.seed 配置项用于控制生成节点 UUID 的随机种子值。"
tags: ["Node", "节点ID", "UUID", "唯一标识"]
summary: "配置项作用 #  node.id.seed 配置项用于控制生成节点唯一标识符（UUID）时的随机种子值。
此配置作为生成节点 ID 的种子，用于确定节点的持久化 UUID。如果磁盘上已经存在持久化的 UUID，则此配置会被忽略，重用已有的 UUID。
配置项属性 #   配置路径: node.id.seed 数据类型: Long（长整型） 默认值: 0L 最小值: Long.MIN_VALUE 最大值: Long.MAX_VALUE 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效）  配置项详解 #  工作机制 #  节点 ID 生成流程 首次启动: ├── 读取 node.id.seed 配置 ├── 使用配置值创建 Random ├── 生成随机 UUID ├── 持久化到磁盘 └── 节点 ID 确定 后续启动: ├── 读取持久化的 UUID ├── 发现已有 UUID ├── 忽略 node.id.seed └── 重用已有 UUID ✅ UUID 生成公式: Random random = new Random(seed); String nodeId = UUIDs."
---


## 配置项作用

`node.id.seed` 配置项用于控制**生成节点唯一标识符（UUID）时的随机种子值**。

此配置作为生成节点 ID 的种子，用于确定节点的持久化 UUID。如果磁盘上已经存在持久化的 UUID，则此配置会被忽略，重用已有的 UUID。

## 配置项属性

- **配置路径**: `node.id.seed`
- **数据类型**: `Long`（长整型）
- **默认值**: `0L`
- **最小值**: `Long.MIN_VALUE`
- **最大值**: `Long.MAX_VALUE`
- **是否可选**: 是
- **作用域**: NodeScope（节点级别）
- **动态更新**: 否（需要重启节点生效）

## 配置项详解

## 工作机制

```
节点 ID 生成流程

首次启动:
├── 读取 node.id.seed 配置
├── 使用配置值创建 Random
├── 生成随机 UUID
├── 持久化到磁盘
└── 节点 ID 确定


后续启动:
├── 读取持久化的 UUID
├── 发现已有 UUID
├── 忽略 node.id.seed
└── 重用已有 UUID ✅


UUID 生成公式:
Random random = new Random(seed);
String nodeId = UUIDs.randomBase64UUID(random);
```

## UUID 持久化

```
UUID 持久化机制

数据路径:
{data.path}/nodes
    │
    └── _node
        ├── 0 (节点 ID 文件)
        └── 0


文件内容:
持久化的节点 UUID


首次启动:
├── 生成 UUID
├── 写入文件
└── 节点 ID 确立


重启后:
├── 读取文件
├── 获取已有 UUID
├── 忽略种子配置
└── 保持相同 ID ✅
```

## 种子的作用

```
随机种子的作用

相同种子:
seed = 123456789
    │
    ↓
Random(123456789)
    │
    ↓
生成 UUID1


再次使用相同种子:
seed = 123456789
    │
    ↓
Random(123456789)
    │
    ↓
生成 UUID1 (相同 ✅)


不同种子:
seed = 987654321
    │
    ↓
Random(987654321)
    │
    ↓
生成 UUID2 (不同 ✅)
```

## 配置建议

## 生产环境（默认）

```yaml
node:
  id:
    seed: 0  # 默认值
```

**建议**: 保持默认值 `0`。系统自动生成唯一 ID。

## 测试环境

```yaml
node:
  id:
    seed: 123456789  # 固定种子
```

**建议**: 设置固定种子。确保测试可重现。

## 特定 ID 生成

```yaml
node:
  id:
    seed: -1  # 负数种子
```

**建议**: 使用负数或其他特定值。

## 不指定配置

```yaml
node:
  name: "production-node"
  # 不指定 seed，使用默认
```

**建议**: 不指定，使用默认随机种子。

## 代码示例

## easysearch.yml 基础配置

```yaml
node:
  id:
    seed: 0
```

## 生产节点配置

```yaml
node:
  name: "data-node-1"
  id:
    seed: 0
```

## 测试节点配置

```yaml
node:
  name: "test-node"
  id:
    seed: 999999999
```

## 确定性测试配置

```yaml
node:
  name: "deterministic-test"
  id:
    seed: 123456789
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `node.id.seed` | UUID 生成种子 | 0 |
| `node.name` | 节点名称 | 机器主机名 |

## 种子值影响

| seed 设置 | 优点 | 缺点 |
|-----------|------|------|
| 0（默认） | 随机性强 | 不可预测 |
| 固定值 | 可重现 | 失去随机性 |
| 时间戳 | 差异化 | 仍有一定随机性 |

## UUID 示例

```
不同种子的 UUID 生成

seed = 0:
Random(0)
└── 生成: aBcDeFgHiJkLmNoPqRsTuVwXyZ


seed = 123456789:
Random(123456789)
└── 生成: XyZ AbC dEf GhI jKl MnO


seed = Long.MAX_VALUE:
Random(Long.MAX_VALUE)
└── 生成: PqRsTuVwXyZaBcDeFgH
```

## 使用场景

## 推荐使用默认值的场景

- **生产环境**: 需要唯一且随机的节点 ID
- **多节点集群**: 每个节点自动生成唯一 ID
- **不可预测**: 节点 ID 不应该被预测

## 推荐设置固定种子的场景

- **测试环境**: 需要可重现的测试结果
- **自动化测试**: 确保测试的一致性
- **开发调试**: 需要相同的节点 ID

## 推荐不设置的场景

- **大多数场景**: 让系统自动处理
- **生产环境**: 避免配置不当

## 持久化说明

```
UUID 持久化的优先级

优先级:

1. 磁盘上的 UUID 文件存在
   ├── 读取已有 UUID
   ├── 忽略 node.id.seed
   └── 重用已有 UUID ✅


2. 磁盘上没有 UUID 文件
   ├── 使用 node.id.seed
   ├── 生成新的 UUID
   ├── 持久化到磁盘
   └── 成为节点 ID ✅


清理 UUID:
删除数据目录下的 _node/0 文件
    │
    ↓
下次启动:
├── 无 UUID 文件
├── 使用 node.id.seed
└── 生成新 UUID ❌
```

## 注意事项

1. **默认值**: 默认值为 `0`，系统自动随机。

2. **持久化优先**: 磁盘 UUID 优先于种子配置。

3. **不可逆**: 一旦 UUID 生成并持久化，修改种子无效。

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

5. **唯一性**: 确保集群内节点 ID 唯一。

6. **测试专用**: 固定种子主要用于测试。

7. **长整型范围**: 可以使用任何长整数值。

8. **随机性**: 种子为 0 时使用系统随机源。

9. **集群影响**: 节点 ID 是集群识别的基础。

10. **谨慎修改**: 生产环境不应随意修改。

## 清空节点 ID

```
如何生成新的节点 ID

方法 1: 删除数据目录
删除 {data.path}/nodes/_node/0
    │
    ↓
重启节点
    │
    ↓
生成新 UUID ✅


方法 2: 更改种子并删除
├── 修改 node.id.seed
├── 删除 _node/0
├── 重启节点
└── 生成新 UUID ✅


警告:
├── 会丢失节点身份
├── 集群可能识别为新节点
└── 数据可能重新分配
```

## 集群角色影响

```
节点 ID 与集群

节点 ID 作用:
├── 节点唯一标识
├── 集群管理基础
├── 路由表依赖
└── 状态跟踪


节点 ID 改变:
├── 集群视为新节点
├── 旧状态丢失
├── 分片可能重新分配
└── 需要重新平衡


保持稳定:
├── 不要随意修改
├── 保持 UUID 持久
└── 确保集群稳定
```