HipChat 账户的 room 设置数量不符合 profile 要求 - 如何解决此 Elasticsearch 异常

适用版本： 6.8-8.11

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

在 Elasticsearch Watcher 的 HipChat 通知配置中，如果使用 integration 类型的 profile，则 room 设置只能配置单个值。如果在配置中为该 profile 指定了多个 room（例如写成 YAML 列表或逗号分隔的多值），Elasticsearch 在解析账户配置时会抛出如下异常：

SettingsException: invalid hipchat account [<account_name>]. [room] setting for [integration] account must only be set with a single value

该异常属于配置校验错误，会在 Watcher 加载或验证 HipChat 账户配置时触发，导致对应的 HipChat 通知账户无法正常工作，进而影响依赖该账户的 Watcher action 执行。

常见现象 #

• Elasticsearch 启动日志或 Watcher 配置加载阶段出现 SettingsException 报错。
• 使用 HipChat 通知的 Watcher 执行失败，action 状态显示为 failed。
• 在 GET _watcher/stats 或 Kibana Watcher UI 中可以看到相关账户配置校验失败的信息。
• 修改 HipChat 账户配置后热加载失败，提示 room 设置非法。

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

Elasticsearch Watcher 的 HipChat 通知支持多种 profile 类型，其中 integration profile 与 user profile 在 room 配置上的约束不同：

• integration profile：对应 HipChat 的 Integration API Token，一个 token 只能绑定到一个 room，因此 room 设置必须且只能指定一个值。
• user profile：对应 HipChat 的 User API Token，拥有更广泛的权限，可以向多个 room 发送消息，因此 room 可以指定多个值。

在源码中，账户配置解析阶段会进行如下校验：

if (rooms == null || rooms.isEmpty()) {
    throw new SettingsException("invalid hipchat account [" + name + "]. missing required [" + ROOM_SETTING + "] setting for [" +
        TYPE + "] account profile");
}
if (rooms.size() > 1) {
    throw new SettingsException("invalid hipchat account [" + name + "]. [" + ROOM_SETTING + "] setting for [" + TYPE + "] " +
        "account must only be set with a single value");
}
this.room = rooms.get(0);

常见触发原因包括：

• 错误地将 integration profile 的 room 配置写成了列表形式（如 - room1\n- room2），误以为可以一次通知多个房间。
• 从 user profile 迁移到 integration profile 时，遗漏了将多 room 配置缩减为单 room。
• 在复用配置模板时未根据 profile 类型调整 room 字段的约束。
• 通过 Elasticsearch API 动态更新账户配置时，传入了数组格式的多 room 值。

3. 如何排查这个错误 #

建议按以下步骤逐步定位问题：

1. 查看完整报错信息：从 Elasticsearch 日志中确认报错账户名称（account name）以及具体的 profile 类型。
2. 检查 HipChat 账户配置：使用 GET _cluster/settings?include_defaults=true 或查看 elasticsearch.yml 中 xpack.notification.hipchat 相关配置段，找到对应账户的 room 设置。
3. 确认 profile 类型：检查该账户是否配置了 profile: integration，若是，则 room 只能为单值。
4. 检查配置格式：确认 room 是否以列表形式配置（YAML 中 room: 下一行以 - 开头即为列表），或者是否以逗号分隔的字符串形式给了多个值。
5. 确认 HipChat Token 类型：如果 Token 是 Integration Token（以 https://hipchat.com/v2/room/<room_id>/notification 为终点），则天然只支持单 room。

4. 如何解决这个错误 #

方案一：将 room 缩减为单个值（推荐） #

如果当前确实使用的是 integration profile，直接修改配置，将 room 改为单个 room ID 或 room 名称：

修改前（错误配置）：

xpack.notification.hipchat:
  account:
    my_hipchat:
      profile: integration
      auth_token: "xxx"
      room:
        - "RoomA"
        - "RoomB"

修改后（正确配置）：

xpack.notification.hipchat:
  account:
    my_hipchat:
      profile: integration
      auth_token: "xxx"
      room: "RoomA"

修改完成后，通过以下方式使配置生效：

# 如果是 elasticsearch.yml 中的配置，需要重启节点
# 如果是集群动态配置，更新后自动生效
PUT _cluster/settings
{
  "persistent": {
    "xpack.notification.hipchat.account.my_hipchat.room": "RoomA"
  }
}

方案二：切换为 user profile（需要多 room 通知时） #

如果业务上确实需要向多个 room 发送通知，且当前使用的是 Integration Token，则需要申请 HipChat User API Token，并将 profile 改为 user：

xpack.notification.hipchat:
  account:
    my_hipchat:
      profile: user
      auth_token: "user_api_token_here"
      room:
        - "RoomA"
        - "RoomB"

注意： HipChat 已于 2018 年停止服务，Atlassian 已全面迁移至其他通知方案（如 Slack、Microsoft Teams 等）。上述配置仅适用于维护的老版本 Elasticsearch 集群或私有部署的 HipChat Server。新部署建议使用 Webhook 通知替代。

方案三：在 action 层分别配置多个账户 #

如果只能使用 integration profile（每个 token 对应一个 room），可以分别为每个 room 创建独立的 HipChat 账户，然后在 Watcher action 中分别引用：

{
  "actions": {
    "notify_room_a": {
      "hipchat": {
        "account": "hipchat_room_a",
        "message": "告警触发：{{ctx.payload.message}}"
      }
    },
    "notify_room_b": {
      "hipchat": {
        "account": "hipchat_room_b",
        "message": "告警触发：{{ctx.payload.message}}"
      }
    }
  }
}

5. 预防建议 #

• 按 profile 类型建立配置模板：为 integration 和 user 两种 profile 分别维护配置模板，并明确标注 room 字段的约束差异，避免混用。
• 在 CI/CD 中增加配置校验：在部署脚本中加入对 HipChat 配置的静态检查，当 profile: integration 时自动校验 room 是否为单值。
• 迁移至 Webhook 通知：HipChat 已停止服务，建议将现有 HipChat 通知迁移至 Slack、Teams 或自定义 Webhook，使用 webhook action 替代 hipchat action，从根本上避免此类问题。
• 使用 INFINI Console 统一管理通知渠道：通过 INFINI Console 集中管理告警通知配置，减少直接修改 Elasticsearch 配置文件带来的风险。

相关错误 #

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

附：日志上下文 #

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

if (rooms == null || rooms.isEmpty()) {
    throw new SettingsException("invalid hipchat account [" + name + "]. missing required [" + ROOM_SETTING + "] setting for [" +
        TYPE + "] account profile");
}
if (rooms.size() > 1) {
    throw new SettingsException("invalid hipchat account [" + name + "]. [" + ROOM_SETTING + "] setting for [" + TYPE + "] " +
        "account must only be set with a single value");
}
this.room = rooms.get(0);
defaults = new Defaults(settings);
}