Elasticsearch-HQ 安装与配置完全指南
概述
Elasticsearch-HQ 是一个功能强大的 Elasticsearch 集群监控和管理工具，提供了直观的 Web 界面来监控集群状态、索引性能、节点信息等关键指标。本文将详细介绍 Elasticsearch-HQ 的安装方法和配置选项，帮助您快速搭建和使用这一工具。
安装方式选择
Elasticsearch-HQ 提供了多种安装方式，您可以根据实际需求选择最适合的一种：
1. Docker 快速安装（推荐）
对于大多数用户，我们推荐使用 Docker 方式安装，这是最简单快捷的方法：
docker run -p 5000:5000 elastichq/elasticsearch-hq
安装完成后，通过浏览器访问 http://localhost:5000 即可使用。
Docker 版本说明：
latest标签：最新的稳定版本develop标签：开发中的不稳定版本
环境变量配置：
可以通过 -e 参数传递环境变量，例如：
docker run -p 5000:5000 -e HQ_DEFAULT_URL='http://your-es-cluster:9200' elastichq/elasticsearch-hq
2. 源码安装
如果您需要更灵活的定制，可以选择源码安装方式：
系统要求：
- Python 3.4 或更高版本
- 支持 Elasticsearch 2.x、5.x、6.x 和 7.x 版本
安装步骤：
- 获取项目源码
- 安装依赖：
pip install -r requirements.txt - 启动服务：
python3 application.py - 访问：
http://localhost:5000
初始配置
首次登录
启动后访问 http://localhost:5000，您将看到登录界面。在输入框中填写 Elasticsearch 集群的地址，格式为：
- 基本格式：
http://DOMAIN:PORT - 启用 HTTPS：
https://DOMAIN:PORT - 基础认证：
http://USERNAME:PASSWORD@DOMAIN:PORT
命令行参数配置
启动脚本 application.py 支持多种参数：
| 参数 | 默认值 | 描述 |
|---|---|---|
--host |
127.0.0.1 | 服务监听地址 |
--port |
5000 | 服务监听端口 |
--debug |
False | 启用调试模式 |
--url |
http://localhost:9200 |
默认显示的 ES 地址 |
--enable-ssl |
False | 启用 SSL 支持 |
--ca-certs |
/path/to/your/ca.crt | CA 证书路径 |
--verify_certs |
True | 是否验证证书 |
示例：
python -m application --enable-ssl --ca-certs /path/to/ca.crt
环境变量配置
也可以通过环境变量进行配置：
| 环境变量 | 默认值 | 描述 |
|---|---|---|
HQ_DEFAULT_URL |
http://localhost:9200 |
默认 ES 地址 |
HQ_ENABLE_SSL |
False | 启用 SSL |
HQ_CA_CERTS |
/path/to/your/ca.crt | CA 证书路径 |
HQ_VERIFY_CERTS |
True | 验证证书 |
HQ_DEBUG |
False | 调试模式 |
高级配置
SSL 证书配置
要启用 SSL 证书支持：
python -m application --enable-ssl --ca-certs /path/to/your/ca.crt
注意： 使用自签名证书时，需要将 verify_certs 设为 False。
数据库配置
Elasticsearch-HQ 使用 SQLite 存储集群连接信息等元数据，数据库文件位于 elastichq.db。如需重置，只需删除该文件，系统会在下次启动时自动重建。
外部配置文件
支持通过 settings.json 文件进行配置，系统会按以下顺序查找：
/etc/elastic-hq/settings.json~/settings.json- 当前工作目录下的
settings.json - 当前工作目录下的
elastichq/settings.json - 当前工作目录下的
config/settings.json
配置示例：
{
"SQLALCHEMY_DATABASE_URI": "sqlite:////SOME/PATH/TO/DB_NAME.db"
}
生产环境部署建议
在正式生产环境中，建议使用多线程服务器运行 Elasticsearch-HQ。推荐使用 gunicorn：
gunicorn -w 1 -b :5000 --worker-class eventlet application:application
重要提示： 要使 Metrics 部分的 WebSocket 正常工作，必须将 gunicorn 设置为 1 个 worker。
常见问题排查
连接问题
- 基础认证失败：确保使用
http://USERNAME:PASSWORD@DOMAIN:PORT格式 - X-Pack 许可证过期：检查并更新 X-Pack 许可证
- 网络不可达：确认 HQ 服务器可以访问 ES 集群
- 证书验证失败：自签名证书需要设置
verify_certs=False
X-Pack 集成
连接 X-Pack 保护的集群时，必须在 URL 中包含用户名和密码。请注意，这些凭据会以明文形式存储在 HQ 数据库中。
日志查看
- 普通安装：
/install/path/application.log - Docker 安装：
/src/application.log
SSL 证书问题
确保 CA 文件与 Elasticsearch 节点使用的证书由同一签发机构签发。可通过以下命令测试：
curl -u admin:password --ca-certs /path/to/ca.crt https://localhost:9200/_cluster/settings?pretty
升级指南
Elasticsearch-HQ 遵循语义化版本控制，只要主版本号不变，升级通常会很顺利。
升级步骤：
- 获取最新源码
- 升级数据库：
python manage.py db upgrade - 重启服务：
python application.py
系统会在页脚显示当前版本和最新版本信息，方便您判断是否需要升级。
总结
Elasticsearch-HQ 是一个功能全面、易于使用的 Elasticsearch 管理工具。通过本文介绍的安装和配置方法，您可以快速搭建起自己的监控平台，有效管理 Elasticsearch 集群。无论是开发环境还是生产环境，Elasticsearch-HQ 都能提供强大的集群监控和管理能力。
