--- title: "节点 PID 文件配置" date: 2026-02-05 lastmod: 2026-02-05 description: "node.pidfile 配置项用于指定节点进程 ID（PID）文件的存储路径。" tags: ["Node", "进程管理", "PID文件", "服务控制"] summary: "配置项作用 # node.pidfile 配置项用于指定节点进程 ID（PID）文件的存储路径。 PID 文件包含运行中的 Easysearch 节点的进程 ID，用于进程管理和服务控制。当节点启动时，其 PID 会被写入指定的文件；当节点正常关闭时，文件会被删除。 配置项属性 # 配置路径: node.pidfile 数据类型: String（文件路径字符串） 默认值: 无（不创建 PID 文件） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 否（需要重启节点生效） 配置项详解 # 工作机制 # PID 文件工作机制 启动流程: node.pidfile: /var/run/easysearch/node.pid │ ├── 1. 检查配置 │ └── 配置存在 → 继续 │ ├── 2. 创建父目录 │ ├── 目录不存在 → 创建 │ └── 创建成功 → 继续 │ ├── 3. 写入 PID │ ├── 获取当前进程 ID │ ├── 例如: 12345 │ └── 写入文件 │ └── 4." --- ## 配置项作用 `node.pidfile` 配置项用于指定**节点进程 ID（PID）文件的存储路径**。 PID 文件包含运行中的 Easysearch 节点的进程 ID，用于进程管理和服务控制。当节点启动时，其 PID 会被写入指定的文件；当节点正常关闭时，文件会被删除。 ## 配置项属性 - **配置路径**: `node.pidfile` - **数据类型**: `String`（文件路径字符串） - **默认值**: 无（不创建 PID 文件） - **是否可选**: 是 - **作用域**: NodeScope（节点级别） - **动态更新**: 否（需要重启节点生效） ## 配置项详解 ## 工作机制 ``` PID 文件工作机制 启动流程: node.pidfile: /var/run/easysearch/node.pid │ ├── 1. 检查配置 │ └── 配置存在 → 继续 │ ├── 2. 创建父目录 │ ├── 目录不存在 → 创建 │ └── 创建成功 → 继续 │ ├── 3. 写入 PID │ ├── 获取当前进程 ID │ ├── 例如: 12345 │ └── 写入文件 │ └── 4. 注册关闭钩子 ├── 正常关闭时删除文件 └── 清理资源 关闭流程: ├── 接收关闭信号 ├── 执行关闭钩子 ├── 删除 PID 文件 └── 进程退出 异常退出: ├── 进程崩溃 ├── PID 文件残留 └── 需要手动清理 ``` ## 文件内容格式 ``` PID 文件内容 文件位置: /var/run/easysearch/node.pid 文件内容: 12345 │ └── 进程 ID (PID) 读取 PID: $ cat /var/run/easysearch/node.pid 12345 验证进程: $ ps -p 12345 PID TTY TIME CMD 12345 ? 00:15:32 java 停止服务: $ kill $(cat /var/run/easysearch/node.pid) ``` ## 服务管理集成 ``` 与系统集成 systemd 服务: ┌────────────────────────────────────┐ │ [Service] │ │ PIDFile=/var/run/easysearch/node.pid│ │ ExecStart=/usr/bin/easysearch │ │ ExecStop=/usr/bin/killcat $PIDFile │ │ Type=forking │ └────────────────────────────────────┘ init.d 脚本: start() { daemon --pidfile=$PIDFILE $ES_BIN } stop() { killproc -p $PIDFILE $ES_BIN } status() { status -p $PIDFILE $ES_BIN } Docker 容器: ├── 使用 PID 文件跟踪进程 ├── 优雅关闭 └── 健康检查 ``` ## 配置建议 ## 生产环境（推荐） ```yaml node: pidfile: /var/run/easysearch/node.pid ``` **建议**: 生产环境应配置 PID 文件。便于服务管理。 ## 开发环境 ```yaml # 不配置 PID 文件 node.name: "dev-node" # node.pidfile 不设置 ``` **建议**: 开发环境可以不配置，简化设置。 ## 多节点环境 ```yaml node: name: "node-1" pidfile: /var/run/easysearch/node-1.pid ``` **建议**: 每个节点使用独立的 PID 文件名。 ## 临时目录 ```yaml node: pidfile: /tmp/easysearch-node.pid ``` **建议**: 仅在无 /var/run 权限时使用。 ## 代码示例 ## easysearch.yml 基础配置 ```yaml node: pidfile: /var/run/easysearch/node.pid ``` ## 多实例配置 ```yaml # 节点 1 node: name: "es-node-1" pidfile: /var/run/easysearch/es-node-1.pid # 节点 2 node: name: "es-node-2" pidfile: /var/run/easysearch/es-node-2.pid ``` ## systemd 服务集成 ```yaml node: pidfile: /var/run/easysearch/pid ``` ```ini # /etc/systemd/system/easysearch.service [Service] Type=forking PIDFile=/var/run/easysearch/pid ExecStart=/usr/share/easysearch/bin/easysearch -d -p /var/run/easysearch/pid ``` ## 自定义路径 ```yaml node: pidfile: /opt/easysearch/run/node.pid ``` ## 相关配置 | 配置项 | 作用 | 默认值 | |--------|------|--------| | `node.pidfile` | PID 文件路径 | 无 | | `node.portsfile` | 端口文件开关 | false | | `node.name` | 节点名称 | 机器主机名 | ## 命令行选项 ``` 命令行使用 easysearch 脚本选项: ./bin/easysearch -d -p /path/to/pidfile │ │ │ └── 指定 PID 文件 └── 后台运行 等价于配置文件: node: pidfile: /path/to/pidfile 查看 PID: cat /path/to/pidfile 12345 停止节点: kill -SIGTERM $(cat /path/to/pidfile) ``` ## 使用场景 ## 推荐配置 PID 文件的场景 - **生产环境**: 需要标准的服务管理 - **系统服务**: 使用 systemd、init.d 等服务管理器 - **进程监控**: 需要跟踪进程状态 - **自动化脚本**: 启停脚本需要知道进程 ID - **容器环境**: Docker 容器内的进程管理 ## 推荐不配置 PID 文件的场景 - **开发环境**: 简化配置 - **测试环境**: 短期运行的节点 - **手动管理**: 不需要自动化服务管理 ## 目录权限 ``` 目录权限要求 /var/run/easysearch/: ├── 所有者: easysearch 用户 ├── 权限: 755 (drwxr-xr-x) └── 用途: 存储运行时文件 创建目录: sudo mkdir -p /var/run/easysearch sudo chown easysearch:easysearch /var/run/easysearch sudo chmod 755 /var/run/easysearch 配置: node: pidfile: /var/run/easysearch/node.pid 临时目录替代: node: pidfile: /tmp/easysearch-node.pid ``` ## 服务管理示例 ``` 使用 PID 文件管理服务 启动服务: #!/bin/bash PIDFILE="/var/run/easysearch/node.pid" # 检查是否已运行 if [ -f "$PIDFILE" ]; then PID=$(cat "$PIDFILE") if ps -p "$PID" > /dev/null 2>&1; then echo "Service already running (PID: $PID)" exit 1 fi fi # 启动服务 ./bin/easysearch -d -p "$PIDFILE" echo "Service started" 停止服务: #!/bin/bash PIDFILE="/var/run/easysearch/node.pid" if [ -f "$PIDFILE" ]; then PID=$(cat "$PIDFILE") kill -SIGTERM "$PID" rm -f "$PIDFILE" echo "Service stopped" else echo "Service not running" fi 重启服务: #!/bin/bash ./stop.sh sleep 5 ./start.sh 状态检查: #!/bin/bash PIDFILE="/var/run/easysearch/node.pid" if [ -f "$PIDFILE" ]; then PID=$(cat "$PIDFILE") if ps -p "$PID" > /dev/null 2>&1; then echo "Service running (PID: $PID)" else echo "PID file exists but process not running" fi else echo "Service not running" fi ``` ## 注意事项 1. **默认值**: 默认不创建 PID 文件。 2. **需要重启**: 修改此配置需要重启节点。 3. **目录权限**: 确保指定目录有写权限。 4. **文件清理**: 异常退出时 PID 文件可能残留。 5. **多节点**: 每个节点使用独立的 PID 文件。 6. **路径选择**: 生产环境推荐使用 /var/run。 7. **服务集成**: 与 systemd/init.d 集成时建议配置。 8. **关闭钩子**: 正常关闭会自动删除文件。 9. **持久化**: 重启后 PID 会变化。 10. **监控**: 可用于监控进程健康状态。 ## 故障排查 ``` PID 文件常见问题 问题 1: 启动失败 错误: Cannot create PID file 原因: ├── 目录不存在 ├── 目录无写权限 └── 磁盘空间不足 解决: ├── 创建目录: mkdir -p /var/run/easysearch ├── 设置权限: chown easysearch:easysearch /var/run/easysearch └── 检查空间: df -h 问题 2: 旧 PID 文件残留 现象: 服务无法启动，提示已运行 原因: ├── 上次异常退出 ├── PID 文件未删除 └── 进程实际不存在 解决: ├── 检查进程: ps -p $(cat pidfile) ├── 确认不存在: 删除旧文件 └── 或清理: rm -f /var/run/easysearch/node.pid 问题 3: 多实例冲突 现象: 两个实例使用同一 PID 文件 原因: ├── 配置相同 └── 路径未区分 解决: ├── 使用不同名称 ├── node-1.pid, node-2.pid └── 或包含节点名 ``` ## 最佳实践 ``` PID 文件最佳实践 1. 标准位置 node: pidfile: /var/run/easysearch/node.pid 2. 权限控制 ├── 目录所有者: easysearch 用户 ├── 文件权限: 644 └── 目录权限: 755 3. 服务集成 ├── systemd: 使用 PIDFile 指令 ├── init.d: 使用 killproc 函数 └── 监控: 基于 PID 健康检查 4. 多实例部署 ├── 不同节点名 ├── 不同 PID 文件 └── 避免冲突 5. 清理机制 ├── 正常关闭: 自动删除 ├── 异常退出: 启动前检查 └── 或phaned: 定期清理 ```