---
title: "查询节点属性"
date: 2026-03-12
lastmod: 2026-03-12
description: "介绍如何使用 Cat API 查询 Easysearch 集群中节点的自定义属性信息。"
tags: ["Cat API", "节点", "属性", "集群管理"]
summary: "此 API 用于显示集群中所有节点的自定义属性信息。
API #  GET /_cat/nodeattrs API 的作用 #  返回集群中每个节点的属性信息，包括：
 节点信息：节点名称、ID、进程 ID、主机名、IP 地址、端口 节点属性：节点的自定义属性名称和对应的值  节点属性用于在节点上存储自定义的键值对信息，常用于：
 标记节点的物理位置（如机房、机架） 标记节点的硬件特性（如 SSD/HDD） 标记节点的业务用途（如热数据/冷数据） 控制分片分配策略  API 的参数 #  此 API 没有路由参数。
查询字符串参数 #     参数 类型 是否必需 默认值 描述     format string 可选 text 响应格式
可选值：json, yaml, text   full_id boolean 可选 false 是否显示完整的节点 ID   h string 可选 默认列 指定显示的列，逗号分隔   help boolean 可选 false 显示帮助信息   local boolean 可选 false 是否从本地节点获取信息   master_timeout time 可选 30s 等待主节点响应的超时时间   s string 可选 - 排序列"
---


此 API 用于显示集群中所有节点的自定义属性信息。

## API

```
GET /_cat/nodeattrs
```

## API 的作用

返回集群中每个节点的属性信息，包括：

- **节点信息**：节点名称、ID、进程 ID、主机名、IP 地址、端口
- **节点属性**：节点的自定义属性名称和对应的值

节点属性用于在节点上存储自定义的键值对信息，常用于：
- 标记节点的物理位置（如机房、机架）
- 标记节点的硬件特性（如 SSD/HDD）
- 标记节点的业务用途（如热数据/冷数据）
- 控制分片分配策略

## API 的参数

此 API **没有**路由参数。

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `format` | string | 可选 | text | 响应格式<br>可选值：`json`, `yaml`, `text` |
| `full_id` | boolean | 可选 | false | 是否显示完整的节点 ID |
| `h` | string | 可选 | 默认列 | 指定显示的列，逗号分隔 |
| `help` | boolean | 可选 | false | 显示帮助信息 |
| `local` | boolean | 可选 | false | 是否从本地节点获取信息 |
| `master_timeout` | time | 可选 | 30s | 等待主节点响应的超时时间 |
| `s` | string | 可选 | - | 排序列<br>支持 `:asc` 和 `:desc` |
| `v` | boolean | 可选 | false | 详细模式，显示列头 |

## 返回的字段信息

| 列名 | 别名 | 描述 | 默认显示 |
|------|------|------|----------|
| `node` | `name` | 节点名称 | ✓ |
| `id` | `nodeId` | 节点唯一 ID | ✗ |
| `pid` | `p` | 进程 ID | ✗ |
| `host` | `h` | 主机名 | ✗ |
| `ip` | `i` | IP 地址 | ✗ |
| `port` | `po` | 传输端口 | ✗ |
| `attr` | `attr.name` | 属性名称 | ✓ |
| `value` | `attr.value` | 属性值 | ✓ |

## 请求示例

```bash
# 查询所有节点属性
GET /_cat/nodeattrs

# 显示列头
GET /_cat/nodeattrs?v

# 使用 JSON 格式
GET /_cat/nodeattrs?format=json

# 只显示特定列
GET /_cat/nodeattrs?h=node,attr,value

# 显示完整节点 ID
GET /_cat/nodeattrs?full_id=true

# 按属性名称排序
GET /_cat/nodeattrs?s=attr:asc

# 显示帮助信息
GET /_cat/nodeattrs?help
```

## 响应示例

### 文本格式（默认）

```
node       attr   value
data-node-1 data   hot
data-node-1 rack   rack1
data-node-1 zone   zone-a
data-node-2 data   cold
data-node-2 rack   rack2
data-node-2 zone   zone-b
data-node-3 data   warm
data-node-3 rack   rack3
data-node-3 zone   zone-a
```

### 文本格式（带列头）

```
node       id   pid  host            ip         port attr   value
data-node-1 4b2c 1234 192.168.1.100  10.0.0.1   9300 data   hot
data-node-1 4b2c 1234 192.168.1.100  10.0.0.1   9300 rack   rack1
data-node-1 4b2c 1234 192.168.1.100  10.0.0.1   9300 zone   zone-a
data-node-2 8f3a 5678 192.168.1.101  10.0.0.2   9300 data   cold
data-node-2 8f3a 5678 192.168.1.101  10.0.0.2   9300 rack   rack2
```

### JSON 格式

```json
[
  {
    "node": "data-node-1",
    "attr": "data",
    "value": "hot"
  },
  {
    "node": "data-node-1",
    "attr": "rack",
    "value": "rack1"
  },
  {
    "node": "data-node-1",
    "attr": "zone",
    "value": "zone-a"
  }
]
```

## 设置节点属性

节点属性可以在 `easysearch.yml` 配置文件中设置：

```yaml
# 设置节点属性
node:
  attr:
    data: hot
    rack: rack1
    zone: zone-a
    storage_type: ssd
```

或者在启动时通过命令行参数设置：

```bash
bin/easysearch -Enode.attr.data=hot -Enode.attr.rack=rack1
```

## 常见节点属性用途

### 1. 数据分层存储
根据数据热度分配分片：

```yaml
# 热数据节点
node.attr.data: hot
node.attr.storage_type: ssd

# 冷数据节点
node.attr.data: cold
node.attr.storage_type: hdd
```

### 2. 机架感知
避免单点故障，确保副本分布在不同机架：

```yaml
# 机架 A
node.attr.rack: rack1
node.attr.zone: zone-a

# 机架 B
node.attr.rack: rack2
node.attr.zone: zone-b
```

### 3. 分片分配控制
使用节点属性控制分片分配：

```json
{
  "settings": {
    "index.routing.allocation.require.data": "hot",
    "index.routing.allocation.require.zone": "zone-a"
  }
}
```

### 4. 硬件特性标记
标记节点的硬件特性：

```yaml
# 高性能节点
node.attr.cpu: high
node.attr.memory: 64gb
node.attr.storage: ssd

# 标准节点
node.attr.cpu: standard
node.attr.memory: 32gb
node.attr.storage: hdd
```

## 分片分配感知配置

配置集群以感知节点属性，实现智能分片分配：

```yaml
# 机架感知
cluster.routing.allocation.awareness.attributes: rack

# 多层感知（机架 + 区域）
cluster.routing.allocation.awareness.attributes: rack,zone

# 强制感知（确保副本分布在不同的属性值上）
cluster.routing.allocation.awareness.force.data.values: hot,warm,cold
```

## 使用场景

1. **容量规划**：查看节点属性，规划资源分配
2. **分片分配**：基于节点属性控制分片分布
3. **故障隔离**：确保副本分布在不同的故障域
4. **数据分层**：实现热数据/温数据/冷数据分离
5. **硬件优化**：根据硬件特性分配不同的负载

## 注意事项

1. 此 API 只支持 GET 方法
2. 每个节点的每个属性会单独显示为一行
3. 节点 ID 默认只显示前 4 个字符，使用 `full_id=true` 显示完整 ID
4. 节点属性需要在配置文件或启动参数中设置
5. 修改节点属性需要重启节点

## 最佳实践

1. **一致性命名**：使用统一的属性命名规范
2. **文档记录**：记录节点属性的含义和用途
3. **合理规划**：根据业务需求合理设计属性
4. **避免频繁变更**：节点属性变更需要重启节点
5. **测试验证**：在生产环境应用前充分测试

## 相关文档

- [查询节点](./get-node.md)
- [获取节点信息](./get-node-info.md)
- [查询分片分配](./get-shard-allocation.md)
- [更新集群设置](./update-cluster-settings.md)