Files

T

guke 7a2b7cb8ed 功能:阿里云号码认证短信 provider + sms.py 拆为可切换 provider 包

现有 sms.py(极光自管码)升级为 app/integrations/sms/ 包:
  - base   : SmsError + provider 无关的 mock_verify
  - jiguang: 原极光自管码逻辑逐字迁入,行为零改动(git 识别为 sms.py 的 rename)
  - aliyun : 新增阿里云 dypns 号码认证(Mode A:阿里云生成+下发+校验,核验免费)
  - __init__: 按 SMS_PROVIDER 每次调用路由的分派器(默认 jiguang,可秒切回退)

关键决策:
  - Mode A:发码 SendSmsVerifyCode(##code## 占位)、校验 CheckSmsVerifyCode(PASS/UNKNOWN);
    本服务不再存码 → 消除极光路径「内存存码、多 worker 不共享」技术债。
  - 防爆破与极光一致:aliyun 保留 per-phone 失败计数(SMS_MAX_VERIFY_ATTEMPTS),达上限本地作废,
    避免两 provider 行为不同致排查困惑(此为 aliyun 路径唯一本地态)。
  - 校验降级:阿里云接口异常 → verify_code 抛 SmsError(503),auth 两处 try/except 透出 503(非误报 400)。
  - 官方 SDK alibabacloud_dypnsapi20170525;SDK 交互隔离在 _call_send/_call_check(惰性 import + 惰性建
    client),单测 monkeypatch 不触真网络。

测试:test_sms_aliyun(17)+ test_sms_dispatch(3)全绿;test_auth 内部访问 retarget 到 jiguang.*。
配置:SMS_PROVIDER + ALIYUN_SMS_*(见 .env.example);文档 docs/integrations/sms.md + aliyun 接口参考。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-25 23:51:30 +08:00

5.1 KiB

Raw Blame History

短信验证码（sms）

文件:app/integrations/sms/(分派器 __init__ + jiguang / aliyun provider + base) | 关联接口:auth-sms-send · auth-sms-login | ← 集成索引

作用

手机号 + 验证码登录的验证码发送 / 校验。支持可切换 provider(SMS_PROVIDER):jiguang(默认,极光自管码)/ aliyun(阿里云号码认证托管码)。SMS_MOCK 另切 mock / real。

短信提供商(`SMS_PROVIDER`,可切换 + 灰度回退)

	`jiguang`(默认)	`aliyun`
验证码	本服务生成、极光只下发、本地内存校验	阿里云生成 + 下发 + 校验(dypns 号码认证,Mode A,核验免费)
发码	极光 `/v1/messages`	`SendSmsVerifyCode`(`##code##` 占位)
校验	比对本地存码	`CheckSmsVerifyCode` → `PASS` / `UNKNOWN`
多 worker	⚠️ 内存存码不共享(见已知局限)	✅ 阿里云托管,天然共享
防爆破	单码失败 `SMS_MAX_VERIFY_ATTEMPTS` 次即作废	同语义(本地 per-phone 失败计数,刻意与极光一致)
单号冷却	本地 `SMS_SEND_INTERVAL_SEC`	交给阿里云 `Interval`
校验降级	本地无网络调用	阿里云接口异常 → `/sms/login` 返 503(非 400,便于排查)

aliyun 需在号码认证控制台开通「融合认证」,用系统赠送签名 + 赠送模板;配置见 .env.example 的 ALIYUN_SMS_*,SDK 为 alibabacloud_dypnsapi20170525。以下章节描述 jiguang provider(自管码)细节。

	mock(`SMS_MOCK=true`,默认 / 开发测试)	real(`SMS_MOCK=false`,生产)
发送	不真发,验证码打日志	调极光 `/v1/messages` 真发
校验	放行任意 6 位数字(测试便利)	比对本服务存的码(一次性 / 过期 / 防爆破)

为什么是"自己生成码"模式

极光有两种验证码玩法:① /v1/codes 极光生成 + /codes/{msg_id}/valid 极光校验;② /v1/messages 本服务生成码、极光只负责发。选 ②:校验本地完成(不依赖极光二次往返)、有效期/错误次数/作废完全可控、跟原 mock 口子结构一致。

函数 / 异常

函数	行为
`send_code(phone) -> int`	防刷检查(冷却)→ `secrets` 生成 N 位码 → 预占(冷却/存码)→ mock 打日志 / real 调极光 → 失败回滚预占。返回距下次可发秒数
`verify_code(phone, code) -> bool`	mock 放行任意 6 位;real 比对存码,匹配即作废,失败累计到上限作废
`SmsError(msg, status_code)`	`status_code` 决定 HTTP 码:过频 429、供应商失败 503、号码无效 400

配置

配置项	默认	说明
`SMS_MOCK`	`true`	mock / real 切换。生产置 false
`SMS_CODE_TTL_SEC`	300	验证码有效期(秒),与极光模板文案"5分钟"一致
`SMS_SEND_INTERVAL_SEC`	60	单号两次发送最小间隔(冷却)
`SMS_SEND_ENDPOINT`	极光 `/v1/messages`	短信发送地址
`SMS_SIGN_ID`	31729	极光签名 ID
`SMS_TEMPLATE_ID`	1	极光模板 ID(变量名 `code`)
`SMS_CODE_LENGTH`	6	验证码位数(本服务生成;前端 code 4-8 位兼容)
`SMS_MAX_VERIFY_ATTEMPTS`	5	单码最多校验失败次数,超过作废(防爆破)

鉴权复用极光一键登录:/v1/messages 用 base64(JG_APP_KEY:JG_MASTER_SECRET) 做 HTTP Basic Auth——短信与一键登录是同一个极光应用(同 AppKey)。上线不需要额外凭证,只需 SMS_MOCK=false(JG_* 一键登录已配)。

防刷(短信花钱 + `/sms/send` 在登录前无法 JWT 鉴权)

2026-07-03 精简:登录风控只留「单号冷却 + 单设备频控」两道主策略(删单号每日上限、删登录纯 IP rate_limit);单码失败上限属验证码安全底线,保留。

单号 SMS_SEND_INTERVAL_SEC 冷却(单号维度)
单设备(device_id + IP)每小时频控:/sms/send ≤ SMS_SEND_MAX_PER_HOUR_PER_DEVICE(5)、/sms/login ≤ SMS_LOGIN_MAX_PER_HOUR(5)——堵「换号绕开单号冷却」+ 挡登录撞库,在 app/api/v1/auth.py 内 enforce_rate_limit
单码校验失败 SMS_MAX_VERIFY_ATTEMPTS 次即作废 + 验过即作废(一次性)
运维侧建议在极光控制台叠加:IP 白名单(只许服务器 IP)+ 防轰炸设置

极光错误码(节选,映射在 `_send_via_jiguang`)

code	含义	处理
50014	余额不足	`logger.critical` 告警 + 503
50009	极光侧超频	429
50006	手机号无效	400
其他	—	503

上线步骤

极光控制台:企业实名 + 短信充值 + 签名审核(sign_id=31729)+ 模板审核(temp_id=1)——均已就绪
.env 设 SMS_MOCK=false(JG_APP_KEY/JG_MASTER_SECRET 一键登录已配)
真机发一条验证:收到短信 + 能登录

已知局限

验证码存进程内存:单 worker uvicorn 够用;重启丢码(用户重发即可);多 worker / 多机不共享 → 冷却 / 校验失效,扩 worker 前迁移到 DB/Redis。见待办与技术债。

5.1 KiB Raw Blame History Unescape Escape