HipChat 账户缺少必需的认证令牌设置 - 如何解决此 Elasticsearch 异常

适用版本： 6.8-8.11

1. 错误异常的基本描述 #

hipchat account [name] missing required [auth_token] setting 是 Elasticsearch Watcher 中 HipChat 通知动作配置不完整时抛出的异常。当 Watcher 尝试发送 HipChat 消息，但对应的 HipChat 账户未在设置中提供认证令牌（auth_token）时，就会触发此错误。

HipChat 是 Atlassian 推出的团队即时通讯工具，Elasticsearch Watcher 支持通过 HipChat 发送告警通知。该通知方式需要在 Elasticsearch 配置中预先定义 HipChat 账户，并为其配置有效的 API 认证令牌。当配置缺失或令牌无效时，Watcher 执行到对应动作便会失败，导致告警无法正常发送。

常见现象 #

• Watcher 执行日志中出现 SettingsException: hipchat account [xxx] missing required [auth_token] setting 异常。
• 配置的 HipChat 告警动作执行失败，告警消息无法发送到 HipChat 房间。
• Elasticsearch 日志中可能出现 Watcher 执行失败的记录，提示对应账户名找不到有效的 auth_token 配置。
• 如果多个 Watcher 共用同一个未正确配置的 HipChat 账户，所有相关告警都会受影响。

典型报错与异常栈 #

异常信息通常类似下面这样：

SettingsException: hipchat account [my_hipchat] missing required [auth_token] setting
Caused by: java.lang.IllegalArgumentException
at org.elasticsearch.xpack.watcher.notification.hipchat.HipChatAccount.<init>(HipChatAccount.java)

2. 为什么会发生这个错误 #

Elasticsearch 在初始化 HipChat 账户时，会按以下顺序查找认证令牌：

1. 先从普通设置（elasticsearch.yml 中的 xpack.notification.hipchat.account.<name>.auth_token）读取。
2. 如果普通设置为空，再从安全设置（elasticsearch.keystore 中的 xpack.notification.hipchat.account.<name>.auth_token）读取。
3. 如果两个位置都没有有效值，则抛出 SettingsException。

关键源码逻辑如下：

private static String getAuthToken(String name, Settings settings) {
    String authToken = settings.get(AUTH_TOKEN_SETTING);
    if (authToken == null || authToken.length() == 0) {
        SecureString secureString = SECURE_AUTH_TOKEN_SETTING.get(settings);
        if (secureString == null || secureString.length() < 1) {
            throw new SettingsException(
                "hipchat account [" + name + "] missing required [" + AUTH_TOKEN_SETTING + "] setting");
        }
        authToken = secureString.toString();
    }
    return authToken;
}

常见原因通常包括：

• HipChat 账户配置中完全省略了 auth_token 设置，既不在 elasticsearch.yml 也不在 keystore 中。
• auth_token 只配置在 elasticsearch.yml 中但值为空字符串，或者被注释掉。
• 使用 keystore 存储令牌时，没有正确执行 bin/elasticsearch-keystore add 命令，或者 keystore 文件权限不正确导致无法读取。
• 账户名称拼写不一致：Watcher 中引用的账户名与配置中定义的账户名不完全匹配。
• 集群滚动升级或配置刷新后，keystore 文件没有同步到所有节点，导致部分节点读到空值。

3. 如何排查这个错误 #

建议按以下步骤逐步确认问题根因：

1. 确认报错信息中的账户名称（方括号中的名字），例如 hipchat account [my_hipchat]，后续所有检查都围绕该名称进行。
2. 检查 elasticsearch.yml 中是否存在对应配置：

   grep -A5 "xpack.notification.hipchat.account" config/elasticsearch.yml
   

3. 检查 keystore 中是否存在对应安全设置：

   bin/elasticsearch-keystore list | grep hipchat
   

4. 如果 keystore 中存在对应条目，确认集群每个节点都能正常读取 keystore 文件，且文件权限正确（通常应为 640，属主为运行 Elasticsearch 的用户）。
5. 检查 Watcher 定义中引用的账户名是否与配置中的账户名完全一致，注意大小写和特殊字符。

排查时需要注意的问题 #

• 修改 elasticsearch.yml 后需要重启节点才能生效；而 keystore 的变更可以通过 API 动态重载（_nodes/reload_secure_settings），但部分版本仍需重启。
• 如果集群有多个节点，务必确认 keystore 文件在所有节点上一致，否则会出现"部分节点正常、部分节点报错"的疑难问题。
• HipChat 服务本身已于 2018 年停止运营（Atlassian 官方已关闭 HipChat），如果使用此功能，通常是在私有化部署或迁移场景下，需要确认服务端是否仍然可达。

4. 如何解决这个错误 #

方案一：在 elasticsearch.yml 中配置 auth_token（不推荐用于生产） #

编辑 config/elasticsearch.yml，添加以下配置：

xpack.notification.hipchat:
  account:
    my_hipchat:
      auth_token: "你的HipChat_API_Token"
      host: "hipchat.example.com"
      port: 443
      use_ssl: true

修改完成后重启 Elasticsearch 节点使配置生效。

方案二：在 keystore 中配置 auth_token（推荐） #

使用 keystore 存储敏感令牌，避免明文出现在配置文件中：

# 添加 auth_token 到 keystore
bin/elasticsearch-keystore add xpack.notification.hipchat.account.my_hipchat.auth_token

# 重载安全设置（无需重启，Elasticsearch 6.x+ 支持）
curl -X POST "localhost:9200/_nodes/reload_secure_settings"

如果集群有多个节点，需要在每个节点上执行上述操作，或使用配置管理工具统一分发 keystore 文件。

方案三：确认账户名称一致 #

如果 Watcher 中使用的账户名与配置不一致，需要统一名称。例如 Watcher 中引用的是 hipchat_prod，则配置中应以相同名称定义：

xpack.notification.hipchat:
  account:
    hipchat_prod:
      auth_token: "xxx"

后续注意事项与推荐建议 #

• 由于 HipChat 官方服务已停止运营，建议评估将告警通知迁移到 Slack、Webhook 或邮件等替代方案。
• 如果仍在使用 HipChat，建议将 auth_token 统一放入 keystore，避免敏感信息泄露到配置文件和版本控制系统中。
• 对 Watcher 配置做变更前，在测试环境先验证 HipChat 动作可以正常发送消息，再同步到生产环境。

借助 INFINI 产品提升排障效率 #

• INFINI Console 适合查看集群健康度、Watcher 执行状态、索引状态和错误趋势，帮助快速判断告警失败是配置问题还是服务端问题。
• INFINI Gateway 适合部署在 Elasticsearch 前面做请求观测、限流和流量治理，可以在 Watcher 触发外部通知时提供额外的可观测性支持。
• 建议将 Watcher 执行失败日志、通知动作错误和集群变更记录统一接入监控面板，缩短从"告警未送达"到"定位根因"的时间。

5. 小结 #

hipchat account [name] missing required [auth_token] setting 的本质原因是 HipChat 通知账户缺少认证令牌配置。通过检查 elasticsearch.yml 和 keystore 两个配置位置，可以快速定位是配置缺失、名称不一致还是 keystore 未同步的问题。修复时优先使用 keystore 存储令牌，同时注意 HipChat 官方服务已停止运营，建议尽早规划迁移到替代通知方案。

相关错误 #

• missing-profile-setting-for-hipchat-account-name-how-to-solve-this-elasticsearch-exception
• invalid-hipchat-account-name-missing-required-room-setting-setting-for-how-to-solve-this-elasticsearch-exception
• invalid-hipchat-account-name-room-setting-setting-for-type-how-to-solve-this-elasticsearch-exception

附：日志上下文 #

下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：

private static String getAuthToken(String name, Settings settings) {
    String authToken = settings.get(AUTH_TOKEN_SETTING);
    if (authToken == null || authToken.length() == 0) {
        SecureString secureString = SECURE_AUTH_TOKEN_SETTING.get(settings);
        if (secureString == null || secureString.length() < 1) {
            throw new SettingsException("hipchat account [" + name + "] missing required [" + AUTH_TOKEN_SETTING + "] setting");
        }
        authToken = secureString.toString();
    }
    return authToken;
}