---
title: "Easysearch 安装目录配置"
date: 2026-03-12
lastmod: 2026-03-12
description: "path.home 配置项用于指定 Easysearch 的安装根目录，是所有其他路径的基础。"
tags: ["Path", "目录配置", "安装路径", "环境配置"]
summary: "配置项作用 #  path.home 配置项用于指定Easysearch 的安装根目录。
这是 Easysearch 配置中最基础也是最重要的路径设置，作为所有其他相对路径的基准。包含二进制文件、配置文件、模块、插件等核心组件。
配置项属性 #   配置路径: path.home 数据类型: String（目录路径） 默认值: 无（必须配置） 是否可选: 否（必须配置） 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效）  配置项详解 #  工作机制 #  path.home 工作机制 启动检查: path.home 必须配置 │ ├── 未配置 → 抛出异常 ❌ │ └── IllegalStateException: path.home is not configured │ ├── 已配置 → 验证目录 │ ├── 目录存在 → 继续 ✅ │ └── 目录不存在 → 可能失败 │ └── 解析为绝对路径 ├── 规范化路径 └── 作为基准路径 设置方式: 1."
---


## 配置项作用

`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 自动设置
└── 通常无需手动配置
```

## 配置建议

## 标准安装（自动）

```yaml
# 不需要配置，启动脚本自动设置
# path.home 由 bin/easysearch 脚本自动检测
```

**建议**: 标准安装不需要手动配置 `path.home`。

## 手动指定

```yaml
path:
  home: /opt/easysearch
```

**建议**: 仅在需要覆盖自动检测时配置。

## 多实例部署

```yaml
# 实例 1
path:
  home: /opt/easysearch-instance-1

# 实例 2
path:
  home: /opt/easysearch-instance-2
```

**建议**: 多实例部署使用不同的安装目录。

## 测试环境

```yaml
path:
  home: /tmp/easysearch-test
```

**建议**: 测试环境可以使用临时目录。

## 代码示例

## 自动配置（推荐）

```bash
# 标准启动，无需配置
./bin/easysearch
```

## 手动指定路径

```yaml
# easysearch.yml
path:
  home: /opt/easysearch
```

## 系统属性方式

```bash
# 启动时指定
./bin/easysearch -Des.path.home=/opt/easysearch
```

## 多实例配置

```yaml
# 实例 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
```

## 环境变量配置

```bash
# 设置环境变量
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
```

## 注意事项

1. **必须配置**: 这是必需配置，未配置会导致启动失败。

2. **自动检测**: 启动脚本会自动设置，通常不需要手动配置。

3. **绝对路径**: 建议使用绝对路径。

4. **目录存在**: 目录必须存在且可访问。

5. **权限正确**: 运行用户需要读取权限。

6. **不可变**: 运行时不能修改。

7. **基础路径**: 其他相对路径基于此目录。

8. **配置分离**: 可以使用 ES_PATH_CONF 分离配置。

9. **多实例**: 不同实例使用不同的 home 目录。

10. **升级注意**: 升级时保持 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. 开发环境
   ├── 简化配置
   ├── 本地目录
   ├── 快速迭代
   └── 便于调试
```