Elasticsearch 参考指南（配置Elasticsearch）

配置Elasticsearch

Elasticsearch引擎具有良好的默认值，并且只需要很少的配置，可以使用集群更新设置API在运行的集群上更改大多数设置。

配置文件应该包含特定于节点的设置（例如node.name和路径），或节点为加入集群所需的设置，比如cluster.name和network.host。

配置文件位置

Elasticsearch有三个配置文件：

• elasticsearch.yml配置Elasticsearch
• jvm.options配置Elasticsearch JVM设置
• log4j2.properties配置Elasticsearch日志记录

这些文件位于config目录中，其默认位置取决于安装是否来自归档发行版（tar.gz或zip）或包发行版（Debian或RPM包）。

对于归档发行版，配置目录位置默认为$ES_HOME/config，可以通过ES_PATH_CONF环境变量更改配置目录的位置，如下所示：

ES_PATH_CONF=/path/to/my/config ./bin/elasticsearch

或者，你可以通过命令行或通过shell概要export ES_PATH_CONF环境变量。

对于包发行版，配置目录位置默认为/etc/elasticsearch，配置目录的位置也可以通过ES_PATH_CONF环境变量进行更改，但是请注意，在shell中设置这个是不够的。相反，这个变量来自/etc/default/elasticsearch（用于Debian包）和/etc/sysconfig/elasticsearch（用于RPM包），你需要在其中一个文件中编辑ES_PATH_CONF=/etc/elasticsearch条目，以更改配置目录的位置。

配置文件格式

配置格式是YAML，下面是更改数据和日志目录路径的一个示例：

path:
    data: /var/lib/elasticsearch
    logs: /var/log/elasticsearch

设置也可以按如下方式进行平坦化：

path.data: /var/lib/elasticsearch
path.logs: /var/log/elasticsearch

环境变量替换

配置文件中使用${…}符号引用的环境变量将被替换为环境变量的值，例如：

node.name:    ${HOSTNAME}
network.host: ${ES_NETWORK_HOST}

设置提示

设置提示已废弃，请对敏感属性值使用安全设置，并不是所有设置都可以转换为使用安全设置。

对于不希望存储在配置文件中的设置，你可以使用值${prompt.text}和${prompt.secret}并在前台运行Elasticsearch，${prompt.secret}已禁用响应，因此输入的值将不会显示在终端中；${prompt.text}将允许你在输入时查看值，例如：

node:
  name: ${prompt.text}

启动Elasticsearch时，会提示你输入如下的实际值：

Enter value for [node.name]:

如果在设置中使用 ${prompt.text}或 ${prompt.secret}，并且进程作为服务或后台运行，则不会启动Elasticsearch。

设置JVM选项

你几乎不需要更改Java虚拟机（JVM）选项，如果这样做，最可能的改变是设置堆大小，本文的其余部分详细解释了如何设置JVM选项。

设置JVM选项（包括系统属性和JVM标志）的首选方法是通过jvm.options配置文件，这个文件的默认位置是config/jvm.options（从tar或zip发行版安装时）和/etc/elasticsearch/jvm.options（从Debian或RPM包安装时）。

这个文件包含一个行分隔的JVM参数列表，它遵循一个特殊的语法：

• 只忽略由空格组成的行

• 以#开头的行被视为注释并被忽略

  # this is a comment

• 以-开头的行被视为独立于JVM版本的JVM选项

  -Xmx2g

• 以数字开头、后跟:、后跟-开头的行被视为只有在JVM版本与数字匹配时才适用的JVM选项

  8:-Xmx2g

• 以数字开头、后跟-、后跟:的行被视为只有当JVM版本大于或等于数字时才适用的JVM选项

  8-:-Xmx2g

• 以数字开头、后跟-、再跟数字、再跟:的行被视为只有当JVM的版本在两个数字的范围内时才适用的JVM选项

  8-9:-Xmx2g

• 所有其他行都被拒绝

你可以向该文件添加自定义JVM标志，并将此配置迁入到版本控制系统中。

设置Java虚拟机选项的另一种机制是通过ES_JAVA_OPTS环境变量，例如：

export ES_JAVA_OPTS="$ES_JAVA_OPTS -Djava.io.tmpdir=/path/to/temp/dir"
./bin/elasticsearch

当使用RPM或Debian包时，可以在系统配置文件中指定ES_JAVA_OPTS。

JVM有一个用于监听JAVA_TOOL_OPTIONS环境变量的内置机制，我们故意在打包脚本中忽略这个环境变量，这样做的主要原因是，在某些操作系统（例如Ubuntu）上，有一些代理是通过这个环境变量默认安装的，我们不希望干扰到Elasticsearch。

此外，其他一些Java程序支持JAVA_OPTS环境变量，这不是构建在JVM中的机制，而是生态系统中的约定，但是，我们不支持这个环境变量，而是支持通过JVM.options文件或如上面所示的ES_JAVA_OPTS环境变量设置JVM选项。

安全设置

有些设置是敏感的，仅依靠文件系统权限来保护它们的值是不够的，对于这个用例，Elasticsearch提供一个keystore和用于管理keystore中的设置的elasticsearch-keystore工具。

这里的所有命令都应该以运行Elasticsearch的用户运行。

只有一些设置被设计为从keystore中读取，请参阅每个设置的文档，以查看是否支持它作为keystore的一部分。

所有对keystore的修改只有在重新启动Elasticsearch之后才会生效。

Elasticsearch keystore目前只提供混淆，今后将增加密码保护。

这些设置，就像elasticsearch.yml配置文件中的常规设置一样，需要在集群中的每个节点上指定，目前，所有安全设置都是特定于节点的设置，每个节点上的值必须相同。

创建keystore

创建elasticsearch.keystore，使用create命令：

bin/elasticsearch-keystore create

elasticsearch.keystore文件将与elasticsearch.yml创建在一起。

列出keystore中的设置

keystore中的设置列表可以通过list命令获得：

bin/elasticsearch-keystore list

添加字符串设置

敏感的字符串设置，比如云插件的身份验证凭证，可以使用add命令添加：

bin/elasticsearch-keystore add the.setting.name.to.set

该工具将提示设置的值，要通过stdin传递值，请使用--stdin标志：

cat /file/containing/setting/value | bin/elasticsearch-keystore add --stdin the.setting.name.to.set

移除设置

要从密钥存储库中移除设置，请使用remove命令：

bin/elasticsearch-keystore remove the.setting.name.to.remove

可重新加载的安全设置

与elasticsearch.yml中的设置值一样，对keystore内容的更改不会自动应用于正在运行的elasticsearch节点，重新读取设置需要重新启动节点。但是，某些安全设置被标记为可重新加载，这样的设置可以重新读取，并应用于正在运行的节点。

所有安全设置的值，无论是否可重新加载，都必须在所有集群节点上相同，在使用bin/elasticsearch-keystore add命令进行所需的安全设置更改后，调用：

POST _nodes/reload_secure_settings

这个API将在每个集群节点上解密并重新读取整个keystore，但只应用可重新加载的安全设置，对其他设置的更改直到下一次重新启动才生效。一旦调用返回，重新加载就完成了，这意味着所有依赖于这些设置的内部数据结构都被更改了，一切都应该看起来好像设置从一开始就有了新的值。

在更改多个可重新加载的安全设置时，在每个集群节点上修改所有设置，然后发出reload_secure_settings调用，而不是在每次修改之后重新加载。

日志记录配置

Elasticsearch使用Log4j 2进行日志记录，可以使用log4j2.properties文件配置Log4j 2。Elasticsearch公开了三个属性，${sys:es.logs.base_path}、 ${sys:es.logs.cluster_name}和可以在配置文件中引用以确定日志文件位置的${sys:es.logs.node_name}（如果节点名通过node.name显式设置）。${sys:es.logs.base_path}属性将解析为日志目录，${sys:es.logs.cluster_name}将解析为集群名（在默认配置中用作日志文件名的前缀），${sys:es.logs.node_name}将解析为节点名（如果节点名被显式设置）。

例如：如果你的日志目录（path.log）是/var/log/elasticsearch，你的集群被命名为production，那么${sys:es.logs.base_path}将解析为/var/log/elasticsearch并且${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}.log将解析为/var/log/elasticsearch/production.log。

appender.rolling.type = RollingFile 
appender.rolling.name = rolling
appender.rolling.fileName = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}.log 
appender.rolling.layout.type = PatternLayout
appender.rolling.layout.pattern = [%d{ISO8601}][%-5p][%-25c{1.}] %marker%.-10000m%n
appender.rolling.filePattern = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}-%d{yyyy-MM-dd}-%i.log.gz 
appender.rolling.policies.type = Policies
appender.rolling.policies.time.type = TimeBasedTriggeringPolicy 
appender.rolling.policies.time.interval = 1 
appender.rolling.policies.time.modulate = true 
appender.rolling.policies.size.type = SizeBasedTriggeringPolicy 
appender.rolling.policies.size.size = 256MB 
appender.rolling.strategy.type = DefaultRolloverStrategy
appender.rolling.strategy.fileIndex = nomax
appender.rolling.strategy.action.type = Delete 
appender.rolling.strategy.action.basepath = ${sys:es.logs.base_path}
appender.rolling.strategy.action.condition.type = IfFileName 
appender.rolling.strategy.action.condition.glob = ${sys:es.logs.cluster_name}-* 
appender.rolling.strategy.action.condition.nested_condition.type = IfAccumulatedFileSize 
appender.rolling.strategy.action.condition.nested_condition.exceeds = 2GB 

• appender.rolling.type = RollingFile ：配置RollingFile输出源
• appender.rolling.fileName = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}.log：日志到/var/log/elasticsearch/production.log
• appender.rolling.filePattern = ${sys:es.logs.base_path}${sys:file.separator}${sys:es.logs.cluster_name}-%d{yyyy-MM-dd}-%i.log.gz：滚动日志到/var/log/elasticsearch/production-yyyy-MM-dd-i.log，日志将被压缩在每个滚动上，并且i将被递增。
• appender.rolling.policies.time.type = TimeBasedTriggeringPolicy：使用基于时间的滚动策略
• appender.rolling.policies.time.interval = 1：每天滚动日志
• appender.rolling.policies.time.modulate = true：在一天的边界上对齐滚动条(而不是每24小时滚动一次)
• appender.rolling.policies.size.type = SizeBasedTriggeringPolicy：使用基于大小的滚动策略
• appender.rolling.policies.size.size = 256MB：在256MB后滚动日志
• appender.rolling.strategy.action.type = Delete：在滚动日志时使用删除操作
• appender.rolling.strategy.action.condition.type = IfFileName：只删除匹配文件模式的日志
• appender.rolling.strategy.action.condition.glob = ${sys:es.logs.cluster_name}-*：模式是只删除主日志
• appender.rolling.strategy.action.condition.nested_condition.type = IfAccumulatedFileSize：只有当我们积累了太多的压缩日志时才删除
• appender.rolling.strategy.action.condition.nested_condition.exceeds = 2GB：压缩日志的大小条件是2GB

Log4j的配置解析会被任何无关的空格搞混乱，如果你复制并粘贴此页面上的任何Log4j设置，或者输入任何Log4j配置，请确保删除所有前导和后导空格。

注意，你可以在appender.rolling.filePattern使用.zip替换.gz，使用zip格式来压缩滚动日志，如果你删除了.gz扩展，那么日志在滚动时不会被压缩。

如果希望在指定的时间内保留日志文件，可以使用带删除操作的滚动策略。

appender.rolling.strategy.type = DefaultRolloverStrategy 
appender.rolling.strategy.action.type = Delete 
appender.rolling.strategy.action.basepath = ${sys:es.logs.base_path} 
appender.rolling.strategy.action.condition.type = IfFileName 
appender.rolling.strategy.action.condition.glob = ${sys:es.logs.cluster_name}-* 
appender.rolling.strategy.action.condition.nested_condition.type = IfLastModified 
appender.rolling.strategy.action.condition.nested_condition.age = 7D

• appender.rolling.strategy.type = DefaultRolloverStrategy：配置DefaultRolloverStrategy
• appender.rolling.strategy.action.type = Delete：配置用于处理滚动的删除操作
• appender.rolling.strategy.action.basepath = ${sys:es.logs.base_path}：Elasticsearch日志的基本路径
• appender.rolling.strategy.action.condition.type = IfFileName：在处理翻转时应用的条件
• appender.rolling.strategy.action.condition.glob = ${sys:es.logs.cluster_name}-*：从与全局${sys:es.logs.cluster_name}-匹配的基本路径中删除文件；这是日志滚动到的全局路径；这只需要删除滚动的Elasticsearch*日志，而不需要删除弃用日志和慢速日志
• appender.rolling.strategy.action.condition.nested_condition.type = IfLastModified：适用于与全局匹配的文件的嵌套条件
• appender.rolling.strategy.action.condition.nested_condition.age = 7D：将日志保存7天

只要名为log4j2.properties并且将Elasticsearch config目录作为一个父目录，多个配置文件就可以被加载（在这种情况下，它们将被合并）。这对于显示其他日志记录器的插件非常有用，日志记录器部分包含java包及其相应的日志级别，输出源部分包含日志的目的地，在Log4j文档中可以找到关于如何自定义日志记录和所有支持的输出源的详细信息。

配置日志级别

有四种配置日志级别的方法，每种方法都有适合使用的情况。

1. 通过命令行：-E <name of logging hierarchy>=<level>（例如，-E logger.org.elasticsearch.transport=trace），当你临时调试单个节点上的问题（例如，启动或开发期间的问题）时，这是最合适的。
2. 通过elasticsearch.yml：<name of logging hierarchy>: <level>（例如，logger.org.elasticsearch.transport:trace），当你正在临时调试一个问题，但是没有通过命令行（例如，通过服务）启动Elasticsearch时，这是最合适的，或者你希望在更长期的基础上调整日志级别。

3. 通过集群设置：

   PUT /_cluster/settings
   {
     "transient": {
       "<name of logging hierarchy>": "<level>"
     }
   }

   例如：

   PUT /_cluster/settings
   {
     "transient": {
       "logger.org.elasticsearch.transport": "trace"
     }
   }

   当你需要动态地调整活动运行集群上的日志记录级别时，这是最合适的。

4. 通过log4j2.properties

   logger.<unique_identifier>.name = <name of logging hierarchy>
   logger.<unique_identifier>.level = <level>

   例如：

   logger.transport.name = org.elasticsearch.transport
   logger.transport.level = trace

   这是最合适你需要对日志记录器进行细粒度控制的方式（例如，你希望将日志记录器发送到另一个文件，或者以不同的方式管理日志记录器时;这是一个罕见的用例）。

弃用日志记录

除了常规日志记录之外，Elasticsearch允许对弃用的动作进行日志记录，例如，这允许你尽早确定如果你需要在将来迁移某些功能。默认情况下，在警告级别启用弃用日志记录，警告级别是发出所有弃用日志消息的级别。

logger.deprecation.level = warn

这将在你的日志目录中创建一个每日滚动弃用日志文件，定期检查这个文件，特别是当你打算升级到一个新的主要版本时。

默认日志配置设置了弃用日志的滚动策略，以便在1GB之后滚动和压缩，并保存最多5个日志文件（4个滚动日志和一个活动日志）。

可以在config/log4j2.properties文件中禁用它，设置弃用日志级别为error。