android-sms-gateway 版本演进与核心技术全景:从 SMS 网关到端到端加密的 Android 实现
android-sms-gateway 版本演进与核心技术全景:从 SMS 网关到端到端加密的 Android 实现
本指南以 CHANGELOG.md 为线索,系统梳理 android-sms-gateway 自 v1.0.0 至 v1.77.2 的能力演进,并结合仓库源码深入剖析消息发送、状态机、Webhook、端到端加密、云网关收件箱与 JWT 认证等核心模块的实现原理。读完本文,你将掌握该 SMS 网关项目的功能全貌、各版本关键变更背后的设计动机,以及如何在 README.md 与 docs/MMS.md 之外,直接通过源码定位与验证每一项关键能力。
一、项目定位与文档规范
android-sms-gateway 是一款将 Android 手机变为 SMS 网关的应用:既能在设备本地启动 HTTP 服务(Local Server),也能连接云端服务器(Cloud Server),通过 API 收发短信、数据短信(Data SMS)与彩信(MMS),并通过 Webhook 推送消息事件。它支持 Android 5.0 及以上,内置端到端加密、多 SIM、消息调度、发送限速等工作能力(详见 README.md)。
作为项目维护的核心元数据之一,CHANGELOG.md 遵循两条业界规范:
- Keep a Changelog 格式:每个版本条目按
Added(新增)/Changed(变更)/Fixed(修复)/Documentation(文档)/Maintenance(维护)/Testing(测试)分类组织; - Semantic Versioning(语义化版本):版本号采用
主.次.修订三段式,文末还维护了从 v1.0.0 到 v1.77.2 的完整比较链接表,方便追溯任意相邻版本的 diff。
从时间线上看,项目自 2022-11-08 发布 v1.0.0 起持续迭代至 2026-10-05 的 v1.77.2,跨度近四年,是观察一个 Android + Ktor + Room 技术栈项目如何逐步扩展边界(短信 → 数据短信 → MMS → 云同步 → 加密 → 批量事件)的绝佳样本。
二、版本里程碑总览
下表按时间顺序汇总主要里程碑版本,便于快速定位各阶段能力重心:
| 版本 | 日期 | 里程碑内容 |
|---|---|---|
| v1.0.0 | 2022-11-08 | 初始版本:短信发送、事件接收、授权、开机自启、本地/公网 IP 信息 |
| v1.2.0 | 2023-11-17 | 多 SIM 支持、消息列表组件、User-Agent、服务状态监控 |
| v1.5.0 | 2024-01-26 | 引入端到端加密(E2E encryption) |
| v1.9.0 | 2024-03-05 | 前台服务发送、待发消息队列、通知模块、GET /device 端点 |
| v1.15.0 | 2024-06-19 | Webhook 体系建立:注册、带重试的投递、设备 ID 字段、云同步 |
| v1.16.0 | 2024-07-03 | Ping 支持、事件总线(EventBus)、Orchestrator 服务 |
| v1.18.0 | 2024-08-12 | sms:sent 事件;MessageState 重构为 ProcessingState |
| v1.19.0 | 2024-09-17 | sms:delivered / sms:failed 事件;消息拉取限批 100 条 |
| v1.28.0 | 2025-01-02 | POST /messages/inbox/export 端点;ReceiverService 引入 |
| v1.33.0 | 2025-03-10 | Webhook 载荷签名(payload signing) |
| v1.37.0 | 2025-05-28 | 设置导入/导出,设置与云端同步 |
| v1.43.0 | 2025-08-06 | SSE(Server-Sent Events)实时事件、通知 |
| v1.44.0 | 2025-08-08 | 消息历史拉取(Get messages history) |
| v1.52.0 | 2025-12-06 | Webhook 队列(Webhooks queue) |
| v1.55.0 | 2026-03-03 | JWT 认证支持 |
| v1.64.0 | 2026-05-26 | JWT Refresh Token 支持 |
| v1.67.0 | 2026-07-08 | sms:cancelled 事件、取消待发消息、每 30 分钟发送限速 |
| v1.71.0 | 2026-08-18 | 批量 Webhook 事件(batch events) |
| v1.74.0 | 2026-08-31 | 通过 API 发送 MMS(含附件) |
| v1.76.0 | 2026-09-25 | 收件箱自动上传云端;加密升级为 hardened 格式(随机 salt + IV) |
| v1.77.0 | 2026-09-29 | 设备密钥对(device key)与混合加密 |
| v1.77.2 | 2026-10-05 | 重复电话号码拒绝;状态竞态原子化修复 |
三、消息发送能力的演进路线
3.1 从单条短信到多形态消息
v1.0.0 仅支持基础的 SmsManager 短信发送,随后能力逐层叠加:
- v1.2.1 加入多段长短信自动分片(multipart messages),对应源码中短信发送路径的
sendMultipartTextMessage类逻辑; - v1.39.0 引入数据短信(Data SMS)收发,
MessageContent.Data模型承载二进制数据与端口号(见 MessageContent.kt); - v1.47.0 提供基础 MMS 支持,v1.74.0 开放 API 发送 MMS:在
mmsMessage字段中携带一个或多个 Base64 附件、可选主题与正文,具体校验逻辑见 MmsMessage.kt; - v1.68.0 支持接收端 MMS 附件,并将 MMS 解析推迟到下载完成之后。
3.2 POST /message 请求模型与校验
API 的入参模型集中在 PostMessageRequest.kt,它同时覆盖本地与云两种模式,核心字段包括:
| 字段 | 类型 | 说明 |
|---|---|---|
phoneNumbers |
List<String> | 收件人列表,必须非空且唯一(v1.77.2 强制校验) |
textMessage |
TextMessage | 文本消息:{ "text": "..." } |
dataMessage |
DataMessage | 数据短信:携带 data 与 0~65535 的 port |
mmsMessage |
MmsMessage | 彩信:subject、text、Base64 attachments 列表 |
simNumber |
Int? | SIM 卡编号,从 1 开始(v1.2.0 多 SIM 支持) |
withDeliveryReport |
Boolean? | 是否请求送达回执(v1.3.0 引入) |
isEncrypted |
Boolean? | 载荷是否已加密 |
priority |
Byte | 发送优先级(v1.35.0 支持) |
ttl / validUntil |
Long / Date | 消息有效期,两者同时传入会抛 "fields conflict"(v1.7.1 引入) |
scheduleAt |
Date? | 定时发送时间,必须是未来时间戳(v1.61.0 引入) |
deviceId |
String? | 多设备模式下指定目标设备(v1.40.0 引入) |
validate() 方法(PostMessageRequest.kt)集中做了 7 类校验:消息类型互斥、文本非空、端口范围、MMS 至少含正文或附件、收件人非空、收件人唯一、scheduleAt 必须在未来——这直接印证了 v1.77.2 "发送重复电话号码被拒绝" 与 v1.61.0 "添加定时发送" 两条变更的实现落点。
3.3 队列、限速与定时
发送侧由 SendMessagesWorker.kt 驱动:作为前台服务(v1.9.0)以 WorkManager 唯一任务运行,支持 setInitialDelay 实现定时发送,并在线程为空闲时以 setExpedited 加急执行——这正是 v1.74.1 "新消息立即发送、不再等待调度 worker" 的实现基础。限速能力(v1.11.0 per period limits、v1.67.0 每 30 分钟限制)与随机延迟(v1.6.0)都作用于 MessagesService.sendPendingMessages() 的出队环节,避免触发运营商风控。
四、消息状态机与可靠性修复
4.1 ProcessingState 与状态转换表
v1.18.0 将 MessageState 重构为 ProcessingState,枚举定义见 ProcessingState.kt:Pending、Cancelled、Processed、Sent、Delivered、Failed 六态。转换合法性由纯函数状态表 MessageStateTransitions.kt 控制,其设计语义值得注意:
- 自转换(self transition)为合法 no-op,不触发数据库写入;
Cancelled不是终态:实际短信结果可以覆盖用户取消(如迟到的发送失败),Cancelled → Sent/Delivered/Failed均合法,Webhook 消费者最终收到的是真实状态;Failed是唯一终态,不允许任何迁出。
这解释了 [Unreleased] 中两条变更的深层原因:云端取消的消息在设备上直接落为 Cancelled(不再报告 Cancelling),以及取消与发送之间的竞态得以原子化解耦。
4.2 状态更新竞态修复(Unreleased)
Unreleased] 部分的 Fixed 条目明确指出:针对单条消息的发送、送达、失败、取消更新现在原子化应用,正在发送途中被取消的消息不再残留陈旧或矛盾状态;同时,一个后台处理器失败不再拖垮其他处理器(状态上传、Webhook 队列刷新、云端 Ping 互相隔离)。这与 [MessageStateTransitions.kt 的 canTransition 门卫逻辑一脉相承,也与 v1.70.3 "异步处理发送/送达广播,避免状态更新丢失" 形成延续性的可靠性投入。
4.3 状态解析兼容性(v1.75.1)
v1.75.1 改进了短信送达状态解析:支持 CDMA(3GPP2)格式并掩码状态位,使 sent/delivered/failed 报告更准确。结合 v1.31.1 "在 sendSMS 中记录异常堆栈" 与 v1.1.2 "Processed 状态支持",可以看出状态追踪一直是消息模块的高频修复点。
五、安全能力的层层加码
5.1 端到端加密的三次升级
安全是该项目演进最密集的轴线:
- v1.5.0 引入端到端加密,消息内容与收件人号码在发往 API 前加密、在设备端解密;
- v1.76.0 升级为 hardened 格式:每个加密值使用随机 salt 和 IV,同时向后兼容读取旧格式密文;
- v1.77.0 引入设备密钥对:应用生成 RSA 密钥对、将公钥上传云端服务器,本地服务器在设备注册响应中暴露
publicKey与keyVersion,消息内容与号码改用设备公钥做混合加密(hybrid encryption)。
算法路由在 EncryptionProviderFactory.kt 中集中体现,三种 Provider 对应三种格式:
| 格式标识 | Provider | 说明 |
|---|---|---|
aes-256-cbc/pbkdf2-sha1 |
LegacyPassphraseEncryptionProvider.kt | 旧版口令加密(仅用于解密兼容) |
aes-256-cbc/pbkdf2-sha1/v2 |
HardenedPassphraseEncryptionProvider.kt | v1.76.0 后的默认格式,随机 salt + IV |
rsa-oaep-aes-256-gcm |
RSAEncryptionProvider.kt | v1.77.0 设备公钥混合加密 |
DEFAULT_ALGORITHM 即 aes-256-cbc/pbkdf2-sha1/v2,且 Provider 按算法名缓存于 ConcurrentHashMap,避免重复构造。
5.2 密钥托管与指纹验证
设备密钥完全托管在 AndroidKeyStore 中(见 KeyStore.kt):API 21~22 使用 KeyPairGeneratorSpec,API 23+ 使用 KeyGenParameterSpec,RSA-2048 + OAEP 填充,私钥永不离开安全硬件。其代码注释明确:Private keys never leave AndroidKeyStore and no software keys exist anywhere。
配套的 Fingerprint.kt 计算公钥的 SHA-256 指纹,按 4 字符分组、冒号分隔展示(如 A1B2:C3D4:...),用于带外验证。密钥轮换由 DeviceKeyRotatedEvent.kt 与 KeyRotationWorker.kt 协同驱动。测试方面,仓库在 androidTest 下提供 HardenedPassphraseEncryptionProviderTest、LegacyPassphraseEncryptionProviderTest、RSAEncryptionProviderTest,在 test 下提供指纹测试,可验证三种 Provider 与指纹算法的正确性。
5.3 认证体系:从 Basic Auth 到 JWT
- v1.25.0 允许修改端口与凭据;v1.26.0 允许修改云端密码;v1.34.0 支持注册码注册;
- v1.55.0 引入 JWT 认证,v1.64.0 支持 Refresh Token。核心实现在 JwtService.kt:HMAC256 签发 access/refresh 令牌对,access token 携带
scopes声明,refresh token 仅含tokens:refreshscope 并记录original_scopes;刷新时执行令牌轮换(rotate),重用已轮换的 refresh token 会触发RefreshTokenReplayException(防重放)。令牌元数据持久化在 TokensDao.kt(由AppDatabase管理,schema 演进可见 app/schemas/me.capcom.smsgateway.data.AppDatabase 下的 25 个版本文件)。
此外,v1.33.0 加入 Webhook 载荷签名(PayloadSingingPlugin.kt),v1.31.0 内置根 CA 证书,v1.45.0 提供允许 HTTP 明文地址的 insecure 构建变体(仅限开发测试,详见 README.md)。
六、Webhook 生态的完整演进
6.1 事件体系:从 2 个到 14 个事件
v1.15.0 建立 Webhook 体系时仅有收短信事件,随后事件类型持续扩充。完整的 14 种事件定义集中在 WebHookEvent.kt:
| 事件 | 引入版本 | 触发时机 |
|---|---|---|
sms:received |
v1.15.0 | 收到 SMS |
sms:batch:received |
v1.71.0 | 批量收到 SMS |
sms:sent |
v1.18.0 | 短信已发送 |
sms:delivered |
v1.19.0 | 短信已送达 |
sms:failed |
v1.19.0 | 短信发送失败 |
sms:cancelled |
v1.67.0 | 待发短信被取消 |
sms:data-received |
v1.39.0 后 | 收到数据短信 |
sms:batch:data-received |
v1.71.0 | 批量收到数据短信 |
mms:received |
v1.56.0 前后 | 收到 MMS 通知(下载前) |
mms:batch:received |
v1.71.0 | 批量 MMS 通知 |
mms:downloaded |
v1.56.0 | MMS 完整下载(含正文与附件) |
mms:batch:downloaded |
v1.71.0 | 批量 MMS 下载完成 |
app:started |
v1.66.0 | 应用启动,携带活跃 SIM 卡列表 |
system:ping |
v1.16.0 | 周期性心跳 |
其中 batchEvent() 方法(WebHookEvent.kt)定义了单个事件到批量事件的映射,仅 4 种接收类事件支持批量聚合。投递实体 WebHookEventDTO.kt 携带 id、webhookId、event、deviceId 与 payload,其中的 deviceId 字段自 v1.15.0 起加入。
6.2 队列、重试与诊断
投递可靠性经历了多轮加固:
- v1.15.2 Webhook worker 加急执行、优化重试策略、解析接收方响应码;
- v1.21.0 增加重试次数选项;
- v1.52.0 引入 Webhook 队列(WebhookQueueEntity.kt、WebhookQueueRepository.kt),投递失败可持久化重放;
- v1.57.1 改为文件后端载荷存储(WebhookPayloadStorage.kt);
- v1.71.1 从轮询改为定时调度投递,加快派发;
- v1.75.0 在设置中新增 Webhook 队列诊断列表页(对应 WebhookQueueListFragment.kt 与 WebhookQueueViewModel.kt)。
事件派发逻辑集中在 WebHooksService.kt 的 emit():按事件查 DB、跳过未启用来源、为每个 Webhook 创建 DTO 并交给 SendWebhookWorker.kt 异步投递,同时记录排队/跳过统计日志。URL 校验规则(必须 https://,或 insecure 构建下的 http://,或 http://127.0.0.1 回环)也在该文件的 replace() 中实现。
七、云网关与收件箱:向云端集中
- v1.1.0 引入云端注册、令牌更新与消息状态上报;v1.10.0 处理 401 自动重新注册;
- v1.43.0 实现条件化 SSE 连接与实时事件通知(SSEForegroundService.kt、SSEManager.kt);
- v1.53.1 连接时强制拉取消息并记录拉取日志(PullMessagesWorker.kt 以最小周期调度,失败按指数退避重试);
- v1.59.0 引入收件箱 API(inbox API)与查询能力;
- v1.76.0 关键变更:收到的新消息(SMS、Data SMS、MMS)在连接云端时自动上传,实现集中访问。落地实现在 InboxUploadWorker.kt:以 100 条为一批循环处理待上传实体,单条失败记录日志并标记完成,批量失败则二分递归缩小批次重试,全程前台通知可见。
接收侧由 IncomingMessagesService.kt 将广播/内容观察者收到的消息(text:/data:/mms:/mms-header: 前缀哈希 ID)写入本地收件箱,MMS 附件经 Base64 解码后持久化到附件存储,并支持按生命周期天数定时截断清理(v1.70.0 定期清理收件消息)。
八、平台兼容、本地化与运维细节
- v1.72.1 在 Android 13+ 使用现代 subscription API 解析 SIM 号码,支持
READ_PHONE_NUMBERS权限;v1.2.0 起支持多 SIM(READ_PHONE_STATE);v1.23.0 尝试探测 SIM 卡槽号;v1.27.1 修复 SIM 轮换偏好; - v1.75.1 CDMA(3GPP2)送达状态解析;
- v1.66.1 增加短信内容观察者兜底(Content Observer fallback),v1.67.0 增加可在设置中关闭该观察者的开关,配合
DATE_SENT统一去重(修复广播与观察者双路径下的重复短信); - 本地化:v1.42.0/v1.53.0 添加简体中文(对应 values-zh/strings.xml),v1.47.1 添加俄语(values-ru/strings.xml),v1.60.0 添加阿拉伯语,v1.69.0 支持工作时间发送窗口;
- 构建与签名:v1.76.0 附带
.env.example构建签名配置,与 README.md 中SIGNING_STORE_PASSWORD/SIGNING_KEY_ALIAS/SIGNING_KEY_PASSWORD三变量及assembleRelease/assembleInsecure任务对应; - v1.41.0 内置 Swagger 文档端点,
docs/api/与app/src/main/assets/api/均保留离线 Swagger 静态资源。
九、总结:从 CHANGELOG 读到的东西
纵观 CHANGELOG.md 的 1389 行,android-sms-gateway 的演进呈现出三条清晰主线:
- 能力横向扩展:SMS → 数据短信 → MMS → 批量事件 → 云收件箱,每一次新增都在 localserver/domain/messages 与 webhooks/domain 留下对应的领域模型;
- 可靠性纵向加固:状态机原子化、取消与发送竞态修复、后台处理器故障隔离、Webhook 队列与文件化存储,配合 messages、webhooks/db 下的测试用例持续回归;
- 安全持续升级:端到端加密从 PBKDF2 口令方案演进到带随机 salt/IV 的 hardened 格式,再到设备密钥混合加密,密钥全程托管 AndroidKeyStore,形成"设备指纹 + 公钥上传 + 云端混合加密"的完整闭环。
对于希望集成或二次开发该项目的读者,建议以 README.md 的 Getting Started 为入口上手 API 与 Webhook,以 docs/MMS.md 深入 MMS 收发细节,再回到 CHANGELOG 按版本号定位每次行为变更的动机——版本历史本身就是一份按时间索引的架构决策记录。