Whaleal SMS 云平台
这一章介绍 Whaleal SMS —— 一个托管式多渠道短信中转平台：把你在各家 CPaaS 的账号聚合成一套统一 API、一个统一后台。
- 控制台：sms.whaleal.com
- 开放 API：
https://smsapi.whaleal.com/open/v1- 线上 API 参考：sms.whaleal.com/developers/api
这一章讲什么
如果只是「调一家厂商的接口把短信发出去」，Quick SMS SDK 就够了 —— Spring Boot 快速开始 十分钟能跑通。
但业务做起来之后，事情通常不会停在一家厂商、一套密钥上：
- 验证码走质量更好的国际通道，营销通知走成本更优的国内通道 —— 渠道分了场景，代码里就多出一套分支
- 为了灾备冗余同时维护两家供应商 —— 换通道、加通道要改代码重新发版
- 不同业务线历史上各自采购通道 —— 每套系统对接一套 API、维护一套 SDK
- 出了故障要挨个登录各家后台看日志 —— 排障要在多个控制台之间来回核对
- 密钥散落在各服务的配置文件里 —— 轮换一次密钥，改动面铺满整个仓库
Whaleal SMS 就是为这些「第二层问题」准备的。 它把底层 CPaaS 账号收进一个平台，向上暴露一套 API、一个后台、一份日志、一处分发规则。
和 Quick SMS 的关系
两个产品是同一套引擎的两种交付形态，不是两套并行实现：
| Quick SMS（SDK） | Whaleal SMS（云平台） | |
|---|---|---|
| 形态 | 开源 SDK，嵌进你的进程 | 托管 SaaS，跑在我们的服务器上 |
| 你要提供 | 各家厂商的密钥 | 各家厂商的密钥（BYOL，仍然是你自己的账号） |
| 你要维护 | 版本升级、密钥配置、回调服务、日志 | 只调一个 API |
| 聚合与路由 | addChannel + failover 策略，写在你的代码里 | 控制台点选绑定，权重/优先级实时可改，不用发版 |
| 观测 | 自己接 SmsMetrics | 控制台统一日志、报表、路由链可视化 |
| 适合 | 想完全自主可控、单团队单渠道 | 多渠道、多业务线、想少写运维代码 |
平台内部的多厂商发信能力由 Quick SMS 提供 —— 你在 SDK 里能用到的适配器（国际 Twilio / Vonage / Infobip / MessageBird / Plivo / AWS SNS，国内阿里 / 腾讯 / 华为 / 云片 / 创蓝 / 容联 / 天翼云 / 火山引擎 等），在平台上同样可用，且新增一家适配器只需要在 SDK 里加实现，平台侧自动继承。
为什么值得多引一层
前提说清楚：平台不卖短信、不经手资费。短信费用永远发生在你自己的 CPaaS 账户里，由供应商直接向你计费。你为平台付的是渠道管理能力的订阅费，不是短信条数的抽成。
在这个前提下，多引一层换来的是四件事：
1. 聚合路由：N 家的吞吐，一家的接口
绑到同一个 API Key 上的多条渠道，平台自动做分发与容灾：
| 绑定方式 | 平台行为 |
|---|---|
| 各渠道权重相等 | 顺序主备 failover —— 按 priority 从小到大，健康时只用首选，失败才切换 |
| 各渠道权重不全相等 | 平滑加权轮询 —— 健康时按权重比分发，失败时剩余渠道按 priority 顺序兜底 |
控制台里签发密钥时就能看到路由链预览（按渠道 priority 排序），权重和 priority 随时可调。这意味着：加一条渠道、把某条降为备胎、临时把某家摘出去，都是控制台操作，不需要改代码、不需要发版。
2. 统一观测：一处看到全部渠道
多供应商最贵的成本是排障。平台把各家的回执归一成统一状态，集中在一份日志里：
- 全渠道发送日志，可按渠道、状态、号码、时间窗筛选
- 渠道质量对比（各家的提交/送达表现摆在一起看）
- 送达状态归一 —— 你不用再记 Twilio 的
delivered和 Vonage 的expired分别代表什么
3. 密钥收口：一次轮换，一处改
厂商凭据在平台侧 AES 加密存储、永不回显完整密钥，发送时按请求解密后传入 SDK。轮换密钥是在控制台改一次，而不是翻遍所有服务的配置文件。
4. 接入成本：任何语言都能接
平台开放 API 是纯 HTTP + JSON，没有 SDK 绑定。Java、Node.js、Python、Go、PHP 都能用同一套接口 —— 具体见 接入方式总览。
典型接入场景
下面三个场景是平台最常被用到的形态。留意每个场景里「配置就能改」和「要改代码」的分界线 —— 那正是引入平台的价值所在。
场景一：验证码与营销消息分流
┌─ API Key「验证码」 ─► Twilio（国际，质量优先）
你的业务系统 ──► │
└─ API Key「营销」 ─► 本地区聚合商（成本优先）
做法：不为「场景」写代码分支，而是签发两个 API Key，各自绑定不同的渠道。业务侧只换密钥，路由规则在控制台维护。
什么时候改配置就够：临时把营销降级走备选通道、把某家摘出去观察、调整两家之间的分发比例 —— 都在密钥详情页改，不用发版。
场景二：单供应商灾备
API Key ─► 【priority=1, weight=1】Twilio ──失败──► 【priority=2】Vonage
（健康时只走这家） （仅主渠道失败时接管）
做法：两条渠道权重都填 1，priority 拉开。平台进入「顺序主备 failover」——健康时只用首选，失败才切备胎，不会两边各发一半。
要点：这是避免「故障期间一半用户收不到」最省事的做法。切换过程你在控制台的日志里能直接看到，不需要自己去猜是哪家出的问题。
场景三：多业务线统一治理
订单系统 ──┐
会员系统 ──┼──► Whaleal SMS ──► 各 CPaaS 账号（同一个集团的采购）
客服系统 ──┘ ▲
└─ 一套日志 / 一份报表 / 一个限速池
做法：各系统共用平台，但按业务签发各自的 API Key，绑定各自的渠道子集。好处有三：
- 排障不用再问「这条短信是谁发的」—— 日志里有渠道、有状态、有 Key 归属
- 供应商凭据只在一处维护，轮换一次到位
- 限速统一在平台侧生效，不会某个系统把整个账号的配额打满
想直接上手？接入方式总览 是五步跑通第一条短信的最短路径。
能力边界（请先读这一段）
这些不是免责声明，是选型前必须知道的边界，也决定了你的架构该把什么放在平台侧、什么留在自己系统里：
| 边界 | 说明 |
|---|---|
| BYOL | 渠道凭据是你自己 CPaaS 账户的。平台不提供、不出售短信通道 |
| 不经手资费 | 短信费用由底层供应商直接向你计费，平台不加价、不抽成、不代收 |
| 不承诺送达 | 平台负责把消息提交给供应商并归一回执，投递结果由底层通道决定 |
| 不存正文 | 出于合规，短信正文不落库。你需要自行留存业务侧发送记录；平台只回传可对账的元数据（编码口径与计费条数） |
| 不做请求去重 | 平台不提供幂等键。超时后重发就是真发第二条 —— 详见 开放 API |
| 模板/签名审核不在平台 | 需要报备的模板与签名，由你在各 CPaaS 后台自行完成 |
平台协议里的原话是：「平台为 BYOL 多供应商统一管理平台：不售卖短信、不经手资费、不承诺送达、不改变底层链路。」做对外宣传和技术方案时，请沿用这个口径。
我该用哪一个
| 你的处境 | 建议 |
|---|---|
| 只用一家厂商，业务量稳定，团队有能力维护 | 直接用 Quick SMS SDK，少一层依赖 |
| 这家厂商要换、或者要加一家做灾备 | 用平台 —— 加渠道是控制台操作，不是发版 |
| 多条业务线各买了通道，想统一起来 | 用平台 —— 一套 API 对接全部渠道 |
| 需要多语言系统共用短信能力（Java 之外还有 PHP/Go） | 用平台 —— HTTP 接口无语言绑定 |
| 需要极致的自主可控、数据完全不出自己的机房 | 用 SDK 自建 —— 权重 / priority 的分发与容灾配置方式可参考渠道与路由配置 |
| 想先看看接入要花多少工夫 | 直接读 接入方式总览，再看套餐与配额 |
本章导航
- 接入方式总览 —— 三条路径怎么选，五步跑通第一条短信
- 控制台使用指南 —— 侧边栏每个页面解决什么问题
- 开放 API 参考 —— 鉴权、三个端点、错误码、重发红线
- 状态回调接入 —— 两条回调链路的区别，含 Spring Boot 接收示例
- 套餐与配额 —— 四档套餐、QPS 分层、用量对账
- 能力路线图 —— 已上线能力与规划中的能力
- 常见问题 —— 接入排错与对外口径