Solr部署：集群节点管理命令详解

Posted on 三月 15, 2025 本文总阅读量次

概述

集群是一组相互协调运行的Solr节点的集合。这些API命令可以在整个SolrCloud集群级别或单个节点上工作，为集群运维提供了强大的管理能力。

CLUSTERSTATUS：集群状态查询

获取集群状态，包括集合、分片、副本、配置名称以及集合别名和集群属性。

此命令还会报告每个集合和分片的健康状态，以便更容易监控集合的运行状态。健康状态值定义如下，按从最佳到最差的顺序排列，基于活跃副本的百分比（active）：

GREEN：active == 100%，所有副本都处于活跃状态且存在分片领导者
YELLOW：100% > active > 50% 且存在分片领导者
ORANGE：50% >= active > 0% 且存在分片领导者
RED：没有活跃副本或没有分片领导者

集合健康状态报告为任意分片的最差状态，例如，对于所有分片都是GREEN但有一个YELLOW的集合，集合健康状态将报告为YELLOW。

API调用方式

V1 API：

1	http://localhost:8983/solr/admin/collections?action=CLUSTERSTATUS

V2 API：

1	curl -X GET http://localhost:8983/api/cluster

CLUSTERSTATUS 参数

collection

类型：可选
默认值：无
说明：请求信息的集合或别名名称。如果省略，将返回集群中所有集合的信息。如果提供别名，将返回别名中集合的信息。

shard

类型：可选
默认值：无
说明：请求信息的分片。可以指定多个分片名称，用逗号分隔。

route

类型：可选
默认值：无
说明：如果你需要特定文档所属分片的详细信息但不知道它属于哪个分片，可以使用此参数。

aliases

类型：可选
默认值：默认为下面指定的includeAll参数的默认值

liveNodes

类型：可选
默认值：默认为下面指定的includeAll参数的默认值
说明：如果设置为true，返回集群中活跃节点的状态。

clusterProperties

类型：可选
默认值：默认为下面指定的includeAll参数的默认值
说明：如果设置为true，返回集群的属性。

roles

类型：可选
默认值：默认为下面指定的includeAll参数的默认值
说明：如果设置为true，返回集群内的角色。

includeAll

类型：可选
默认值：true
说明：如果设置为true，返回与活跃节点、集合、别名、集群属性、角色等相关的所有信息。如果设置为false，返回的信息基于其他指定的参数。

响应示例

输入：

1	http://localhost:8983/solr/admin/collections?action=CLUSTERSTATUS

输出：

{
  "responseHeader": {
    "status": 0,
    "QTime": 333
  },
  "cluster": {
    "collections": {
      "collection1": {
        "shards": {
          "shard1": {
            "range": "80000000-ffffffff",
            "state": "active",
            "health": "GREEN",
            "replicas": {
              "core_node1": {
                "state": "active",
                "core": "collection1",
                "node_name": "127.0.1.1:8983_solr",
                "base_url": "http://127.0.1.1:8983/solr",
                "leader": "true"
              },
              "core_node3": {
                "state": "active",
                "core": "collection1",
                "node_name": "127.0.1.1:8900_solr",
                "base_url": "http://127.0.1.1:8900/solr"
              }
            }
          },
          "shard2": {
            "range": "0-7fffffff",
            "state": "active",
            "health": "GREEN",
            "replicas": {
              "core_node2": {
                "state": "active",
                "core": "collection1",
                "node_name": "127.0.1.1:7574_solr",
                "base_url": "http://127.0.1.1:7574/solr",
                "leader": "true"
              },
              "core_node4": {
                "state": "active",
                "core": "collection1",
                "node_name": "127.0.1.1:7500_solr",
                "base_url": "http://127.0.1.1:7500/solr"
              }
            }
          }
        },
        "router": {"name": "compositeId"},
        "replicationFactor": "1",
        "znodeVersion": 11,
        "autoCreated": "true",
        "configName": "my_config",
        "health": "GREEN",
        "aliases": ["both_collections"]
      }
    },
    "aliases": {"both_collections": "collection1,collection2"},
    "roles": {
      "overseer": [
        "127.0.1.1:8983_solr",
        "127.0.1.1:7574_solr"
      ]
    },
    "live_nodes": [
      "127.0.1.1:7574_solr",
      "127.0.1.1:7500_solr",
      "127.0.1.1:8983_solr",
      "127.0.1.1:8900_solr"
    ]
  }
}

CLUSTERPROP：集群属性管理

添加、编辑或删除集群级属性。

API调用方式

V1 API：

1	http://localhost:8983/solr/admin/collections?action=CLUSTERPROP&name=urlScheme&val=https

V2 API 创建或更新集群属性：

curl -X PUT http://localhost:8983/api/cluster/properties/urlScheme \
  -H 'Content-Type: application/json' -d '{
    "value": "https"
  }'

V2 API 删除集群属性：

1	curl -X DELETE http://localhost:8983/api/cluster/properties/urlScheme

CLUSTERPROP 参数

name (v1)

类型：可选
默认值：无
说明：属性的名称。在v2请求中出现在路径中。支持的属性名称有location、maxCoresPerNode、urlScheme和defaultShardPreferences。如果启用了Jaeger追踪模块，属性samplePercentage也可用。其他属性可以设置（例如，如果你的自定义插件需要它们），但必须以前缀ext.开头。不以ext.开头的未知属性将被拒绝。

val (v1), value (v2)

类型：可选
默认值：无
说明：属性的值。如果值为空或null，则取消设置该属性。

设置集群级默认值

可以使用defaults参数为集合的某些属性设置集群级默认值。

设置/更新默认值（仅V2 API）：

curl -X PUT -H 'Content-type:application/json' --data-binary '{
  "defaults" : {
    "collection": {
      "numShards": 2,
      "nrtReplicas": 1,
      "tlogReplicas": 1,
      "pullReplicas": 1
    }
  }
}' http://localhost:8983/api/cluster/properties

取消设置单个默认值：

curl -X PUT -H 'Content-type:application/json' --data-binary '{
  "defaults" : {
    "collection": {
      "nrtReplicas": null
    }
  }
}' http://localhost:8983/api/cluster/properties

默认分片偏好

使用defaultShardPreferences参数，你可以实现机架或可用区感知。首先，确保使用系统属性”标记”你的节点（例如，-Drack=rack1）。然后，将defaultShardPreferences的值设置为node.sysprop:sysprop.YOUR_PROPERTY_NAME：

1
2
3

curl -X PUT -H 'Content-type:application/json' --data-binary '{
  "value" : "node.sysprop:sysprop.rack"
}' http://localhost:8983/api/cluster/properties/defaultShardPreferences

此时，如果你在具有例如rack=rack1的节点上运行查询，Solr将尝试只命中来自rack1的副本。

集群属性操作示例

列出集群属性（仅V2 API）：

1	curl -X GET http://localhost:8983/api/cluster/properties

获取特定集群属性（仅V2 API）：

1	curl -X GET http://localhost:8983/api/cluster/properties/urlScheme

Balance Replicas：副本平衡

在给定的Solr节点集合中打乱副本，直到达到平衡状态。配置的副本放置插件将用于决定：

哪些副本应该被移动以进行平衡
这些副本应该放置在哪些节点上
集群何时达到”平衡状态”

API调用方式

V2 API：

curl -X POST http://localhost:8983/api/cluster/replicas/balance \
  -H 'Content-Type: application/json' -d '{
    "nodes": ["localhost:8983_solr", "localhost:8984_solr"],
    "async": "balance-replicas-1"
  }'

参数说明

nodes

类型：可选
默认值：无
说明：副本将在其上进行平衡的节点。不在此节点集合中的副本将不包括在平衡中。如果未提供此参数，将使用所有活跃数据节点。

waitForFinalState

类型：可选
默认值：false
说明：如果为true，请求将仅在所有受影响的副本变为活跃时完成。如果为false，API将在最少必需的副本（如受影响的领导者副本）变为活跃时返回。

async

类型：可选
默认值：无
说明：用于跟踪此操作的请求ID，该操作将异步处理。

重要提示：此操作不会对源节点上的副本持有必要的锁。因此在此期间不要执行其他集合操作。

Migrate Replicas：副本迁移

将给定源节点集合中的所有副本迁移出去。如果使用多个节点作为targetNode（显式或默认），则配置的副本放置插件将用于确定每个迁移副本应使用哪个targetNode。

API调用方式

V2 API：

curl -X POST http://localhost:8983/api/cluster/replicas/migrate \
  -H 'Content-Type: application/json' -d '{
    "sourceNodes": ["localhost:8983_solr", "localhost:8984_solr"],
    "targetNodes": ["localhost:8985_solr", "localhost:8986_solr"],
    "async": "migrate-replicas-1"
  }'

参数说明

sourceNodes

类型：必需
默认值：无
说明：副本将从中迁移的节点。

targetNodes

类型：可选
默认值：无
说明：迁移副本将移动到的节点。如果未提供，API将使用所有未在sourceNodes中提供的活跃节点。如果有多个节点要迁移副本，则配置的PlacementPlugin副本将选择其中一个节点。

waitForFinalState

类型：可选
默认值：false
说明：如果为true，请求将仅在所有受影响的副本变为活跃时完成。

async

类型：可选
默认值：无
说明：用于跟踪此异步处理操作的请求ID。

BALANCESHARDUNIQUE：平衡分片属性

确保特定属性在构成集合的物理节点之间均匀分布。如果属性已存在于副本上，将尽力保留在那里。如果属性在分片上的任何副本上都不存在，则选择一个并添加该属性。

API调用方式

V1 API：

1	http://localhost:8983/solr/admin/collections?action=BALANCESHARDUNIQUE&collection=techproducts&property=preferredLeader

V2 API：

curl -X POST http://localhost:8983/api/collections/techproducts/balance-shard-unique \
  -H 'Content-Type: application/json' -d '{
    "property": "preferredLeader"
  }'

参数说明

collection

类型：必需
默认值：无
说明：要平衡属性的集合名称。

property

类型：必需
默认值：无
说明：要平衡的属性。如果未明确指定，文字property.将前缀到此属性。

onlyactivenodes

类型：可选
默认值：true
说明：通常，属性仅在活跃节点上实例化。如果此参数指定为false，则非活跃节点也包括在分发中。

shardUnique

类型：可选
默认值：无
说明：某种安全阀。有一个预定义属性（preferredLeader）将此值默认为true。对于所有其他要平衡的属性，这必须设置为true或将返回错误消息。

REPLACENODE：替换节点

警告：此API的功能已被Migrate Replicas替代和增强，请考虑使用新API，因为此API可能在未来版本中移除。

此命令在另一个节点上重新创建一个节点（源）中的副本。复制每个副本后，删除源节点中的副本。

API调用方式

V1 API：

1	http://localhost:8983/solr/admin/collections?action=REPLACENODE&sourceNode=source-node&targetNode=target-node

V2 API：

curl -X POST "http://localhost:8983/api/cluster/nodes/localhost:7574_solr/replace" \
  -H 'Content-Type: application/json' -d '{
    "targetNodeName": "localhost:8983_solr",
    "waitForFinalState": "false",
    "async": "async"
  }'

参数说明

sourceNode

类型：必需
说明：需要从中复制副本的源节点。

targetNode

类型：可选
说明：副本将被复制到的目标节点。如果未提供此参数，Solr将使用除sourceNode外的所有活跃节点。

parallel

类型：可选
默认值：false
说明：如果此标志设置为true，所有副本将在单独的线程中创建。请记住，如果副本有非常大的索引，这可能导致非常高的网络和磁盘I/O。

waitForFinalState

类型：可选
默认值：false
说明：如果为true，请求将仅在所有受影响的副本变为活跃时完成。

timeout

类型：可选
默认值：300秒
说明：等待新副本创建和领导者副本完全恢复的时间（秒）。

DELETENODE：删除节点副本

删除该节点中所有集合的所有副本。请注意，此操作后节点本身将仍作为活跃节点保留。

API调用方式

V1 API：

1	http://localhost:8983/solr/admin/collections?action=DELETENODE&node=nodeName

V2 API：

curl -X POST "http://localhost:8983/api/cluster/nodes/localhost:7574_solr/clear/" \
  -H 'Content-Type: application/json' -d '{
    "async": "someAsyncId"
  }'

参数说明

node

类型：必需
说明：要移除的节点。

async

类型：可选
说明：用于跟踪此异步处理操作的请求ID。

角色管理

ADDROLE：添加角色

将角色分配给集群中的给定节点。目前唯一支持的角色是overseer。

使用此命令将特定节点专用作Overseer。多次调用以添加更多节点。这在Overseer可能过载的大型集群中很有用。如果可用，分配了’overseer’角色的节点列表中的一个将成为overseer。如果指定的节点都不运行，系统将将角色分配给任何其他节点。

API调用方式

V1 API：

1	http://localhost:8983/solr/admin/collections?action=ADDROLE&role=overseer&node=localhost:8983_solr

V2 API：

curl -X POST http://localhost:8983/api/cluster \
  -H 'Content-Type: application/json' -d '{
    "add-role": {
      "role": "overseer",
      "node": "localhost:8983_solr"
    }
  }'

REMOVEROLE：移除角色

移除分配的角色。此API用于撤消使用ADDROLE操作分配的角色。

API调用方式

V1 API：

1	http://localhost:8983/solr/admin/collections?action=REMOVEROLE&role=overseer&node=localhost:8983_solr

V2 API：

curl -X POST http://localhost:8983/api/cluster \
  -H 'Content-Type: application/json' -d '{
    "remove-role": {
      "role": "overseer",
      "node": "localhost:8983_solr"
    }
  }'

参数说明

role

类型：必需
说明：角色的名称。目前仅支持overseer角色。

node

类型：必需
说明：将分配/移除角色的节点名称。可以在节点启动之前分配角色。

OVERSEERSTATUS：Overseer状态和统计

返回overseer的当前状态、各种overseer API的性能统计信息，以及每个操作类型的最后10个失败。

API调用方式

V1 API：

1	http://localhost:8983/solr/admin/collections?action=OVERSEERSTATUS

V2 API：

1	curl -X GET http://localhost:8983/api/cluster/overseer

响应示例

{
  "responseHeader": {
    "status": 0,
    "QTime": 33
  },
  "leader": "127.0.1.1:8983_solr",
  "overseer_queue_size": 0,
  "overseer_work_queue_size": 0,
  "overseer_collection_queue_size": 2,
  "overseer_operations": [
    "createcollection", {
      "requests": 2,
      "errors": 0,
      "avgRequestsPerSecond": 0.7467088842794136,
      "5minRateRequestsPerSecond": 7.525069023276674,
      "15minRateRequestsPerSecond": 10.271274280947182,
      "avgTimePerRequest": 0.5050685,
      "medianRequestTime": 0.5050685,
      "75thPcRequestTime": 0.519016,
      "95thPcRequestTime": 0.519016,
      "99thPcRequestTime": 0.519016,
      "999thPcRequestTime": 0.519016
    }
  ],
  "collection_operations": [
    "splitshard", {
      "requests": 1,
      "errors": 1,
      "recent_failures": [{
        "request": {
          "operation": "splitshard",
          "shard": "shard2",
          "collection": "example1"
        },
        "response": [
          "Operation splitshard caused exception:",
          "org.apache.solr.common.SolrException: No shard with the specified name exists: shard2"
        ]
      }]
    }
  ]
}

最佳实践建议

集群监控

定期执行CLUSTERSTATUS：监控集群健康状态，特别关注RED和ORANGE状态的分片
设置监控告警：对集群状态变化设置自动告警机制
追踪性能指标：使用OVERSEERSTATUS监控Overseer性能

节点管理

平衡操作：在高负载期间避免执行副本平衡操作
迁移策略：使用Migrate Replicas替代REPLACENODE进行节点替换
异步操作：对大规模操作使用async参数避免超时

属性配置

默认分片偏好：在多机架环境中配置defaultShardPreferences提升性能
集群级默认值：合理设置collection默认值简化集合创建
自定义属性：使用ext.前缀添加自定义集群属性

安全考虑

角色分离：在大型集群中专用Overseer节点
操作锁定：执行节点操作时避免并发集合操作
备份验证：节点替换前确保数据备份完整

这些集群节点管理命令为SolrCloud提供了完整的运维管理能力，正确使用这些命令可以确保集群的高可用性和optimal性能。