企业官网建设流程全解析

Apache DolphinScheduler 阿里云语音告警（AliyunVoice）插件配置与实现解析

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler

本指南以 Apache DolphinScheduler 的阿里云语音告警插件（AliyunVoice）为核心，讲解如何通过告警实例管理创建语音告警实例、填写被叫号码/呼叫显示号码/语音模板及 AccessKey 等参数，并结合仓库源码剖析插件从参数解析、阿里云语音服务调用到结果回传的完整链路。读者读完可独立完成语音告警的配置、测试与问题排查，并理解其底层实现原理。

一、语音告警是什么：场景与定位

在数据调度平台中，告警的时效性至关重要。相比邮件、短信等文本通道，语音通知能够在告警发生时直接拨打电话，将关键故障信息以语音形式播报给值班人员，适用于：

• 工作流（Workflow）失败、任务（Task）失败等高优先级告警；
• 深夜或非工作时间、值班人员无法持续盯屏的场景；
• 需要"必达"效果、要求第一时间人工介入的异常。

Apache DolphinScheduler 的告警体系采用插件化架构，语音告警作为AlertChannelFactory的一种实现，注册名称为AliyunVoice。用户无需修改代码，只需在告警实例管理中新建告警实例并选择语音插件，即可把语音通道挂接到工作流的失败策略上。

说明：本插件依赖阿里云语音服务（语音通知文件类型）能力，使用前需要在阿里云侧开通相应服务并准备好语音模板与 API 密钥。插件源码位于 dolphinscheduler-alert-aliyunVoice，对应文档为 docs/docs/zh/guide/alert/aliyun-voice.md。

二、创建语音告警实例

进入 DolphinScheduler 的安全中心 → 告警实例管理，点击创建告警实例：

1. 选择告警插件类型为语音（插件内部名称为AliyunVoice）；
2. 填写下表所述的参数；
3. 保存后即可在告警组中引用该实例。

如上图所示，语音告警实例需要配置"被叫电话号码、呼叫显示号码、语音模板、AccessKey ID、AccessKey Secret"等字段。

三、参数配置详解

语音告警插件的参数由 VoiceAlertChannelFactory#params() 定义，共 6 个输入项，字段名与展示名定义在 VoiceAlertConstants.java 中，占位提示语则来自 AlertInputTips.java。

各参数的详细说明如下：

• 被叫电话号码：必填项，对应AlertInputTips.CALLED_NUMBER（"请输入被叫电话号码"）。它是SingleCallByTts请求中的CalledNumber，必须是可接听的真实手机号或固话。
• 呼叫显示号码：选填项，界面提示"不填则使用默认号码"。从源码看，该值在 VoiceAlertChannel#buildVoiceParam 中同时被设置到VoiceParam.outId，作为调用方自定义的透传字段（回调 ID）。
• 语音模板：填写阿里云语音服务中创建的"语音通知文件"模板编码（形如TTS_2450XXXXX）。VoiceSenderTest 中即以TTS_2450XXXXX作为示例值。
• 访问域名：对应阿里云语音服务dyvmsapi的 endpoint 地址。源码中通过config.endpoint = conn.getAddress()设置（见下文发送链路）。
• accessKeyId / accessKeySecret：阿里云 OpenAPI 调用的鉴权凭据，应妥善保管，建议使用阿里云 RAM 子账号并仅授予语音服务调用权限。

注：前端国际化文案与上述参数一一对应，见 dolphinscheduler-ui/src/locales/zh_CN/security.ts 与 en_US/security.ts，其中"访问域名"在界面显示为Address。

四、发送流程与源码级实现原理

语音告警从触发到拨号，经历"告警事件 → 参数装配 → 阿里云 API 调用 → 结果回传"四个环节，核心实现为四个类：

• VoiceAlertChannel.java：告警通道入口；
• VoiceParam.java：参数封装对象；
• VoiceSender.java：真正执行发送；
• VoiceAlertChannelFactory.java：插件注册与参数定义。

4.1 插件注册与参数装配

VoiceAlertChannelFactory通过@AutoService(AlertChannelFactory.class)注解完成 SPI 自动注册，name()返回插件名称AliyunVoice，params()返回 6 个输入参数，create()实例化VoiceAlertChannel。对应测试 VoiceAlertChannelFactoryTest 验证了参数数量为 6、通道实例创建非空。

告警触发后，告警服务会以Map<String, String>形式把实例配置传入VoiceAlertChannel.process(AlertInfo info)：

1. 若info.getAlertParams()为 null，直接返回AlertResult(false, "aliyun-voice params is null")；
2. 否则调用buildVoiceParam(paramsMap)，按常量 key 取出 6 个字段并装配成VoiceParam（含Connection内部类，承载 address、accessKeyId、accessKeySecret）；
3. 交由new VoiceSender(voiceParam).send()执行发送。

4.2 阿里云语音 API 调用（VoiceSender）

VoiceSender.send()是发送核心，基于阿里云官方 Java SDK（com.aliyun.dyvmsapi20170525）：

Client client = createClient(voiceParam.getConnection()); SingleCallByTtsRequest singleCallByTtsRequest = new SingleCallByTtsRequest() .setCalledNumber(voiceParam.getCalledNumber()) .setTtsCode(voiceParam.getTtsCode()) .setOutId(voiceParam.getOutId()); RuntimeOptions runtime = new RuntimeOptions(); SingleCallByTtsResponse response = client.singleCallByTtsWithOptions(singleCallByTtsRequest, runtime);

• createClient使用 AccessKeyId / AccessKeySecret 构建鉴权配置，并将实例中填写的address设置为config.endpoint；
• 请求类型为SingleCallByTts（向指定号码发送语音通知文件类型的语音通知），OutId为调用方透传的回调 ID；
• 响应体code为ok（忽略大小写）时判定发送成功，并将callId作为成功消息返回；否则返回阿里云侧的message作为失败原因；
• 任何异常都会被捕获并记录到日志（log.error("send aliyun vocie error.", e)），同时把异常信息写入AlertResult.message。

4.3 测试验证

仓库提供了两类测试：

• VoiceSenderTest：使用占位手机号与假 AccessKey 构造VoiceParam并调用send()，断言发送结果失败（isSuccess() == false），验证在无效凭证下不会抛出未捕获异常；
• VoiceAlertChannelFactoryTest：验证插件参数数量与通道工厂创建行为。

五、在告警组中使用语音实例

创建好语音告警实例后，还需要在告警组管理中把该实例加入告警组，然后在工作流定义或任务定义中把失败/成功策略指向该告警组。当工作流状态满足触发条件时，告警服务会读取实例配置并调用语音插件，向被叫号码发起语音通知。

语音通道的触发逻辑与其他告警通道完全一致，均复用告警服务统一的发送调度，无需额外配置。若需要验证，可使用告警实例的"测试"功能（如有）或直接触发一次失败工作流观察告警日志。

六、常见问题与排查建议

排查时可重点查看alert-server的运行日志，VoiceSender会把异常信息与阿里云返回 message 一并记录。

七、小结

本文以阿里云语音告警插件为主线，完整覆盖了告警实例创建、6 个参数的语义与来源、发送链路的源码实现以及测试验证方式。通过 VoiceAlertChannelFactory、VoiceAlertChannel、VoiceSender 等源码可以看到：插件采用标准 SPI 机制注册，参数装配、鉴权配置与请求构造分层清晰，告警结果（callId或错误 message）会完整回传至告警服务，方便运维人员结合日志与阿里云侧记录定位问题。按本文步骤完成配置后，即可将工作流失败信息以电话语音的方式第一时间触达值班人员。

【免费下载链接】dolphinschedulerApache DolphinScheduler is the modern data orchestration platform. Agile to create high performance workflow with low-code项目地址: https://gitcode.com/GitHub_Trending/dol/dolphinscheduler