环境变量参考

环境变量参考 #

Easysearch 支持通过环境变量控制启动行为、JVM 设置和运行路径等。本页提供所有支持的环境变量的完整参考。

核心环境变量 #

变量说明默认值
ES_HOMEEasysearch 安装根目录从启动脚本位置自动推断
ES_PATH_CONF配置文件目录路径$ES_HOME/config
ES_JAVA_HOME自定义 Java 安装路径(推荐使用此变量)未设置(优先使用内置 JDK)
JAVA_HOMEJava 安装路径(后备方案,ES_JAVA_HOME 优先)系统默认
ES_JAVA_OPTS附加 JVM 选项,如堆大小
ES_TMPDIR临时文件目录自动创建
ES_STARTUP_SLEEP_TIME后台启动后的等待时间(秒)未设置

JDK 选择优先级 #

Easysearch 按以下优先级选择 Java 运行环境:

1. 内置 JDK($ES_HOME/jdk)       ← 最优先,推荐使用
2. ES_JAVA_HOME 环境变量          ← 无内置 JDK 时使用
3. JAVA_HOME 环境变量             ← 最终后备方案

建议:使用 Easysearch 自带的内置 JDK,除非有特殊需求需要使用其他 Java 版本。

路径相关 #

ES_PATH_CONF #

指定配置文件目录,该目录下需包含 easysearch.ymljvm.optionslog4j2.properties 等配置文件。

# 使用自定义配置目录
export ES_PATH_CONF=/etc/easysearch
bin/easysearch

或在启动命令中内联设置:

ES_PATH_CONF=/opt/config bin/easysearch -d

ES_TMPDIR #

Easysearch 启动时会在 $ES_TMPDIR(或系统临时目录)下创建一个专用的临时目录。如果需要指定临时文件位置:

export ES_TMPDIR=/data/easysearch/tmp

JVM 相关 #

ES_JAVA_OPTS #

覆盖或追加 JVM 选项。最常见的用途是设置堆大小:

export ES_JAVA_OPTS="-Xms8g -Xmx8g"
bin/easysearch

注意ES_JAVA_OPTS 中的值会追加到 jvm.options 文件中的设置之后,因此可以覆盖 jvm.options 中的同名选项。

被忽略的变量 #

以下 Java 相关环境变量会被 Easysearch 启动脚本主动忽略,并输出警告信息:

变量处理方式替代方案
JAVA_TOOL_OPTIONS取消设置,输出警告使用 ES_JAVA_OPTS
JAVA_OPTS忽略,输出警告使用 ES_JAVA_OPTS

在配置文件中引用环境变量 #

easysearch.yml 支持使用 ${...} 语法引用环境变量的值:

# 使用环境变量设置集群名称
cluster.name: ${CLUSTER_NAME}

# 使用环境变量设置网络地址
network.host: ${ES_NETWORK_HOST}

# 带默认值(如果环境变量未设置,使用默认值)
node.name: ${HOSTNAME:my-node}

使用示例:

export CLUSTER_NAME=production
export ES_NETWORK_HOST=0.0.0.0
bin/easysearch

提示:任何自定义环境变量都可以在 easysearch.yml 中通过 ${VAR_NAME} 引用,不限于以 ES_ 开头的变量。

Docker 环境特有变量 #

在 Docker 部署模式下,Easysearch 支持一些额外的环境变量和特殊行为:

变量说明
EASYSEARCH_INITIAL_ADMIN_PASSWORD初始管理员密码
ELASTIC_PASSWORDelastic 用户密码
ELASTIC_PASSWORD_FILE从文件读取 elastic 密码(与 ELASTIC_PASSWORD 互斥)
KEYSTORE_PASSWORDKeystore 密码
KEYSTORE_PASSWORD_FILE从文件读取 keystore 密码(与 KEYSTORE_PASSWORD 互斥)

Docker 中的自动设置转换 #

在 Docker 部署中,任何包含点号的环境变量会自动转换为 -E 命令行参数:

# Docker 环境变量
cluster.name=my_cluster
network.host=0.0.0.0
discovery.type=single-node

# 自动转换为启动参数
bin/easysearch -Ecluster.name=my_cluster -Enetwork.host=0.0.0.0 -Ediscovery.type=single-node

Docker Compose 示例:

services:
  easysearch:
    image: infinilabs/easysearch:latest
    environment:
      - cluster.name=my_cluster
      - node.name=node-1
      - discovery.type=single-node
      - EASYSEARCH_INITIAL_ADMIN_PASSWORD=my_password
      - ES_JAVA_OPTS=-Xms4g -Xmx4g

_FILE 后缀变量 #

支持 _FILE 后缀的变量用于从文件读取敏感信息(配合 Docker Secrets 使用):

services:
  easysearch:
    environment:
      - ELASTIC_PASSWORD_FILE=/run/secrets/elastic_password
    secrets:
      - elastic_password
secrets:
  elastic_password:
    file: ./elastic_password.txt

要求_FILE 指向的文件权限必须为 400600,且与非 _FILE 变体互斥。

系统属性 #

Easysearch 启动时会自动设置以下 Java 系统属性:

系统属性来源说明
es.path.home$ES_HOME安装根目录
es.path.conf$ES_PATH_CONF配置目录
es.distribution.flavor构建时确定发行版类型
es.distribution.type构建时确定安装方式(tar/docker/rpm)
es.bundled_jdk构建时确定是否包含内置 JDK

架构相关行为 #

架构特殊行为
arm64 / aarch64JVM 启动参数包含 -Xshare:off(禁用 CDS)
其他架构JVM 使用 -Xshare:auto(自动使用 CDS,映射失败时回退)

配置方式总览 #

Easysearch 支持多种配置方式,适用于不同场景:

方式适用场景持久性安全性
easysearch.yml固定配置(路径、网络、发现)✅ 持久⚠️ 明文
-E 命令行参数临时覆盖、测试❌ 临时⚠️ 进程列表可见
环境变量 + ${...}容器化部署、不同环境差异化❌ 临时⚠️ 明文
Keystore敏感信息(密码、密钥)✅ 持久✅ 加密
jvm.options / jvm.options.d/JVM 参数✅ 持久N/A
_cluster/settings API动态集群设置✅/❌N/A