證碼接收平臺(tái)：接收、存儲(chǔ)、查詢與回調(diào)全鏈路教程)
做應(yīng)用開發(fā)這些年短信驗(yàn)證碼這東西看著不起眼但真到聯(lián)調(diào)階段能把人逼瘋。自己手機(jī)號(hào)不敢亂填、測(cè)試環(huán)境收不到短信、第三方平臺(tái)回調(diào)遲遲不來、驗(yàn)證碼過期了才發(fā)現(xiàn)沒存下來——這些問題幾乎每個(gè)后端和測(cè)試都遇到過。所以我花了兩個(gè)周末從零搭了一套短信驗(yàn)證碼接收平臺(tái)把接收、存儲(chǔ)、查詢、通知、管理后臺(tái)全鏈路打通順手整理成這篇超詳細(xì)教程。無論你是做API開發(fā)、自動(dòng)化測(cè)試、第三方登錄對(duì)接還是想給業(yè)務(wù)系統(tǒng)加個(gè)驗(yàn)證碼兜底通道這篇都能直接抄作業(yè)。整個(gè)平臺(tái)本質(zhì)上干的事情很簡(jiǎn)單把散落在各處的短信驗(yàn)證碼統(tǒng)一收攏到一個(gè)地方再通過HTTP接口或管理后臺(tái)隨時(shí)查。但真正落地的時(shí)候接入方式選型、數(shù)據(jù)模型設(shè)計(jì)、過期策略、回調(diào)防重、安全簽名這些細(xì)節(jié)才是大頭一個(gè)沒想清楚后面就要返工。下面按我的實(shí)際搭建順序從架構(gòu)設(shè)計(jì)講到部署上線把每一步的理由和坑都說明白。1. 平臺(tái)定位與整體方案設(shè)計(jì)1.1 這個(gè)平臺(tái)到底解決什么問題短信驗(yàn)證碼接收平臺(tái)不是一個(gè)給普通用戶用的產(chǎn)品它解決的是開發(fā)和測(cè)試環(huán)節(jié)里的一個(gè)具體痛點(diǎn)你沒法穩(wěn)定、可控地收到驗(yàn)證碼。比如你在做用戶注冊(cè)流程的自動(dòng)化測(cè)試每次跑用例都要真實(shí)填一個(gè)手機(jī)號(hào)、等短信、再讀驗(yàn)證碼填回去短信延遲一波動(dòng)整個(gè)用例就掛了。再比如你對(duì)接了某個(gè)第三方服務(wù)對(duì)方要求你提供接收回調(diào)的地址來收驗(yàn)證碼通知你總不能在本地起個(gè)服務(wù)等它回調(diào)。所以這個(gè)平臺(tái)的價(jià)值就三條第一把驗(yàn)證碼接收入口統(tǒng)一成標(biāo)準(zhǔn)HTTP接口方便任意語言調(diào)用第二把驗(yàn)證碼和手機(jī)號(hào)、業(yè)務(wù)標(biāo)識(shí)、時(shí)間關(guān)聯(lián)起來能按條件快速檢索第三提供管理后臺(tái)人也能直接查不用翻日志。想明白這三點(diǎn)后面的架構(gòu)就不會(huì)跑偏。1.2 兩條接入路線回調(diào)轉(zhuǎn)發(fā)還是硬件模塊接收短信驗(yàn)證碼本質(zhì)上就兩條路要么從云短信服務(wù)商那里拿回調(diào)要么自己搞一個(gè)能收短信的硬件網(wǎng)關(guān)。兩條路我都試過感受完全不同。云短信服務(wù)商回調(diào)是首選也是絕大多數(shù)業(yè)務(wù)場(chǎng)景適用的。原理是你把驗(yàn)證碼發(fā)到某個(gè)手機(jī)號(hào)之后運(yùn)營商或短信平臺(tái)會(huì)把短信內(nèi)容以HTTP回調(diào)的形式推送到你指定的URL你的平臺(tái)負(fù)責(zé)接收、解析、入庫。這種方式零硬件成本、接收延遲低、部署簡(jiǎn)單而且只要能收到回調(diào)驗(yàn)證碼內(nèi)容、發(fā)送時(shí)間、手機(jī)號(hào)這些字段都是結(jié)構(gòu)化帶過來的解析非常干凈。硬件GSM模塊方案則是兜底方案適合沒有云短信服務(wù)商資源、或者要收的是真實(shí)手機(jī)卡短信的場(chǎng)景。常見做法是搞一個(gè)樹莓派或者工控機(jī)插上SIM800L之類的GSM模塊模塊收到短信后通過串口把內(nèi)容讀出來再POST到你平臺(tái)的接口。這個(gè)方案的好處是短信真正落在你自己的卡上缺點(diǎn)也明顯硬件要維護(hù)、SIM卡要養(yǎng)號(hào)、信號(hào)不穩(wěn)定、并發(fā)一高就丟消息。我建議按需選擇不要一上來就上硬件先把回調(diào)方案跑通再說。1.3 技術(shù)選型為什么用 FastAPI Redis SQLite技術(shù)棧我選的是Python FastAPI Redis SQLite沒上重型中間件。原因很實(shí)際這個(gè)平臺(tái)的定位是輕量級(jí)內(nèi)部工具不是高并發(fā)業(yè)務(wù)系統(tǒng)。FastAPI寫起來快、自帶API文檔、異步性能也夠用Redis用來做驗(yàn)證碼的短期緩存和過期控制天然支持TTL省去自己寫定時(shí)任務(wù)刪數(shù)據(jù)的麻煩SQLite作為持久化存儲(chǔ)單文件備份方便數(shù)據(jù)量到百萬級(jí)之前完全扛得住。你要是更習(xí)慣Java或Go這套架構(gòu)思路完全能平移代碼邏輯都是一樣的。核心區(qū)別只在語法層。我傾向把重心放在設(shè)計(jì)思路上不要糾結(jié)用哪個(gè)框架先跑通再優(yōu)化。2. 核心數(shù)據(jù)模型與驗(yàn)證碼生命周期2.1 數(shù)據(jù)表設(shè)計(jì)與字段含義先看表結(jié)構(gòu)這是整個(gè)平臺(tái)的骨架。我設(shè)計(jì)了一張sms_code表字段如下字段名類型說明idINTEGER 主鍵自增唯一IDphoneVARCHAR(20)接收驗(yàn)證碼的手機(jī)號(hào)codeVARCHAR(10)驗(yàn)證碼內(nèi)容messageTEXT完整短信原文biz_idVARCHAR(64)業(yè)務(wù)標(biāo)識(shí)比如注冊(cè)、登錄、找回密碼channelVARCHAR(32)來源渠道aliyun/twilio/gsm等statusTINYINT0待使用 1已使用 2已過期expire_atDATETIME過期時(shí)間created_atDATETIME接收時(shí)間notifiedTINYINT是否已推送給業(yè)務(wù)方0/1每個(gè)字段都有用途重點(diǎn)說幾個(gè)容易忽略的。biz_id很關(guān)鍵業(yè)務(wù)方調(diào)用查詢接口時(shí)往往不是只查一個(gè)手機(jī)號(hào)下的所有驗(yàn)證碼而是帶著自己的業(yè)務(wù)單號(hào)來查沒有這個(gè)字段查詢就抓瞎。message必須存完整原文因?yàn)轵?yàn)證碼解析可能出錯(cuò)留原文方便事后核對(duì)。notified這個(gè)字段很多人會(huì)省但它是做回調(diào)通知防重的基礎(chǔ)沒有它回調(diào)推送失敗重試時(shí)就無法判斷是否已經(jīng)推過。2.2 驗(yàn)證碼狀態(tài)機(jī)待使用、已使用、已過期驗(yàn)證碼的生命周期很清晰三種狀態(tài)來回流轉(zhuǎn)待使用消息接收成功、解析出驗(yàn)證碼、入庫完成后的初始狀態(tài)。已使用業(yè)務(wù)方通過接口標(biāo)記該驗(yàn)證碼已被消費(fèi)防止同一驗(yàn)證碼被重復(fù)使用。已過期到達(dá)預(yù)設(shè)有效期后自動(dòng)進(jìn)入查詢接口默認(rèn)不返回過期驗(yàn)證碼。狀態(tài)流轉(zhuǎn)要在代碼里強(qiáng)制約束不能只在界面上顯示。我實(shí)現(xiàn)的邏輯是查詢接口返回待使用狀態(tài)的驗(yàn)證碼標(biāo)記使用時(shí)通過UPDATE ... WHERE status 0的方式做樂觀鎖如果更新影響行數(shù)為0說明已經(jīng)被消費(fèi)或過期直接返回失敗。這樣即使在多線程并發(fā)場(chǎng)景下同一個(gè)驗(yàn)證碼也只會(huì)被消費(fèi)一次。2.3 過期策略與防重復(fù)消費(fèi)過期策略我用了雙保險(xiǎn)。Redis里存一份keyTTL設(shè)為驗(yàn)證碼有效期默認(rèn)5分鐘到點(diǎn)自動(dòng)消失SQLite里也維護(hù)expire_at字段查詢時(shí)用SQL過濾expire_at now()。這樣即使Redis數(shù)據(jù)被清掉數(shù)據(jù)庫層依然有兜底。這里有個(gè)細(xì)節(jié)值得說驗(yàn)證碼的有效期應(yīng)該從短信發(fā)送時(shí)間算而不是從平臺(tái)接收時(shí)間算。云短信服務(wù)商回調(diào)里通常會(huì)帶發(fā)送時(shí)間沒有的話就取平臺(tái)接收時(shí)間近似。5分鐘有效期是個(gè)經(jīng)驗(yàn)值業(yè)務(wù)上一般短信驗(yàn)證碼都是5分鐘有效你按自己業(yè)務(wù)調(diào)整即可。過期時(shí)間到了不要物理刪除數(shù)據(jù)保留記錄便于審計(jì)只靠status2標(biāo)記過期就行等哪天數(shù)據(jù)膨脹了再定期清理。3. 短信接入層實(shí)現(xiàn)從收到短信到入庫3.1 方案A云短信服務(wù)商回調(diào)Webhook接入云短信回調(diào)的接入邏輯是最順的。以阿里云短信為例你在控制臺(tái)配置上行消息回調(diào)地址指向平臺(tái)的/webhook/sms接口即可。服務(wù)商收到短信后會(huì)把消息內(nèi)容POST到這個(gè)地址你的接口只需要驗(yàn)簽、解析、入庫三步。下面是我實(shí)現(xiàn)的FastAPI回調(diào)接口核心代碼# webhook.py import hashlib import hmac import json from datetime import datetime, timedelta from fastapi import APIRouter, Request, HTTPException router APIRouter(prefix/webhook, tags[webhook]) def verify_signature(payload: bytes, signature: str, secret: str) - bool: 服務(wù)商會(huì)用 secret 對(duì)請(qǐng)求體做 HMAC-SHA256 簽名 我們這邊用同樣的方式計(jì)算一次對(duì)比是否一致。 expected hmac.new( secret.encode(utf-8), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature) router.post(/sms) async def receive_sms_callback(request: Request): 接收云短信服務(wù)商的回調(diào)。 兼容阿里云/Twilio等常見格式字段名不同就做個(gè)映射。 body await request.body() headers request.headers signature headers.get(X-Signature, ) secret your_webhook_secret # 與短信平臺(tái)配置一致 if not verify_signature(body, signature, secret): raise HTTPException(status_code403, detailsignature verify failed) data json.loads(body) # 字段映射兼容不同服務(wù)商 phone data.get(phone) or data.get(mobile) or data.get(To) code data.get(code) or data.get(smsCode) or data.get(Body) message data.get(message) or data.get(text) or data.get(content) channel data.get(channel, unknown) if not phone or not code: raise HTTPException(status_code400, detailmissing required fields) # 入庫 緩存 通知一并處理 await save_sms_code( phonephone, codecode, messagemessage, channelchannel, expire_atdatetime.now() timedelta(minutes5), ) return {code: 0, msg: ok}這段代碼里最容易被坑的是驗(yàn)簽。很多服務(wù)商不是簡(jiǎn)單放一個(gè)簽名頭而是把簽名放在 query 參數(shù)里或者對(duì) body 做base64之后再簽名你按他們的文檔調(diào)整verify_signature里的簽名算法就行。我建議先不開啟驗(yàn)簽跑通全流程確認(rèn)回調(diào)能正常收到之后再打開驗(yàn)簽排查起來更快。3.2 方案BGSM模塊自建短信網(wǎng)關(guān)如果你沒有云短信服務(wù)商資源而是要用真實(shí)SIM卡收短信那就用GSM模塊方案。硬件連接方式很簡(jiǎn)單SIM800L模塊的VCC接5V電源、GND接地、TXD/RXD分別接樹莓派的RX/TX插上SIM卡、接好天線然后通過Python的pyserial讀取串口數(shù)據(jù)。核心邏輯是監(jiān)聽串口當(dāng)有新短信進(jìn)來時(shí)AT指令會(huì)主動(dòng)推送CMTI: SM, index這樣的通知然后你發(fā)送ATCMGRindex讀取指定索引的短信內(nèi)容解析出手機(jī)號(hào)和驗(yàn)證碼再POST到平臺(tái)的接收接口。這里有個(gè)大坑SIM卡短信存滿之后新短信會(huì)收不到所以每讀完一條就要用ATCMGDindex刪除保持存儲(chǔ)空間可用。GSM模塊收到短信內(nèi)容后如果驗(yàn)證碼和手機(jī)號(hào)是混在一起的用正則提取就行。比如短信內(nèi)容【XX網(wǎng)】您的驗(yàn)證碼是1234565分鐘內(nèi)有效用re.search(r(\\d{4,6}), message)就能把驗(yàn)證碼摳出來。整個(gè)過程不復(fù)雜但硬件調(diào)試耗時(shí)我前前后后折騰了一天才穩(wěn)定信號(hào)不好時(shí)收發(fā)延遲會(huì)到十幾秒要有心理準(zhǔn)備。3.3 入庫邏輯與消息隊(duì)列解耦回調(diào)接口收到短信后不能直接同步寫入數(shù)據(jù)庫就算完。因?yàn)槿霂熘笸€要做兩件事往Redis寫緩存、向外推送通知給業(yè)務(wù)方。這三件事如果串行做回調(diào)接口的響應(yīng)時(shí)間會(huì)被通知推送拖慢服務(wù)商那邊超時(shí)就會(huì)重推造成重復(fù)數(shù)據(jù)。我的做法是入庫之后把“推送通知”這個(gè)動(dòng)作塞進(jìn)一個(gè)內(nèi)存隊(duì)列由后臺(tái)任務(wù)池異步消費(fèi)回調(diào)接口只負(fù)責(zé)快速落庫并返回。如果你用Celery或者其他任務(wù)隊(duì)列也完全可以原理一樣。FastAPI里最簡(jiǎn)單的做法是用BackgroundTasksfrom fastapi import BackgroundTasks async def save_sms_code(phone: str, code: str, message: str, channel: str, expire_at: datetime): # 入庫 SQLite insert_sql INSERT INTO sms_code (phone, code, message, channel, status, expire_at, created_at) VALUES (?, ?, ?, ?, 0, ?, ?) await db.execute(insert_sql, ( phone, code, message, channel, expire_at.strftime(%Y-%m-%d %H:%M:%S), datetime.now().strftime(%Y-%m-%d %H:%M:%S), )) # 寫 RedisTTL 5 分鐘 redis_key fsms:latest:{phone} await redis.setex(redis_key, 300, json.dumps({ phone: phone, code: code, message: message, channel: channel, })) # 異步推送 background_tasks.add_task(notify_business, phone, code, message) router.post(/sms) async def receive_sms_callback(request: Request, background_tasks: BackgroundTasks): ... await save_sms_code(..., background_tasks) return {code: 0, msg: ok}這樣做的好處是回調(diào)接口的響應(yīng)時(shí)間穩(wěn)定在毫秒級(jí)服務(wù)商不會(huì)因?yàn)槌瑫r(shí)重推。入庫和通知解耦后哪怕通知服務(wù)掛了也不影響短信的正常接收和存儲(chǔ)。4. 查詢API與異步通知設(shè)計(jì)4.1 查詢接口按手機(jī)號(hào)或業(yè)務(wù)標(biāo)識(shí)拉取驗(yàn)證碼查詢接口是平臺(tái)對(duì)外輸出能力的主要入口。業(yè)務(wù)方的典型場(chǎng)景是測(cè)試腳本執(zhí)行到填寫驗(yàn)證碼這一步時(shí)調(diào)用你的接口傳入手機(jī)號(hào)拿到驗(yàn)證碼再填回去完成流程。所以接口設(shè)計(jì)要簡(jiǎn)單直接參數(shù)越少越好。# query_api.py from fastapi import APIRouter, Query router APIRouter(prefix/api, tags[api]) router.get(/sms/code) async def get_sms_code( phone: str Query(..., description手機(jī)號(hào)), biz_id: str Query(None, description業(yè)務(wù)標(biāo)識(shí)可選), ): 查詢最新一條未使用的驗(yàn)證碼。 默認(rèn)返回當(dāng)前時(shí)間前5分鐘內(nèi)、狀態(tài)為待使用的記錄。 sql SELECT id, phone, code, message, biz_id, channel, status, expire_at, created_at FROM sms_code WHERE phone ? AND status 0 AND expire_at ? ORDER BY id DESC LIMIT 1 row await db.fetch_one(sql, (phone, datetime.now().strftime(%Y-%m-%d %H:%M:%S))) if not row: return {code: 1, msg: no available sms code, data: None} if biz_id and row[biz_id] ! biz_id: return {code: 1, msg: biz_id mismatch, data: None} return {code: 0, msg: ok, data: dict(row)}查詢邏輯有一個(gè)重要的取舍默認(rèn)只返回最新一條待使用驗(yàn)證碼而不是返回所有記錄。原因是一般業(yè)務(wù)場(chǎng)景下你只需要最新的那個(gè)驗(yàn)證碼返回太多反而容易取錯(cuò)。如果你確實(shí)需要全部記錄加一個(gè)limit參數(shù)讓調(diào)用方自己控制即可。4.2 回調(diào)通知驗(yàn)證碼到達(dá)后主動(dòng)推送給業(yè)務(wù)方查詢接口是拉模式業(yè)務(wù)方主動(dòng)來取。但有些場(chǎng)景更適合推模式——驗(yàn)證碼一到達(dá)平臺(tái)主動(dòng)POST到業(yè)務(wù)方指定的回調(diào)地址業(yè)務(wù)方不用輪詢。我在平臺(tái)里加了一個(gè)notify_url配置業(yè)務(wù)方注冊(cè)時(shí)會(huì)綁定自己的回調(diào)地址和密鑰。推送邏輯用簡(jiǎn)單重試策略第一次推送失敗后間隔5秒、30秒、2分鐘各重試一次最多4次。同時(shí)依賴數(shù)據(jù)庫里的notified字段判斷狀態(tài)推送成功置14次都失敗則保持0方便事后人工補(bǔ)推。重試過程中要特別注意消息冪等業(yè)務(wù)方的接收接口應(yīng)該按驗(yàn)證碼ID去重否則重試會(huì)導(dǎo)致業(yè)務(wù)處理兩次。4.3 接口簽名與安全防護(hù)平臺(tái)內(nèi)部自己用的時(shí)候可以不做簽名但一旦要暴露給多個(gè)業(yè)務(wù)方簽名認(rèn)證就必須加。我的實(shí)現(xiàn)是每個(gè)業(yè)務(wù)方分配一個(gè)app_id和app_secret調(diào)用查詢接口時(shí)請(qǐng)求頭帶上X-App-Id和X-Timestamp同時(shí)用app_secret對(duì)請(qǐng)求參數(shù)做HMAC-SHA256得到一個(gè)X-Signature頭。服務(wù)端用相同方式計(jì)算簽名并對(duì)比同時(shí)檢查時(shí)間戳超過5分鐘視為過期請(qǐng)求。這個(gè)設(shè)計(jì)主要防兩件事一是防止接口被未授權(quán)的第三方調(diào)用二是防止請(qǐng)求被截獲后重放。時(shí)間戳校驗(yàn)就是防重放的因?yàn)轵?yàn)證碼數(shù)據(jù)本身敏感接口暴露在公網(wǎng)被亂抓就麻煩了。除了簽名我還在Nginx層加了IP白名單和限流雙保險(xiǎn)。5. 管理后臺(tái)與可視化查詢5.1 后臺(tái)頁面功能清單管理后臺(tái)我用的是一個(gè)很樸素的思路一個(gè)HTML頁面 一個(gè)查詢接口不做復(fù)雜前端框架。頁面功能就這么幾個(gè)按手機(jī)號(hào)查詢輸入手機(jī)號(hào)展示該號(hào)碼最近接收的驗(yàn)證碼記錄。按時(shí)間篩選默認(rèn)顯示最近30分鐘可切換1小時(shí)、24小時(shí)。標(biāo)記已使用每條記錄旁邊有個(gè)按鈕手動(dòng)把狀態(tài)改成已使用。查看原文點(diǎn)擊展開查看完整的短信原文和原始回調(diào)數(shù)據(jù)。后臺(tái)不需要做登錄注冊(cè)一個(gè)簡(jiǎn)單的Token校驗(yàn)就夠了部署在內(nèi)網(wǎng)最省事。如果非要暴露公網(wǎng)建議在Nginx層加HTTP Basic Auth多一層保險(xiǎn)。5.2 查詢操作與交互細(xì)節(jié)后臺(tái)的交互細(xì)節(jié)比很多人想象的重要。我踩過幾個(gè)坑驗(yàn)證碼列表默認(rèn)按接收時(shí)間倒序排這個(gè)必須做到否則你看到的第一條不是最新的會(huì)被誤判每條記錄要顯示接收時(shí)間的時(shí)區(qū)這個(gè)也必須有不然對(duì)不上時(shí)間線已使用的驗(yàn)證碼要有明顯的視覺區(qū)分我用了灰色標(biāo)簽避免誤用。另一個(gè)小細(xì)節(jié)是查詢結(jié)果里要把驗(yàn)證碼單獨(dú)列出來加粗顯示不要混在短信原文里面。因?yàn)闇y(cè)試人員在實(shí)際操作時(shí)是要把驗(yàn)證碼復(fù)制出去的他們不會(huì)去看原文。后臺(tái)頁面雖然簡(jiǎn)單但要圍繞“快速找到驗(yàn)證碼”這個(gè)核心目標(biāo)來設(shè)計(jì)其他花里胡哨的功能都是干擾。6. 部署上線與穩(wěn)定性優(yōu)化6.1 Docker Compose 一鍵部署部署方式我推薦Docker Compose一條命令起全套省去環(huán)境搭建的麻煩。目錄結(jié)構(gòu)如下sms-platform/ ├── app/ │ ├── main.py │ ├── webhook.py │ ├── query_api.py │ ├── database.py │ ├── models.py │ └── requirements.txt ├── Dockerfile ├── docker-compose.yml └── data/ └── sms.dbdocker-compose.yml里只需要兩個(gè)服務(wù)一個(gè)FastAPI應(yīng)用一個(gè)Redis。SQLite數(shù)據(jù)庫文件通過volume掛載到宿主機(jī)方便備份。內(nèi)容如下# docker-compose.yml version: 3.8 services: redis: image: redis:7-alpine container_name: sms-redis restart: always ports: - 6379:6379 app: build: . container_name: sms-platform restart: always ports: - 8000:8000 environment: - REDIS_URLredis://redis:6379/0 - DATABASE_PATH/app/data/sms.db - TOKENyour_admin_token volumes: - ./data:/app/data depends_on: - redis啟動(dòng)命令就是docker compose up -d --build訪問http://服務(wù)器IP:8000/docs就能看到FastAPI自動(dòng)生成的接口文檔管理后臺(tái)頁面放在http://服務(wù)器IP:8000/admin。6.2 關(guān)鍵配置項(xiàng)說明配置項(xiàng)的坑主要集中在環(huán)境變量上。我強(qiáng)烈建議把所有可變參數(shù)都抽到環(huán)境變量里不要在代碼里硬編碼。關(guān)鍵配置有這么幾個(gè)環(huán)境變量默認(rèn)值說明REDIS_URLredis://localhost:6379/0Redis連接串DATABASE_PATH./sms.dbSQLite數(shù)據(jù)庫文件路徑TOKENadmin123管理后臺(tái)訪問TokenWEBHOOK_SECRET空回調(diào)接口驗(yàn)簽密鑰CODE_TTL_SECONDS300驗(yàn)證碼有效期秒數(shù)這些配置看起來簡(jiǎn)單但每一項(xiàng)都在生產(chǎn)環(huán)境里坑過我。比如DATABASE_PATH容器里如果不掛載volume重啟一下數(shù)據(jù)庫就沒了數(shù)據(jù)全丟。再比如CODE_TTL_SECONDS剛開始寫死5分鐘后來業(yè)務(wù)方要求改成10分鐘改代碼重新部署太麻煩抽成環(huán)境變量一行就搞定。6.3 穩(wěn)定性監(jiān)控與告警平臺(tái)穩(wěn)定性監(jiān)控一開始我覺得沒有必要反正就是個(gè)內(nèi)部工具。直到有一次云短信服務(wù)商回調(diào)突然斷了一個(gè)多小時(shí)我完全沒察覺業(yè)務(wù)方找過來才發(fā)現(xiàn)。從那以后我加了三層監(jiān)控第一層心跳接口。加一個(gè)/healthz返回?cái)?shù)據(jù)庫和Redis的連接狀態(tài)配合云監(jiān)控平臺(tái)做探活掛了自動(dòng)告警。第二層數(shù)據(jù)量監(jiān)控。每分鐘統(tǒng)計(jì)接收的驗(yàn)證碼數(shù)量寫入日志如果一段時(shí)間內(nèi)數(shù)量驟降為0大概率是回調(diào)鏈路出問題了。第三層推送失敗告警。如果通知業(yè)務(wù)方的notified字段長(zhǎng)時(shí)間保持0說明推送鏈路有異常需要人工介入。這三層監(jiān)控不需要專門搭一個(gè)監(jiān)控系統(tǒng)最簡(jiǎn)陋的做法就是寫幾個(gè)腳本定時(shí)跑發(fā)現(xiàn)問題往企業(yè)微信或釘釘群發(fā)個(gè)消息。監(jiān)控的核心是“能發(fā)現(xiàn)問題”而不是“用什么工具發(fā)現(xiàn)”。7. 常見問題與排查技巧實(shí)錄7.1 收不到驗(yàn)證碼短信這是最常遇到的問題一上來懷疑云短信服務(wù)商有問題其實(shí)大半是本地配置問題。按照我排查的經(jīng)驗(yàn)順序應(yīng)該是先看回調(diào)日志有沒有請(qǐng)求進(jìn)來沒有請(qǐng)求就說明回調(diào)地址沒配置對(duì)或者服務(wù)商那邊根本沒把短信發(fā)出去有請(qǐng)求但入庫失敗就看是不是驗(yàn)簽沒過、字段解析失敗入庫成功但查詢不到就看是不是狀態(tài)被提前改成已使用或者Redis和SQLite的過期時(shí)間不一致。這一套排查下來絕大多數(shù)收不到短信的問題都能定位。千萬注意不要跳過看日志這一步去猜原因回調(diào)日志是你排查的第一手資料必須保留。7.2 回調(diào)超時(shí)或重復(fù)推送云短信服務(wù)商的回調(diào)是有超時(shí)時(shí)間的一般3到5秒。如果你的回調(diào)接口里做了耗時(shí)操作比如同步推送通知響應(yīng)慢了服務(wù)商就會(huì)重推造成同一個(gè)驗(yàn)證碼入庫多條記錄。這個(gè)問題根因就是入庫邏輯里沒做冪等。解決辦法有兩個(gè)層面第一入庫前檢查手機(jī)號(hào)加驗(yàn)證碼加接收時(shí)間的唯一索引重復(fù)的直接忽略第二把耗時(shí)操作移出回調(diào)請(qǐng)求鏈路異步執(zhí)行。兩件事都做了重復(fù)推送的問題基本絕跡。另外還要注意即使做了冪等日志里也要保留每次回調(diào)的原始記錄方便核對(duì)。7.3 驗(yàn)證碼亂碼或解析失敗驗(yàn)證碼解析失敗通常出現(xiàn)在GSM模塊方案里云回調(diào)方案很少見。GSM模塊收到的短信內(nèi)容會(huì)受編碼影響常見的情況是中文短信內(nèi)容變成亂碼但驗(yàn)證碼是數(shù)字所以還能提取出來。如果連數(shù)字都解析不了大概率是短信內(nèi)容里驗(yàn)證碼格式不是純連續(xù)數(shù)字比如驗(yàn)證碼為 1 2 3 4 5 6中間有空格正則匹配就失敗。我的處理方案是用兩步提取第一優(yōu)先用正則匹配連續(xù)數(shù)字第二如果匹配不到就按常見關(guān)鍵詞切分取關(guān)鍵詞后面的字段再清除非數(shù)字字符。這個(gè)兜底邏輯不完美但應(yīng)付常見格式足夠了。另外GSM模塊方案里的AT指令解析也有編碼坑串口默認(rèn)可能是7-bit或8-bit模式要按SIM卡的字符集調(diào)整否則中文必亂。7.4 時(shí)區(qū)與過期時(shí)間坑時(shí)區(qū)問題是那種“看起來沒問題跑起來全是問題”的隱藏坑。FastAPI默認(rèn)用的是服務(wù)器本地時(shí)間如果你服務(wù)器是UTC時(shí)區(qū)而你和業(yè)務(wù)方都在東八區(qū)那么你存的created_at和業(yè)務(wù)方看到的時(shí)間就對(duì)不上。我吃過這個(gè)虧排查了半天才發(fā)現(xiàn)是時(shí)區(qū)偏移。統(tǒng)一方案是服務(wù)器統(tǒng)一設(shè)置成Asia/Shanghai所有時(shí)間字段存儲(chǔ)和展示都用東八區(qū)時(shí)間。在Docker環(huán)境里需要在啟動(dòng)命令里加-e TZAsia/Shanghai同時(shí)代碼里也強(qiáng)制指定雙保險(xiǎn)。過期時(shí)間的計(jì)算也基于東八區(qū)時(shí)間不要混用UTC和本地時(shí)間否則驗(yàn)證碼明明沒過期卻顯示過期查起來特別抓狂。8. 合規(guī)邊界與我的個(gè)人體會(huì)8.1 合規(guī)使用場(chǎng)景提醒這個(gè)平臺(tái)本身是開發(fā)工具但它接收的是短信驗(yàn)證碼這種敏感信息所以使用邊界一定要講清楚。合法的場(chǎng)景是你自己業(yè)務(wù)系統(tǒng)里的測(cè)試號(hào)碼回調(diào)、你開發(fā)的自動(dòng)化測(cè)試腳本、你自建的短信網(wǎng)關(guān)監(jiān)控。一句話總結(jié)就是平臺(tái)只能接收你自己能合法接收的短信不能用于繞過實(shí)名認(rèn)證、批量注冊(cè)、惡意薅羊毛等違法違規(guī)場(chǎng)景。另外如果平臺(tái)里存儲(chǔ)了真實(shí)的手機(jī)號(hào)和短信內(nèi)容要注意隱私保護(hù)。至少要做到三點(diǎn)數(shù)據(jù)庫文件權(quán)限收緊、管理后臺(tái)訪問加認(rèn)證、日志脫敏處理。不要覺得內(nèi)部工具就無所謂數(shù)據(jù)安全這根弦任何時(shí)候都不能松。8.2 個(gè)人實(shí)操體會(huì)這套平臺(tái)前前后后改了三版第一版只是簡(jiǎn)單把回調(diào)存進(jìn)數(shù)據(jù)庫第二版加了查詢接口第三版才補(bǔ)上Redis緩存、通知推送、簽名認(rèn)證。每一次改動(dòng)都是被真實(shí)場(chǎng)景逼出來的不是一開始就設(shè)計(jì)好的。所以我特別建議你第一次搭的時(shí)候先跑通最小閉環(huán)不要貪大求全后面遇到具體需求再迭代加功能。如果要擴(kuò)展這個(gè)平臺(tái)可以考慮的方向有驗(yàn)證碼識(shí)別接入OCR模型自動(dòng)識(shí)別短信驗(yàn)證碼圖片多租戶支持給不同業(yè)務(wù)方分配獨(dú)立密鑰和存儲(chǔ)隔離監(jiān)控?cái)?shù)據(jù)可視化。但這些都屬于錦上添花核心鏈路反而是多多打磨細(xì)節(jié)——驗(yàn)簽、冪等、過期、防重、監(jiān)控把這些做到位平臺(tái)才能真正扛得住生產(chǎn)環(huán)境的折騰。 從零搭建短信驗(yàn)證碼接收平臺(tái)：接收、存儲(chǔ)、查詢與回調(diào)全鏈路教程
做應(yīng)用開發(fā)這些年短信驗(yàn)證碼這東西看著不起眼但真到聯(lián)調(diào)階段能把人逼瘋。自己手機(jī)號(hào)不敢亂填、測(cè)試環(huán)境收不到短信、第三方平臺(tái)回調(diào)遲遲不來、驗(yàn)證碼過期了才發(fā)現(xiàn)沒存下來——這些問題幾乎每個(gè)后端和測(cè)試都遇到過。所以我花了兩個(gè)周末從零搭了一套短信驗(yàn)證碼接收平臺(tái)把接收、存儲(chǔ)、查詢、通知、管理后臺(tái)全鏈路打通順手整理成這篇超詳細(xì)教程。無論你是做API開發(fā)、自動(dòng)化測(cè)試、第三方登錄對(duì)接還是想給業(yè)務(wù)系統(tǒng)加個(gè)驗(yàn)證碼兜底通道這篇都能直接抄作業(yè)。整個(gè)平臺(tái)本質(zhì)上干的事情很簡(jiǎn)單把散落在各處的短信驗(yàn)證碼統(tǒng)一收攏到一個(gè)地方再通過HTTP接口或管理后臺(tái)隨時(shí)查。但真正落地的時(shí)候接入方式選型、數(shù)據(jù)模型設(shè)計(jì)、過期策略、回調(diào)防重、安全簽名這些細(xì)節(jié)才是大頭一個(gè)沒想清楚后面就要返工。下面按我的實(shí)際搭建順序從架構(gòu)設(shè)計(jì)講到部署上線把每一步的理由和坑都說明白。1. 平臺(tái)定位與整體方案設(shè)計(jì)1.1 這個(gè)平臺(tái)到底解決什么問題短信驗(yàn)證碼接收平臺(tái)不是一個(gè)給普通用戶用的產(chǎn)品它解決的是開發(fā)和測(cè)試環(huán)節(jié)里的一個(gè)具體痛點(diǎn)你沒法穩(wěn)定、可控地收到驗(yàn)證碼。比如你在做用戶注冊(cè)流程的自動(dòng)化測(cè)試每次跑用例都要真實(shí)填一個(gè)手機(jī)號(hào)、等短信、再讀驗(yàn)證碼填回去短信延遲一波動(dòng)整個(gè)用例就掛了。再比如你對(duì)接了某個(gè)第三方服務(wù)對(duì)方要求你提供接收回調(diào)的地址來收驗(yàn)證碼通知你總不能在本地起個(gè)服務(wù)等它回調(diào)。所以這個(gè)平臺(tái)的價(jià)值就三條第一把驗(yàn)證碼接收入口統(tǒng)一成標(biāo)準(zhǔn)HTTP接口方便任意語言調(diào)用第二把驗(yàn)證碼和手機(jī)號(hào)、業(yè)務(wù)標(biāo)識(shí)、時(shí)間關(guān)聯(lián)起來能按條件快速檢索第三提供管理后臺(tái)人也能直接查不用翻日志。想明白這三點(diǎn)后面的架構(gòu)就不會(huì)跑偏。1.2 兩條接入路線回調(diào)轉(zhuǎn)發(fā)還是硬件模塊接收短信驗(yàn)證碼本質(zhì)上就兩條路要么從云短信服務(wù)商那里拿回調(diào)要么自己搞一個(gè)能收短信的硬件網(wǎng)關(guān)。兩條路我都試過感受完全不同。云短信服務(wù)商回調(diào)是首選也是絕大多數(shù)業(yè)務(wù)場(chǎng)景適用的。原理是你把驗(yàn)證碼發(fā)到某個(gè)手機(jī)號(hào)之后運(yùn)營商或短信平臺(tái)會(huì)把短信內(nèi)容以HTTP回調(diào)的形式推送到你指定的URL你的平臺(tái)負(fù)責(zé)接收、解析、入庫。這種方式零硬件成本、接收延遲低、部署簡(jiǎn)單而且只要能收到回調(diào)驗(yàn)證碼內(nèi)容、發(fā)送時(shí)間、手機(jī)號(hào)這些字段都是結(jié)構(gòu)化帶過來的解析非常干凈。硬件GSM模塊方案則是兜底方案適合沒有云短信服務(wù)商資源、或者要收的是真實(shí)手機(jī)卡短信的場(chǎng)景。常見做法是搞一個(gè)樹莓派或者工控機(jī)插上SIM800L之類的GSM模塊模塊收到短信后通過串口把內(nèi)容讀出來再POST到你平臺(tái)的接口。這個(gè)方案的好處是短信真正落在你自己的卡上缺點(diǎn)也明顯硬件要維護(hù)、SIM卡要養(yǎng)號(hào)、信號(hào)不穩(wěn)定、并發(fā)一高就丟消息。我建議按需選擇不要一上來就上硬件先把回調(diào)方案跑通再說。1.3 技術(shù)選型為什么用 FastAPI Redis SQLite技術(shù)棧我選的是Python FastAPI Redis SQLite沒上重型中間件。原因很實(shí)際這個(gè)平臺(tái)的定位是輕量級(jí)內(nèi)部工具不是高并發(fā)業(yè)務(wù)系統(tǒng)。FastAPI寫起來快、自帶API文檔、異步性能也夠用Redis用來做驗(yàn)證碼的短期緩存和過期控制天然支持TTL省去自己寫定時(shí)任務(wù)刪數(shù)據(jù)的麻煩SQLite作為持久化存儲(chǔ)單文件備份方便數(shù)據(jù)量到百萬級(jí)之前完全扛得住。你要是更習(xí)慣Java或Go這套架構(gòu)思路完全能平移代碼邏輯都是一樣的。核心區(qū)別只在語法層。我傾向把重心放在設(shè)計(jì)思路上不要糾結(jié)用哪個(gè)框架先跑通再優(yōu)化。2. 核心數(shù)據(jù)模型與驗(yàn)證碼生命周期2.1 數(shù)據(jù)表設(shè)計(jì)與字段含義先看表結(jié)構(gòu)這是整個(gè)平臺(tái)的骨架。我設(shè)計(jì)了一張sms_code表字段如下字段名類型說明idINTEGER 主鍵自增唯一IDphoneVARCHAR(20)接收驗(yàn)證碼的手機(jī)號(hào)codeVARCHAR(10)驗(yàn)證碼內(nèi)容messageTEXT完整短信原文biz_idVARCHAR(64)業(yè)務(wù)標(biāo)識(shí)比如注冊(cè)、登錄、找回密碼channelVARCHAR(32)來源渠道aliyun/twilio/gsm等statusTINYINT0待使用 1已使用 2已過期expire_atDATETIME過期時(shí)間created_atDATETIME接收時(shí)間notifiedTINYINT是否已推送給業(yè)務(wù)方0/1每個(gè)字段都有用途重點(diǎn)說幾個(gè)容易忽略的。biz_id很關(guān)鍵業(yè)務(wù)方調(diào)用查詢接口時(shí)往往不是只查一個(gè)手機(jī)號(hào)下的所有驗(yàn)證碼而是帶著自己的業(yè)務(wù)單號(hào)來查沒有這個(gè)字段查詢就抓瞎。message必須存完整原文因?yàn)轵?yàn)證碼解析可能出錯(cuò)留原文方便事后核對(duì)。notified這個(gè)字段很多人會(huì)省但它是做回調(diào)通知防重的基礎(chǔ)沒有它回調(diào)推送失敗重試時(shí)就無法判斷是否已經(jīng)推過。2.2 驗(yàn)證碼狀態(tài)機(jī)待使用、已使用、已過期驗(yàn)證碼的生命周期很清晰三種狀態(tài)來回流轉(zhuǎn)待使用消息接收成功、解析出驗(yàn)證碼、入庫完成后的初始狀態(tài)。已使用業(yè)務(wù)方通過接口標(biāo)記該驗(yàn)證碼已被消費(fèi)防止同一驗(yàn)證碼被重復(fù)使用。已過期到達(dá)預(yù)設(shè)有效期后自動(dòng)進(jìn)入查詢接口默認(rèn)不返回過期驗(yàn)證碼。狀態(tài)流轉(zhuǎn)要在代碼里強(qiáng)制約束不能只在界面上顯示。我實(shí)現(xiàn)的邏輯是查詢接口返回待使用狀態(tài)的驗(yàn)證碼標(biāo)記使用時(shí)通過UPDATE ... WHERE status 0的方式做樂觀鎖如果更新影響行數(shù)為0說明已經(jīng)被消費(fèi)或過期直接返回失敗。這樣即使在多線程并發(fā)場(chǎng)景下同一個(gè)驗(yàn)證碼也只會(huì)被消費(fèi)一次。2.3 過期策略與防重復(fù)消費(fèi)過期策略我用了雙保險(xiǎn)。Redis里存一份keyTTL設(shè)為驗(yàn)證碼有效期默認(rèn)5分鐘到點(diǎn)自動(dòng)消失SQLite里也維護(hù)expire_at字段查詢時(shí)用SQL過濾expire_at now()。這樣即使Redis數(shù)據(jù)被清掉數(shù)據(jù)庫層依然有兜底。這里有個(gè)細(xì)節(jié)值得說驗(yàn)證碼的有效期應(yīng)該從短信發(fā)送時(shí)間算而不是從平臺(tái)接收時(shí)間算。云短信服務(wù)商回調(diào)里通常會(huì)帶發(fā)送時(shí)間沒有的話就取平臺(tái)接收時(shí)間近似。5分鐘有效期是個(gè)經(jīng)驗(yàn)值業(yè)務(wù)上一般短信驗(yàn)證碼都是5分鐘有效你按自己業(yè)務(wù)調(diào)整即可。過期時(shí)間到了不要物理刪除數(shù)據(jù)保留記錄便于審計(jì)只靠status2標(biāo)記過期就行等哪天數(shù)據(jù)膨脹了再定期清理。3. 短信接入層實(shí)現(xiàn)從收到短信到入庫3.1 方案A云短信服務(wù)商回調(diào)Webhook接入云短信回調(diào)的接入邏輯是最順的。以阿里云短信為例你在控制臺(tái)配置上行消息回調(diào)地址指向平臺(tái)的/webhook/sms接口即可。服務(wù)商收到短信后會(huì)把消息內(nèi)容POST到這個(gè)地址你的接口只需要驗(yàn)簽、解析、入庫三步。下面是我實(shí)現(xiàn)的FastAPI回調(diào)接口核心代碼# webhook.py import hashlib import hmac import json from datetime import datetime, timedelta from fastapi import APIRouter, Request, HTTPException router APIRouter(prefix/webhook, tags[webhook]) def verify_signature(payload: bytes, signature: str, secret: str) - bool: 服務(wù)商會(huì)用 secret 對(duì)請(qǐng)求體做 HMAC-SHA256 簽名 我們這邊用同樣的方式計(jì)算一次對(duì)比是否一致。 expected hmac.new( secret.encode(utf-8), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature) router.post(/sms) async def receive_sms_callback(request: Request): 接收云短信服務(wù)商的回調(diào)。 兼容阿里云/Twilio等常見格式字段名不同就做個(gè)映射。 body await request.body() headers request.headers signature headers.get(X-Signature, ) secret your_webhook_secret # 與短信平臺(tái)配置一致 if not verify_signature(body, signature, secret): raise HTTPException(status_code403, detailsignature verify failed) data json.loads(body) # 字段映射兼容不同服務(wù)商 phone data.get(phone) or data.get(mobile) or data.get(To) code data.get(code) or data.get(smsCode) or data.get(Body) message data.get(message) or data.get(text) or data.get(content) channel data.get(channel, unknown) if not phone or not code: raise HTTPException(status_code400, detailmissing required fields) # 入庫 緩存 通知一并處理 await save_sms_code( phonephone, codecode, messagemessage, channelchannel, expire_atdatetime.now() timedelta(minutes5), ) return {code: 0, msg: ok}這段代碼里最容易被坑的是驗(yàn)簽。很多服務(wù)商不是簡(jiǎn)單放一個(gè)簽名頭而是把簽名放在 query 參數(shù)里或者對(duì) body 做base64之后再簽名你按他們的文檔調(diào)整verify_signature里的簽名算法就行。我建議先不開啟驗(yàn)簽跑通全流程確認(rèn)回調(diào)能正常收到之后再打開驗(yàn)簽排查起來更快。3.2 方案BGSM模塊自建短信網(wǎng)關(guān)如果你沒有云短信服務(wù)商資源而是要用真實(shí)SIM卡收短信那就用GSM模塊方案。硬件連接方式很簡(jiǎn)單SIM800L模塊的VCC接5V電源、GND接地、TXD/RXD分別接樹莓派的RX/TX插上SIM卡、接好天線然后通過Python的pyserial讀取串口數(shù)據(jù)。核心邏輯是監(jiān)聽串口當(dāng)有新短信進(jìn)來時(shí)AT指令會(huì)主動(dòng)推送CMTI: SM, index這樣的通知然后你發(fā)送ATCMGRindex讀取指定索引的短信內(nèi)容解析出手機(jī)號(hào)和驗(yàn)證碼再POST到平臺(tái)的接收接口。這里有個(gè)大坑SIM卡短信存滿之后新短信會(huì)收不到所以每讀完一條就要用ATCMGDindex刪除保持存儲(chǔ)空間可用。GSM模塊收到短信內(nèi)容后如果驗(yàn)證碼和手機(jī)號(hào)是混在一起的用正則提取就行。比如短信內(nèi)容【XX網(wǎng)】您的驗(yàn)證碼是1234565分鐘內(nèi)有效用re.search(r(\\d{4,6}), message)就能把驗(yàn)證碼摳出來。整個(gè)過程不復(fù)雜但硬件調(diào)試耗時(shí)我前前后后折騰了一天才穩(wěn)定信號(hào)不好時(shí)收發(fā)延遲會(huì)到十幾秒要有心理準(zhǔn)備。3.3 入庫邏輯與消息隊(duì)列解耦回調(diào)接口收到短信后不能直接同步寫入數(shù)據(jù)庫就算完。因?yàn)槿霂熘笸€要做兩件事往Redis寫緩存、向外推送通知給業(yè)務(wù)方。這三件事如果串行做回調(diào)接口的響應(yīng)時(shí)間會(huì)被通知推送拖慢服務(wù)商那邊超時(shí)就會(huì)重推造成重復(fù)數(shù)據(jù)。我的做法是入庫之后把“推送通知”這個(gè)動(dòng)作塞進(jìn)一個(gè)內(nèi)存隊(duì)列由后臺(tái)任務(wù)池異步消費(fèi)回調(diào)接口只負(fù)責(zé)快速落庫并返回。如果你用Celery或者其他任務(wù)隊(duì)列也完全可以原理一樣。FastAPI里最簡(jiǎn)單的做法是用BackgroundTasksfrom fastapi import BackgroundTasks async def save_sms_code(phone: str, code: str, message: str, channel: str, expire_at: datetime): # 入庫 SQLite insert_sql INSERT INTO sms_code (phone, code, message, channel, status, expire_at, created_at) VALUES (?, ?, ?, ?, 0, ?, ?) await db.execute(insert_sql, ( phone, code, message, channel, expire_at.strftime(%Y-%m-%d %H:%M:%S), datetime.now().strftime(%Y-%m-%d %H:%M:%S), )) # 寫 RedisTTL 5 分鐘 redis_key fsms:latest:{phone} await redis.setex(redis_key, 300, json.dumps({ phone: phone, code: code, message: message, channel: channel, })) # 異步推送 background_tasks.add_task(notify_business, phone, code, message) router.post(/sms) async def receive_sms_callback(request: Request, background_tasks: BackgroundTasks): ... await save_sms_code(..., background_tasks) return {code: 0, msg: ok}這樣做的好處是回調(diào)接口的響應(yīng)時(shí)間穩(wěn)定在毫秒級(jí)服務(wù)商不會(huì)因?yàn)槌瑫r(shí)重推。入庫和通知解耦后哪怕通知服務(wù)掛了也不影響短信的正常接收和存儲(chǔ)。4. 查詢API與異步通知設(shè)計(jì)4.1 查詢接口按手機(jī)號(hào)或業(yè)務(wù)標(biāo)識(shí)拉取驗(yàn)證碼查詢接口是平臺(tái)對(duì)外輸出能力的主要入口。業(yè)務(wù)方的典型場(chǎng)景是測(cè)試腳本執(zhí)行到填寫驗(yàn)證碼這一步時(shí)調(diào)用你的接口傳入手機(jī)號(hào)拿到驗(yàn)證碼再填回去完成流程。所以接口設(shè)計(jì)要簡(jiǎn)單直接參數(shù)越少越好。# query_api.py from fastapi import APIRouter, Query router APIRouter(prefix/api, tags[api]) router.get(/sms/code) async def get_sms_code( phone: str Query(..., description手機(jī)號(hào)), biz_id: str Query(None, description業(yè)務(wù)標(biāo)識(shí)可選), ): 查詢最新一條未使用的驗(yàn)證碼。 默認(rèn)返回當(dāng)前時(shí)間前5分鐘內(nèi)、狀態(tài)為待使用的記錄。 sql SELECT id, phone, code, message, biz_id, channel, status, expire_at, created_at FROM sms_code WHERE phone ? AND status 0 AND expire_at ? ORDER BY id DESC LIMIT 1 row await db.fetch_one(sql, (phone, datetime.now().strftime(%Y-%m-%d %H:%M:%S))) if not row: return {code: 1, msg: no available sms code, data: None} if biz_id and row[biz_id] ! biz_id: return {code: 1, msg: biz_id mismatch, data: None} return {code: 0, msg: ok, data: dict(row)}查詢邏輯有一個(gè)重要的取舍默認(rèn)只返回最新一條待使用驗(yàn)證碼而不是返回所有記錄。原因是一般業(yè)務(wù)場(chǎng)景下你只需要最新的那個(gè)驗(yàn)證碼返回太多反而容易取錯(cuò)。如果你確實(shí)需要全部記錄加一個(gè)limit參數(shù)讓調(diào)用方自己控制即可。4.2 回調(diào)通知驗(yàn)證碼到達(dá)后主動(dòng)推送給業(yè)務(wù)方查詢接口是拉模式業(yè)務(wù)方主動(dòng)來取。但有些場(chǎng)景更適合推模式——驗(yàn)證碼一到達(dá)平臺(tái)主動(dòng)POST到業(yè)務(wù)方指定的回調(diào)地址業(yè)務(wù)方不用輪詢。我在平臺(tái)里加了一個(gè)notify_url配置業(yè)務(wù)方注冊(cè)時(shí)會(huì)綁定自己的回調(diào)地址和密鑰。推送邏輯用簡(jiǎn)單重試策略第一次推送失敗后間隔5秒、30秒、2分鐘各重試一次最多4次。同時(shí)依賴數(shù)據(jù)庫里的notified字段判斷狀態(tài)推送成功置14次都失敗則保持0方便事后人工補(bǔ)推。重試過程中要特別注意消息冪等業(yè)務(wù)方的接收接口應(yīng)該按驗(yàn)證碼ID去重否則重試會(huì)導(dǎo)致業(yè)務(wù)處理兩次。4.3 接口簽名與安全防護(hù)平臺(tái)內(nèi)部自己用的時(shí)候可以不做簽名但一旦要暴露給多個(gè)業(yè)務(wù)方簽名認(rèn)證就必須加。我的實(shí)現(xiàn)是每個(gè)業(yè)務(wù)方分配一個(gè)app_id和app_secret調(diào)用查詢接口時(shí)請(qǐng)求頭帶上X-App-Id和X-Timestamp同時(shí)用app_secret對(duì)請(qǐng)求參數(shù)做HMAC-SHA256得到一個(gè)X-Signature頭。服務(wù)端用相同方式計(jì)算簽名并對(duì)比同時(shí)檢查時(shí)間戳超過5分鐘視為過期請(qǐng)求。這個(gè)設(shè)計(jì)主要防兩件事一是防止接口被未授權(quán)的第三方調(diào)用二是防止請(qǐng)求被截獲后重放。時(shí)間戳校驗(yàn)就是防重放的因?yàn)轵?yàn)證碼數(shù)據(jù)本身敏感接口暴露在公網(wǎng)被亂抓就麻煩了。除了簽名我還在Nginx層加了IP白名單和限流雙保險(xiǎn)。5. 管理后臺(tái)與可視化查詢5.1 后臺(tái)頁面功能清單管理后臺(tái)我用的是一個(gè)很樸素的思路一個(gè)HTML頁面 一個(gè)查詢接口不做復(fù)雜前端框架。頁面功能就這么幾個(gè)按手機(jī)號(hào)查詢輸入手機(jī)號(hào)展示該號(hào)碼最近接收的驗(yàn)證碼記錄。按時(shí)間篩選默認(rèn)顯示最近30分鐘可切換1小時(shí)、24小時(shí)。標(biāo)記已使用每條記錄旁邊有個(gè)按鈕手動(dòng)把狀態(tài)改成已使用。查看原文點(diǎn)擊展開查看完整的短信原文和原始回調(diào)數(shù)據(jù)。后臺(tái)不需要做登錄注冊(cè)一個(gè)簡(jiǎn)單的Token校驗(yàn)就夠了部署在內(nèi)網(wǎng)最省事。如果非要暴露公網(wǎng)建議在Nginx層加HTTP Basic Auth多一層保險(xiǎn)。5.2 查詢操作與交互細(xì)節(jié)后臺(tái)的交互細(xì)節(jié)比很多人想象的重要。我踩過幾個(gè)坑驗(yàn)證碼列表默認(rèn)按接收時(shí)間倒序排這個(gè)必須做到否則你看到的第一條不是最新的會(huì)被誤判每條記錄要顯示接收時(shí)間的時(shí)區(qū)這個(gè)也必須有不然對(duì)不上時(shí)間線已使用的驗(yàn)證碼要有明顯的視覺區(qū)分我用了灰色標(biāo)簽避免誤用。另一個(gè)小細(xì)節(jié)是查詢結(jié)果里要把驗(yàn)證碼單獨(dú)列出來加粗顯示不要混在短信原文里面。因?yàn)闇y(cè)試人員在實(shí)際操作時(shí)是要把驗(yàn)證碼復(fù)制出去的他們不會(huì)去看原文。后臺(tái)頁面雖然簡(jiǎn)單但要圍繞“快速找到驗(yàn)證碼”這個(gè)核心目標(biāo)來設(shè)計(jì)其他花里胡哨的功能都是干擾。6. 部署上線與穩(wěn)定性優(yōu)化6.1 Docker Compose 一鍵部署部署方式我推薦Docker Compose一條命令起全套省去環(huán)境搭建的麻煩。目錄結(jié)構(gòu)如下sms-platform/ ├── app/ │ ├── main.py │ ├── webhook.py │ ├── query_api.py │ ├── database.py │ ├── models.py │ └── requirements.txt ├── Dockerfile ├── docker-compose.yml └── data/ └── sms.dbdocker-compose.yml里只需要兩個(gè)服務(wù)一個(gè)FastAPI應(yīng)用一個(gè)Redis。SQLite數(shù)據(jù)庫文件通過volume掛載到宿主機(jī)方便備份。內(nèi)容如下# docker-compose.yml version: 3.8 services: redis: image: redis:7-alpine container_name: sms-redis restart: always ports: - 6379:6379 app: build: . container_name: sms-platform restart: always ports: - 8000:8000 environment: - REDIS_URLredis://redis:6379/0 - DATABASE_PATH/app/data/sms.db - TOKENyour_admin_token volumes: - ./data:/app/data depends_on: - redis啟動(dòng)命令就是docker compose up -d --build訪問http://服務(wù)器IP:8000/docs就能看到FastAPI自動(dòng)生成的接口文檔管理后臺(tái)頁面放在http://服務(wù)器IP:8000/admin。6.2 關(guān)鍵配置項(xiàng)說明配置項(xiàng)的坑主要集中在環(huán)境變量上。我強(qiáng)烈建議把所有可變參數(shù)都抽到環(huán)境變量里不要在代碼里硬編碼。關(guān)鍵配置有這么幾個(gè)環(huán)境變量默認(rèn)值說明REDIS_URLredis://localhost:6379/0Redis連接串DATABASE_PATH./sms.dbSQLite數(shù)據(jù)庫文件路徑TOKENadmin123管理后臺(tái)訪問TokenWEBHOOK_SECRET空回調(diào)接口驗(yàn)簽密鑰CODE_TTL_SECONDS300驗(yàn)證碼有效期秒數(shù)這些配置看起來簡(jiǎn)單但每一項(xiàng)都在生產(chǎn)環(huán)境里坑過我。比如DATABASE_PATH容器里如果不掛載volume重啟一下數(shù)據(jù)庫就沒了數(shù)據(jù)全丟。再比如CODE_TTL_SECONDS剛開始寫死5分鐘后來業(yè)務(wù)方要求改成10分鐘改代碼重新部署太麻煩抽成環(huán)境變量一行就搞定。6.3 穩(wěn)定性監(jiān)控與告警平臺(tái)穩(wěn)定性監(jiān)控一開始我覺得沒有必要反正就是個(gè)內(nèi)部工具。直到有一次云短信服務(wù)商回調(diào)突然斷了一個(gè)多小時(shí)我完全沒察覺業(yè)務(wù)方找過來才發(fā)現(xiàn)。從那以后我加了三層監(jiān)控第一層心跳接口。加一個(gè)/healthz返回?cái)?shù)據(jù)庫和Redis的連接狀態(tài)配合云監(jiān)控平臺(tái)做探活掛了自動(dòng)告警。第二層數(shù)據(jù)量監(jiān)控。每分鐘統(tǒng)計(jì)接收的驗(yàn)證碼數(shù)量寫入日志如果一段時(shí)間內(nèi)數(shù)量驟降為0大概率是回調(diào)鏈路出問題了。第三層推送失敗告警。如果通知業(yè)務(wù)方的notified字段長(zhǎng)時(shí)間保持0說明推送鏈路有異常需要人工介入。這三層監(jiān)控不需要專門搭一個(gè)監(jiān)控系統(tǒng)最簡(jiǎn)陋的做法就是寫幾個(gè)腳本定時(shí)跑發(fā)現(xiàn)問題往企業(yè)微信或釘釘群發(fā)個(gè)消息。監(jiān)控的核心是“能發(fā)現(xiàn)問題”而不是“用什么工具發(fā)現(xiàn)”。7. 常見問題與排查技巧實(shí)錄7.1 收不到驗(yàn)證碼短信這是最常遇到的問題一上來懷疑云短信服務(wù)商有問題其實(shí)大半是本地配置問題。按照我排查的經(jīng)驗(yàn)順序應(yīng)該是先看回調(diào)日志有沒有請(qǐng)求進(jìn)來沒有請(qǐng)求就說明回調(diào)地址沒配置對(duì)或者服務(wù)商那邊根本沒把短信發(fā)出去有請(qǐng)求但入庫失敗就看是不是驗(yàn)簽沒過、字段解析失敗入庫成功但查詢不到就看是不是狀態(tài)被提前改成已使用或者Redis和SQLite的過期時(shí)間不一致。這一套排查下來絕大多數(shù)收不到短信的問題都能定位。千萬注意不要跳過看日志這一步去猜原因回調(diào)日志是你排查的第一手資料必須保留。7.2 回調(diào)超時(shí)或重復(fù)推送云短信服務(wù)商的回調(diào)是有超時(shí)時(shí)間的一般3到5秒。如果你的回調(diào)接口里做了耗時(shí)操作比如同步推送通知響應(yīng)慢了服務(wù)商就會(huì)重推造成同一個(gè)驗(yàn)證碼入庫多條記錄。這個(gè)問題根因就是入庫邏輯里沒做冪等。解決辦法有兩個(gè)層面第一入庫前檢查手機(jī)號(hào)加驗(yàn)證碼加接收時(shí)間的唯一索引重復(fù)的直接忽略第二把耗時(shí)操作移出回調(diào)請(qǐng)求鏈路異步執(zhí)行。兩件事都做了重復(fù)推送的問題基本絕跡。另外還要注意即使做了冪等日志里也要保留每次回調(diào)的原始記錄方便核對(duì)。7.3 驗(yàn)證碼亂碼或解析失敗驗(yàn)證碼解析失敗通常出現(xiàn)在GSM模塊方案里云回調(diào)方案很少見。GSM模塊收到的短信內(nèi)容會(huì)受編碼影響常見的情況是中文短信內(nèi)容變成亂碼但驗(yàn)證碼是數(shù)字所以還能提取出來。如果連數(shù)字都解析不了大概率是短信內(nèi)容里驗(yàn)證碼格式不是純連續(xù)數(shù)字比如驗(yàn)證碼為 1 2 3 4 5 6中間有空格正則匹配就失敗。我的處理方案是用兩步提取第一優(yōu)先用正則匹配連續(xù)數(shù)字第二如果匹配不到就按常見關(guān)鍵詞切分取關(guān)鍵詞后面的字段再清除非數(shù)字字符。這個(gè)兜底邏輯不完美但應(yīng)付常見格式足夠了。另外GSM模塊方案里的AT指令解析也有編碼坑串口默認(rèn)可能是7-bit或8-bit模式要按SIM卡的字符集調(diào)整否則中文必亂。7.4 時(shí)區(qū)與過期時(shí)間坑時(shí)區(qū)問題是那種“看起來沒問題跑起來全是問題”的隱藏坑。FastAPI默認(rèn)用的是服務(wù)器本地時(shí)間如果你服務(wù)器是UTC時(shí)區(qū)而你和業(yè)務(wù)方都在東八區(qū)那么你存的created_at和業(yè)務(wù)方看到的時(shí)間就對(duì)不上。我吃過這個(gè)虧排查了半天才發(fā)現(xiàn)是時(shí)區(qū)偏移。統(tǒng)一方案是服務(wù)器統(tǒng)一設(shè)置成Asia/Shanghai所有時(shí)間字段存儲(chǔ)和展示都用東八區(qū)時(shí)間。在Docker環(huán)境里需要在啟動(dòng)命令里加-e TZAsia/Shanghai同時(shí)代碼里也強(qiáng)制指定雙保險(xiǎn)。過期時(shí)間的計(jì)算也基于東八區(qū)時(shí)間不要混用UTC和本地時(shí)間否則驗(yàn)證碼明明沒過期卻顯示過期查起來特別抓狂。8. 合規(guī)邊界與我的個(gè)人體會(huì)8.1 合規(guī)使用場(chǎng)景提醒這個(gè)平臺(tái)本身是開發(fā)工具但它接收的是短信驗(yàn)證碼這種敏感信息所以使用邊界一定要講清楚。合法的場(chǎng)景是你自己業(yè)務(wù)系統(tǒng)里的測(cè)試號(hào)碼回調(diào)、你開發(fā)的自動(dòng)化測(cè)試腳本、你自建的短信網(wǎng)關(guān)監(jiān)控。一句話總結(jié)就是平臺(tái)只能接收你自己能合法接收的短信不能用于繞過實(shí)名認(rèn)證、批量注冊(cè)、惡意薅羊毛等違法違規(guī)場(chǎng)景。另外如果平臺(tái)里存儲(chǔ)了真實(shí)的手機(jī)號(hào)和短信內(nèi)容要注意隱私保護(hù)。至少要做到三點(diǎn)數(shù)據(jù)庫文件權(quán)限收緊、管理后臺(tái)訪問加認(rèn)證、日志脫敏處理。不要覺得內(nèi)部工具就無所謂數(shù)據(jù)安全這根弦任何時(shí)候都不能松。8.2 個(gè)人實(shí)操體會(huì)這套平臺(tái)前前后后改了三版第一版只是簡(jiǎn)單把回調(diào)存進(jìn)數(shù)據(jù)庫第二版加了查詢接口第三版才補(bǔ)上Redis緩存、通知推送、簽名認(rèn)證。每一次改動(dòng)都是被真實(shí)場(chǎng)景逼出來的不是一開始就設(shè)計(jì)好的。所以我特別建議你第一次搭的時(shí)候先跑通最小閉環(huán)不要貪大求全后面遇到具體需求再迭代加功能。如果要擴(kuò)展這個(gè)平臺(tái)可以考慮的方向有驗(yàn)證碼識(shí)別接入OCR模型自動(dòng)識(shí)別短信驗(yàn)證碼圖片多租戶支持給不同業(yè)務(wù)方分配獨(dú)立密鑰和存儲(chǔ)隔離監(jiān)控?cái)?shù)據(jù)可視化。但這些都屬于錦上添花核心鏈路反而是多多打磨細(xì)節(jié)——驗(yàn)簽、冪等、過期、防重、監(jiān)控把這些做到位平臺(tái)才能真正扛得住生產(chǎn)環(huán)境的折騰。