ElasticHQ 安装与配置完全指南
概述
ElasticHQ 是一个功能强大的 Elasticsearch 集群管理工具，提供直观的 Web 界面来监控和管理 Elasticsearch 集群。本文将详细介绍 ElasticHQ 的多种安装方式、配置选项以及常见问题的解决方案。
安装方式
Docker 快速部署（推荐）
对于大多数用户来说，使用 Docker 是最简单快捷的部署方式：
docker run -p 5000:5000 elastichq/elasticsearch-hq
部署完成后，通过浏览器访问 http://localhost:5000 即可使用。
Docker 环境变量配置
可以通过 -e 参数传递环境变量来配置 ElasticHQ：
docker run -p 5000:5000 elastichq/elasticsearch-hq -e HQ_DEFAULT_URL='http://your-es-cluster:9200'
版本说明：
latest标签：最新稳定版develop标签：开发版（可能不稳定）
源码安装
系统要求
- Python 3.4 或更高版本
- Elasticsearch 2.x、5.x、6.x 或 7.x 版本
安装步骤
- 获取源码（通过下载或克隆）
- 安装依赖：
pip install -r requirements.txt - 启动服务：
python3 application.py - 访问：
http://localhost:5000
替代启动方式：
python manage.py runserver
版本分支说明
master：稳定版develop：开发版（不稳定）#.#.#RC-#：预发布候选版本
初始配置
首次访问 ElasticHQ 时，需要输入 Elasticsearch 集群的连接信息：
- 基本格式：
http://DOMAIN:PORT - 支持 HTTPS
- 基本认证格式：
http://USERNAME:PASSWORD@DOMAIN:PORT
详细配置选项
命令行参数
启动时可用的命令行参数：
| 参数 | 默认值 | 描述 |
|---|---|---|
--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
数据库配置
ElasticHQ 使用 SQLite 存储集群连接信息等元数据，数据库文件位于 elastichq.db。
重置数据库：删除该文件后重启服务即可。
外部配置文件
支持通过 settings.json 文件配置，ElasticHQ 会从以下位置查找该文件：
/etc/elastic-hq/settings.json~/settings.json- 当前工作目录下的
settings.json - 当前工作目录下的
elastichq/settings.json - 当前工作目录下的
config/settings.json
配置示例：
{
"SQLALCHEMY_DATABASE_URI": "sqlite:////path/to/db_name.db"
}
生产环境部署建议
不建议直接使用 Flask 开发服务器运行在生产环境，推荐使用 Gunicorn：
gunicorn -w 1 -b :5000 --worker-class eventlet application:application
注意：要使 Metrics 部分的 WebSocket 正常工作，必须设置 worker 数量为 1。
常见问题排查
连接问题
- 认证问题：确保使用
http://USERNAME:PASSWORD@DOMAIN:PORT格式 - X-Pack 许可证过期：检查并更新许可证
- 网络连通性：确认 HQ 服务器可以访问 ES 集群
- 证书验证失败：自签名证书需设置
verify_certs=False
X-Pack 集成
必须通过 URL 传递用户名和密码，这些凭证会以明文形式存储在数据库中。
日志查看
- 标准安装：
/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
Docker 容器数据持久化
使用 volume 挂载数据库目录以保持数据持久化。
升级指南
ElasticHQ 遵循语义化版本控制，只要主版本号不变，升级通常不会引入破坏性变更。
升级步骤：
- 获取最新代码
- 升级数据库：
python manage.py db upgrade - 重启服务
日志配置
默认日志输出到控制台和文件（application.log）。高级用户可通过修改 elastichq/config/logger.json 自定义日志配置。
许可证
ElasticHQ 使用 Apache License 2.0 许可证。
