Solr配置：Configsets API完整指南

Posted on 一月 17, 2025 本文总阅读量次

Solr配置：Configsets API完整指南

Configsets API使您能够在Solr运行SolrCloud模式时向ZooKeeper上传新的配置集、创建和删除配置集。

配置集是配置文件的集合，如solrconfig.xml、synonyms.txt、模式、特定语言的文件和其他集合级配置文件（通常位于conf目录中的所有内容）。Solr附带两个示例配置集（_default和sample_techproducts_configs），可在创建集合时使用。使用相同概念，您可以创建自己的配置集，并在创建集合时使其可用。

此API提供了一种将配置文件上传到ZooKeeper并在两个或多个集合之间共享相同配置文件集的方法。

一旦配置集已上传到ZooKeeper，在使用Collections API创建集合时使用配置集名称，集合将使用您的配置文件。

如果通过此API上传，配置集不必在集合之间共享，但如果您希望这样做，此API使其更容易实现。上传配置集的替代方法是将配置文件放入server/solr/configsets下的目录中，并在使用bin/solr create创建集合时使用目录名称作为-d参数。

注意： 此API只能与运行SolrCloud模式的Solr一起使用。如果您不在SolrCloud模式下运行Solr但仍希望使用共享配置，请参见配置集部分。

API通过向configs端点传递命令来工作。端点的路径因使用的API而异：v1 API使用/solr/admin/configs，而v2 API使用/api/configsets。下面提供了两种类型的示例。

列出配置集

list命令获取在集合创建期间可用的配置集名称。

V1 API

使用v1 API时，list命令必须大写为LIST：

1	http://localhost:8983/solr/admin/configs?action=LIST&omitHeader=true

V2 API

使用v2 API时，当请求中没有发送数据时，隐含list命令。

1	http://localhost:8983/api/configsets?omitHeader=true

输出将如下所示：

{
  "configSets": [
    "_default",
    "techproducts",
    "gettingstarted"
  ]
}

上传配置集

上传配置集，作为压缩文件发送。也可以使用filePath参数上传单个非压缩文件。

此功能默认启用，但可以通过运行时参数-Dconfigset.upload.enabled=false禁用。如果您要将Solr安装暴露给不受信任的用户，建议禁用此功能（尽管您永远不应该这样做！）。

如果启用了身份验证并且上传操作作为已认证请求执行，则配置集以”受信任”模式上传。没有身份验证的情况下，配置集以”不受信任”模式上传。使用”不受信任”配置集创建集合时，以下功能将不起作用：

在请求处理时不能使用XSLT转换器（tr参数）。
如果在配置集中指定，ScriptUpdateProcessorFactory将不会初始化。
如果配置集中使用了<lib>指令，集合将不会初始化。
（注意：添加到Solr类路径的库不需要<lib>指令）

如果您使用任何这些参数或功能，您必须在Solr安装中启用安全功能，并且必须作为已认证用户上传配置集。

并非所有文件类型都支持在配置集中使用。请参见禁止的文件类型了解更多信息。

upload命令采用以下参数：

name

必需参数，默认值：无
上传完成时要创建的配置集

overwrite

可选参数，默认值：见描述
如果设置为true，Solr将覆盖同名的现有配置集（如果为false，请求将失败）
如果提供了filePath，则此选项指定如果配置集中的指定文件已存在，是否应覆盖它
使用v1 API时默认值为false，但使用v2 API时为true

cleanup

可选参数，默认值：false
覆盖现有配置集时（overwrite=true），此参数告诉Solr删除存在于旧配置集中但不在上传的配置集中的ZooKeeper文件
使用filePath时，此参数不能设置为true

filePath

可选参数，默认值：无
此参数允许将单个非压缩文件上传到ZooKeeper中配置集下的给定路径
此功能遵循overwrite参数，因此如果给定文件路径已存在于配置集中且overwrite设置为false，请求将失败
使用filePath时，cleanup参数不能设置为true

如果上传整个配置集，请求主体应该是包含配置集的zip文件。zip文件必须从conf目录内创建（即solrconfig.xml必须是zip文件中的顶级条目）。

以下是如何创建名为”myconfig.zip”的zip文件并将其作为名为”myConfigSet”的配置集上传的示例：

V1 API

使用v1 API时，upload命令必须大写为UPLOAD：

1
2
3

$ (cd solr/server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) > myconfigset.zip

$ curl -X POST --header "Content-Type:application/octet-stream" --data-binary @myconfigset.zip "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet"

同样可以使用Unix管道通过单个请求实现：

$ (cd server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) | curl -X POST --header "Content-Type:application/octet-stream" --data-binary @- "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet"

V2 API

使用v2 API时，要上传的配置集名称作为路径参数提供：

1
2
3

$ (cd solr/server/solr/configsets/sample_techproducts_configs/conf && zip -r - *) > myconfigset.zip

$ curl -X PUT --header "Content-Type:application/octet-stream" --data-binary @myconfigset.zip "http://localhost:8983/api/configsets/myConfigSet"

使用此API时，如果配置集已存在，默认行为是覆盖配置集。可以使用参数overwrite=false禁用此行为，在这种情况下，如果配置集已存在，请求将失败。

以下是如何将单个文件上传到名为”myConfigSet”的配置集的示例：

V1 API

使用v1 API时，upload命令必须大写为UPLOAD。要上传的文件名通过filePath参数提供：

curl -X POST --header "Content-Type:application/octet-stream" --data-binary @solr/server/solr/configsets/sample_techproducts_configs/conf/solrconfig.xml "http://localhost:8983/solr/admin/configs?action=UPLOAD&name=myConfigSet&filePath=solrconfig.xml&overwrite=true"

V2 API

使用v2 API时，配置集和文件的名称都在URL中提供。它们可以在/configsets/__config_name__/__file_name__中替换。文件名可能嵌套并包含/字符。

curl -X PUT --header "Content-Type:application/octet-stream" --data-binary @solr/server/solr/configsets/sample_techproducts_configs/conf/solrconfig.xml "http://localhost:8983/api/configsets/myConfigSet/solrconfig.xml"

使用此API时，如果文件已存在于配置集中，默认行为是覆盖文件。可以使用参数overwrite=false禁用此行为，在这种情况下，如果文件已存在于配置集中，请求将失败。

创建配置集

create命令基于先前上传的配置集创建新的配置集。

如果您尚未上传任何配置集，请参见上面的<<上传配置集>>命令。

创建配置集时支持以下参数。

name

必需参数，默认值：无
要创建的配置集

baseConfigSet

可选参数，默认值：_default
要作为基础复制的配置集名称

configSetProp.property=value

可选参数，默认值：无
要在复制的配置集中覆盖的基础配置集中的配置集属性

例如，要基于先前定义的”predefinedTemplate”配置集创建名为”myConfigset”的配置集，覆盖immutable属性为false。

V1 API

使用v1 API时，create命令必须大写为CREATE：

1	http://localhost:8983/solr/admin/configs?action=CREATE&name=myConfigSet&baseConfigSet=predefinedTemplate&configSetProp.immutable=false&wt=xml&omitHeader=true

V2 API

使用v2 API时，create命令是隐含的，参数在POST请求主体中指定。

curl -X POST -H 'Content-type: application/json' -d '{
  "name": "myConfigSet",
  "baseConfigSet": "predefinedTemplate",
  "properties": {
    "immutable": "false"
  }
}' http://localhost:8983/api/configsets?omitHeader=true

输出

<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">323</int>
  </lst>
</response>

删除配置集

delete命令删除配置集。它不会删除使用该配置集创建的任何集合。

name

必需参数，默认值：无
要删除的配置集

要删除名为”myConfigSet”的配置集：

V1 API

使用v1 API时，delete命令必须大写为DELETE。要删除的配置集名称通过name参数提供：

1	http://localhost:8983/solr/admin/configs?action=DELETE&name=myConfigSet&omitHeader=true

V2 API

使用v2 API时，delete命令作为请求方法提供，如-X DELETE。要删除的配置集名称作为路径参数提供：

1	curl -X DELETE http://localhost:8983/api/configsets/myConfigSet?omitHeader=true

输出

<response>
  <lst name="responseHeader">
    <int name="status">0</int>
    <int name="QTime">170</int>
  </lst>
</response>

最佳实践

配置集版本管理

建议对配置集进行版本管理，特别是在生产环境中：

命名约定：使用有意义的名称，包含版本信息，如myapp-v1.0、myapp-v1.1等
备份策略：在更新配置集之前，始终备份现有版本
测试验证：在非生产环境中彻底测试新配置集

安全考虑

启用认证：在生产环境中始终启用Solr认证以使用受信任模式
文件类型限制：了解并遵循配置集中禁止的文件类型规则
权限控制：限制可以上传和修改配置集的用户

性能优化

清理操作：定期清理不使用的配置集以保持ZooKeeper整洁
批量操作：对于多个文件更改，优先使用完整配置集上传而不是单个文件上传
监控使用情况：跟踪哪些配置集被哪些集合使用

故障排除

常见问题

上传失败：检查文件权限和网络连接
认证错误：确保用户具有适当的权限
ZooKeeper连接：验证ZooKeeper集群的健康状况

错误处理

重试机制：实现适当的重试逻辑处理临时网络问题
状态验证：上传后验证配置集是否正确创建
日志监控：监控Solr日志以获取详细错误信息

总结

Configsets API为SolrCloud环境中的配置管理提供了强大而灵活的解决方案。通过支持配置集的上传、创建、列出和删除操作，它简化了多集合环境中的配置共享和版本管理。合理使用此API，结合适当的安全措施和最佳实践，可以大大提高Solr集群的可维护性和配置一致性。

无论是在开发环境中进行快速配置迭代，还是在生产环境中进行精细的配置管理，Configsets API都提供了必要的工具来满足各种需求。通过理解其工作原理和限制，管理员可以构建更加健壮和可扩展的Solr解决方案。