PagerDuty 账户缺少必需的 service key - 如何解决此 Elasticsearch 异常

适用版本： 6.8-8.9

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

invalid pagerduty account [name]. missing required [service_key] setting 是 Elasticsearch Watcher 在初始化 PagerDuty 告警动作时抛出的配置异常。当 Elasticsearch 尝试为指定的 PagerDuty 账户加载 service_key（或 api_key），但在普通配置和安全配置中均未找到有效值时，就会触发此异常。

常见现象 #

• Watcher 中配置的 PagerDuty 告警动作无法执行，相关 watch 处于 failed 状态。
• Elasticsearch 日志中出现 SettingsException 并携带上述错误信息，同时注明具体失败的账户名。
• 使用 _execute API 手动触发 watch 时，直接返回 400 或 500 错误，提示 PagerDuty 账户配置无效。
• Kibana 的 Watcher UI 中对应动作显示为异常状态，无法成功发送告警到 PagerDuty。

典型报错与异常栈 #

SettingsException: invalid pagerduty account [my_pagerduty]. missing required [service_key] setting
    at org.elasticsearch.xpack.watcher.notification.pagerduty.PagerDutyAccounts.<init>(PagerDutyAccounts.java:xx)
    at org.elasticsearch.xpack.watcher.notification.pagerduty.PagerDutyService.doStart(PagerDutyService.java:xx)

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

Elasticsearch Watcher 的 PagerDuty 通知功能依赖一个有效的服务密钥（service_key 或 api_key）来向 PagerDuty 平台发送告警事件。Elasticsearch 在启动时和每次加载 PagerDuty 账户配置时，会按以下优先级查找该密钥：

1. 先读取 elasticsearch.yml 中 xpack.notification.pagerduty.account.*.service_key 普通配置。
2. 若普通配置中未找到，则尝试从 安全设置（Secure Settings） 中读取 xpack.notification.pagerduty.account.*.secure_service_api_key。
3. 若两个位置均未配置或值为空，则直接抛出 SettingsException。

核心源码逻辑如下：

String serviceKey = accountSettings.get(SERVICE_KEY_SETTING,
    serviceSettings.get(SERVICE_KEY_SETTING, null));
if (serviceKey == null) {
    SecureString secureString = SECURE_SERVICE_API_KEY_SETTING.get(accountSettings);
    if (secureString == null || secureString.length() < 1) {
        throw new SettingsException("invalid pagerduty account [" + name +
            "]. missing required [" + SERVICE_KEY_SETTING + "] setting");
    }
    serviceKey = secureString.toString();
}

常见原因包括：

• elasticsearch.yml 中漏配了 service_key，或者配置项名称拼写错误。
• 使用了安全设置方式存储密钥，但忘记通过 elasticsearch-keystore 工具添加对应条目，或添加后未重启节点使配置生效。
• 从旧版本迁移或复制配置文件时，遗漏了 PagerDuty 相关配置段。
• PagerDuty 账户名在 watch 中引用与实际配置不一致，导致加载了错误的账户配置。

3. 如何排查这个异常 #

建议按以下顺序排查：

1. 确认报错中的账户名：从异常信息中提取 [name] 部分，确认 Watcher 中引用的 PagerDuty 账户名。
2. 检查普通配置：查看 elasticsearch.yml 中是否存在 xpack.notification.pagerduty.account.<name>.service_key 配置项，且值非空。
3. 检查安全设置：若未使用普通配置，运行 bin/elasticsearch-keystore list，确认 xpack.notification.pagerduty.account.<name>.secure_service_api_key 是否存在。
4. 验证密钥有效性：确认配置的 service key 与 PagerDuty 控制台中生成的 Integration Key 一致，且未被禁用或删除。
5. 确认节点已重启：若使用安全设置方式，修改 keystore 后必须重启 Elasticsearch 节点才能生效。

排查时需要注意的问题 #

• PagerDuty 的 service_key（旧版 Integration Key）与 routing_key（新版 Events API v2）是不同概念，确认 Watcher 版本与 PagerDuty 集成类型匹配。
• 若集群有多个节点，确保每个节点的配置一致，否则可能出现部分节点可用、部分节点报错的情况。
• 安全设置存储在 keystore 文件中，不会出现在 elasticsearch.yml 里，排查时不能仅看配置文件。

4. 如何解决这个错误 #

方案一：使用普通配置（适用于测试环境） #

在 elasticsearch.yml 中添加 service key 配置，然后重启节点：

xpack.notification.pagerduty.account.my_pagerduty:
  service_key: "your_pagerduty_integration_key_here"

方案二：使用安全设置（推荐生产环境） #

通过 elasticsearch-keystore 工具将密钥以安全方式存储，避免明文出现在配置文件中：

# 添加安全密钥
bin/elasticsearch-keystore add xpack.notification.pagerduty.account.my_pagerduty.secure_service_api_key

# 查看已配置的 keystore 条目
bin/elasticsearch-keystore list

# 重启 Elasticsearch 使配置生效

方案三：使用 Events API v2（新版 PagerDuty） #

如果使用 PagerDuty Events API v2，需要配置 routing_key 而非 service_key：

xpack.notification.pagerduty.account.my_pagerduty:
  routing_key: "your_pagerduty_routing_key_here"

验证修复 #

修复后，可通过以下方式验证 PagerDuty 账户是否加载成功：

# 查看 Watcher 统计信息，确认 PagerDuty 账户已初始化
GET _watcher/stats

# 手动执行一个包含 PagerDuty 动作的 watch 进行测试
POST _watcher/watch/_execute
{
  "watch": {
    "trigger": { "schedule": { "interval": "1m" } },
    "actions": {
      "pagerduty_action": {
        "pagerduty": {
          "account": "my_pagerduty",
          "description": "Test PagerDuty notification"
        }
      }
    }
  }
}

5. 预防建议 #

• 统一配置管理：将 PagerDuty 账户配置纳入配置管理工具（如 Ansible、Terraform）统一管理，避免手动修改导致遗漏。
• 环境一致性检查：在环境迁移或集群扩容时，使用脚本自动校验关键告警集成账户的密钥是否存在且有效。
• 优先使用安全设置：生产环境中优先使用 elasticsearch-keystore 存储敏感密钥，避免密钥泄露风险。
• 建立告警自检：在 Watcher 中添加定期自检 watch，验证 PagerDuty 动作能否正常执行，及时发现配置失效问题。
• 文档化集成信息：记录每个 PagerDuty 账户对应的 PagerDuty Service、Integration Key 和负责人，便于后续维护。

相关错误 #

• watch-attachment-http-error-status-host-port-how-to-solve-this-elasticsearch-exception
• watch-attachment-http-empty-response-body-host-port-how-to-solve-this-elasticsearch-exception
• connection-exception：连接异常

附：日志上下文 #

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

private static String getServiceKey(String name, Settings accountSettings, Settings serviceSettings) {
    String serviceKey = accountSettings.get(SERVICE_KEY_SETTING,
        serviceSettings.get(SERVICE_KEY_SETTING, null));
    if (serviceKey == null) {
        SecureString secureString = SECURE_SERVICE_API_KEY_SETTING.get(accountSettings);
        if (secureString == null || secureString.length() < 1) {
            throw new SettingsException("invalid pagerduty account [" + name + "]. missing required ["
                + SERVICE_KEY_SETTING + "] setting");
        }
        serviceKey = secureString.toString();
    }
    return serviceKey;
}