配置项作用 #
path.home 配置项用于指定Easysearch 的安装根目录。
这是 Easysearch 配置中最基础也是最重要的路径设置，作为所有其他相对路径的基准。包含二进制文件、配置文件、模块、插件等核心组件。
配置项属性 #
- 配置路径:
path.home - 数据类型:
String（目录路径） - 默认值: 无（必须配置）
- 是否可选: 否（必须配置）
- 作用域: NodeScope（节点级别）
- 动态更新: 否（需要重启节点生效）
配置项详解 #
工作机制 #
path.home 工作机制
启动检查:
path.home 必须配置
│
├── 未配置 → 抛出异常 ❌
│ └── IllegalStateException: path.home is not configured
│
├── 已配置 → 验证目录
│ ├── 目录存在 → 继续 ✅
│ └── 目录不存在 → 可能失败
│
└── 解析为绝对路径
├── 规范化路径
└── 作为基准路径
设置方式:
1. 启动脚本自动设置
bin/easysearch → 自动设置 ES_HOME
2. 系统属性
-Des.path.home=/usr/share/easysearch
3. 配置文件
path.home: /usr/share/easysearch
路径解析:
path.home: /usr/share/easysearch
│
├── path.data: ${path.home}/data (如果未设置)
├── path.logs: ${path.home}/logs (如果未设置)
├── path.repo: 可配置
└── 所有相对路径基于此
目录结构 #
path.home 目录结构
/usr/share/easysearch/ (path.home)
├── bin/ # 可执行脚本
│ ├── easysearch # 主启动脚本
│ ├── easysearch-plugin # 插件管理
│ └── ...
│
├── config/ # 配置目录 (或 ES_PATH_CONF)
│ ├── easysearch.yml # 主配置文件
│ ├── jvm.options # JVM 配置
│ ├── log4j2.properties # 日志配置
│ └── ...
│
├── data/ # 数据目录 (默认)
│ └── nodes/
│
├── logs/ # 日志目录 (默认)
│ ├── cluster.log
│ └── ...
│
├── plugins/ # 插件目录
│ ├── analysis-icu/
│ ├── ingest-geoip/
│ └── ...
│
├── lib/ # Java 库
│ └── *.jar
│
├── modules/ # 模块目录
│ ├── aggs-matrix-stats/
│ ├── analysis-common/
│ └── ...
│
└── jdk/ # 内置 JDK (某些发行版)
└── ...
默认路径解析 #
其他路径的默认解析规则
path.home: /usr/share/easysearch
1. path.data
如果未设置 → ${path.home}/data
如果设置 → 使用指定路径
2. path.logs
如果未设置 → ${path.home}/logs
如果设置 → 使用指定路径
3. 配置目录
如果 ES_PATH_CONF 未设置 → ${path.home}/config
如果 ES_PATH_CONF 设置 → 使用指定路径
4. 插件目录
始终 → ${path.home}/plugins
5. 模块目录
始终 → ${path.home}/modules
示例:
path.home: /opt/easysearch
未设置其他路径时:
├── data: /opt/easysearch/data
├── logs: /opt/easysearch/logs
└── config: /opt/easysearch/config
启动脚本处理 #
启动脚本如何处理 path.home
bin/easysearch 脚本:
#!/bin/bash
...
# 设置 ES_HOME
if [ -z "$ES_HOME" ]; then
ES_HOME="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
fi
export ES_HOME
# 添加 JVM 参数
ES_JAVA_OPTS="$ES_JAVA_OPTS -Des.path.home=$ES_HOME"
# 启动
$JAVA $ES_JAVA_OPTS \
-Des.path.home="$ES_HOME" \
-Des.path.conf="$ES_PATH_CONF" \
...
org.easysearch.bootstrap.Easysearch
结果:
├── ES_HOME 自动检测
├── path.home 自动设置
└── 通常无需手动配置
配置建议 #
标准安装（自动） #
# 不需要配置，启动脚本自动设置
# path.home 由 bin/easysearch 脚本自动检测
建议: 标准安装不需要手动配置 path.home。
手动指定 #
path:
home: /opt/easysearch
建议: 仅在需要覆盖自动检测时配置。
多实例部署 #
# 实例 1
path:
home: /opt/easysearch-instance-1
# 实例 2
path:
home: /opt/easysearch-instance-2
建议: 多实例部署使用不同的安装目录。
测试环境 #
path:
home: /tmp/easysearch-test
建议: 测试环境可以使用临时目录。
代码示例 #
自动配置（推荐） #
# 标准启动，无需配置
./bin/easysearch
手动指定路径 #
# easysearch.yml
path:
home: /opt/easysearch
系统属性方式 #
# 启动时指定
./bin/easysearch -Des.path.home=/opt/easysearch
多实例配置 #
# 实例 1
path:
home: /opt/easysearch-1
data: /data/easysearch-1
logs: /var/log/easysearch-1
# 实例 2
path:
home: /opt/easysearch-2
data: /data/easysearch-2
logs: /var/log/easysearch-2
环境变量配置 #
# 设置环境变量
export ES_HOME=/opt/easysearch
# 启动脚本会使用 ES_HOME
./bin/easysearch
相关配置 #
| 配置项 | 作用 | 默认值 |
|---|---|---|
path.home | 安装根目录 | 自动检测 |
path.data | 数据目录 | ${path.home}/data |
path.logs | 日志目录 | ${path.home}/logs |
path.repo | 快照仓库目录 | - |
ES_PATH_CONF | 配置目录环境变量 | ${path.home}/config |
环境变量 #
相关环境变量
1. ES_HOME
├── 通常由启动脚本设置
├── 指向 Easysearch 安装目录
└── 用于设置 path.home
2. ES_PATH_CONF
├── 配置目录路径
├── 优先级高于 path.home/config
├── 用法: export ES_PATH_CONF=/etc/easysearch
└── 允许配置文件分离
3. ES_JAVA_OPTS
├── JVM 参数
├── 可以覆盖 path.home
├── 示例: -Des.path.home=/opt/es
└── 不推荐覆盖
优先级:
命令行参数 > ES_JAVA_OPTS > 配置文件 > 自动检测
推荐:
├── 使用默认自动检测 ✅
├── 仅在必要时覆盖
└── 使用 ES_PATH_CONF 分离配置
使用场景 #
标准单机安装 #
标准安装场景
目录结构:
/usr/share/easysearch/ # path.home (安装目录)
├── bin/
├── config/
├── data/ → /var/lib/easysearch (推荐)
├── logs/ → /var/log/easysearch (推荐)
├── plugins/
└── modules/
配置:
# 不需要配置 path.home
path:
data: /var/lib/easysearch
logs: /var/log/easysearch
多实例部署 #
多实例场景
实例 1:
/opt/easysearch-instance-1/ # path.home
├── bin/
├── config/
└── ...
实例 2:
/opt/easysearch-instance-2/ # path.home
├── bin/
├── config/
└── ...
优势:
├── 独立升级
├── 配置隔离
├── 资源隔离
└── 故障隔离
开发环境 #
开发环境场景
目录:
~/dev/easysearch/ # path.home
├── bin/
├── config/
├── data/ # 本地数据
└── logs/ # 本地日志
优势:
├── 简单配置
├── 快速部署
└── 便于调试
生产环境 #
生产环境推荐
目录分离:
/usr/share/easysearch/ # path.home (只读)
├── bin/
├── config/ → /etc/easysearch
├── data/ → /var/lib/easysearch
├── logs/ → /var/log/easysearch
└── modules/
配置:
# easysearch.yml (可选)
path:
home: /usr/share/easysearch
# 或使用环境变量
export ES_PATH_CONF=/etc/easysearch
权限要求 #
目录权限要求
1. path.home
├── 读取: 需要 (bin, modules, lib)
├── 执行: 需要 (bin 脚本)
├── 写入: 通常不需要
└── 推荐: 755 (drwxr-xr-x)
2. path.data
├── 读写: 必须 ✅
├── 执行: 必须 ✅
└── 推荐: 750 或 755
3. path.logs
├── 读写: 必须 ✅
├── 执行: 必须 ✅
└── 推荐: 755
4. config 目录
├── 读取: 必须 ✅
└── 推荐: 644 (文件), 755 (目录)
设置权限:
sudo chown -R easysearch:easysearch /usr/share/easysearch
sudo chmod -R 755 /usr/share/easysearch
sudo chmod 750 /var/lib/easysearch
sudo chmod 755 /var/log/easysearch
注意事项 #
必须配置: 这是必需配置，未配置会导致启动失败。
自动检测: 启动脚本会自动设置，通常不需要手动配置。
绝对路径: 建议使用绝对路径。
目录存在: 目录必须存在且可访问。
权限正确: 运行用户需要读取权限。
不可变: 运行时不能修改。
基础路径: 其他相对路径基于此目录。
配置分离: 可以使用 ES_PATH_CONF 分离配置。
多实例: 不同实例使用不同的 home 目录。
升级注意: 升级时保持 home 目录结构一致。
故障排查 #
常见问题排查
问题 1: 启动失败 - path.home not configured
错误:
IllegalStateException: path.home is not configured
原因:
├── 启动脚本问题
├── 环境变量问题
└── 配置文件问题
解决:
├── 使用标准启动脚本
├── 检查 ES_HOME 环境变量
├── 在配置文件中设置
└── 验证目录权限
问题 2: 找不到文件或目录
错误:
FileNotFoundException: /path/to/file
检查:
├── path.home 是否正确
├── 相对路径是否基于正确的 home
└── 文件是否真的存在
解决:
├── 验证 path.home 设置
├── 使用绝对路径
└── 检查目录结构
问题 3: 权限错误
错误:
AccessDeniedException: /usr/share/easysearch
解决:
├── 检查目录所有者
├── 修改文件权限
├── 使用正确的用户运行
└── 验证 SELinux/AppArmor
最佳实践 #
path.home 最佳实践
1. 标准安装
├── 使用官方发行版
├── 保持默认结构
├── 让脚本自动设置
└── 最少配置 ✅
2. 生产环境
├── 分离数据和日志
├── 使用绝对路径
├── 保持 home 只读
└── 配置文件分离
3. 多实例
├── 不同 home 目录
├── 独立配置
├── 独立数据
└── 独立日志
4. 容器化
├── 固定安装路径
├── 挂载数据和日志
├── 保持 home 只读
└── 使用环境变量
5. 开发环境
├── 简化配置
├── 本地目录
├── 快速迭代
└── 便于调试
