
去年十一月对账,有三笔支付成功的单子在我们系统里还是未支付状态。查了两个小时,发现是回调地址配错了一个字符:登记的时候多打了一个斜杠,对方每次回调都打到 404,重试三轮之后放弃。
同一周还有另一件事。一个下游系统升级,回调处理变慢,对方的重试机制是每分钟一次、不设上限,我们的接口在十分钟里收到四千多次重复请求,队列堵住,连正常回调也进不来了。
这两件事指向同一套东西:回调地址要有人登记、要校验、要能改;接收端要验签、要去重、要快速返回。这篇讲我们现在的做法,代码部分是一个可以直接改用的接收端。
地址写错、地址不可达、验签失败、处理超时、重复请求互相覆盖、以及我们没接住的异常。六种里只有两种会留下明显日志,其余四种表现都是“对方说发了,我们没收到”。
地址写错这种出现得多,也难查,因为登记页面只校验格式,不校验可达。格式校验能拦住少写协议头的,拦不住多一个斜杠的。
处理超时比较隐蔽。对方等三秒,我们处理用了五秒,对方判定失败开始重试,我们这边其实处理成功了,于是同一笔业务被处理两次。看起来是重复问题,根子是超时。
登记环节解决“地址对不对”,接收环节解决“这条消息是不是真的、是不是已经处理过”。两件事分开做,不能靠一边兜。
登记环节的三个校验:格式合法、全局唯一、可达性探测。可达性探测是发一个探测请求,带一个随机串,要求对方原样返回,返回不了就不允许启用。
接收环节的三个校验:签名、时间窗、幂等键。签名证明来源,时间窗防重放,幂等键防重复处理。三个都在,才算接住了一条回调。
回调成功率、平均处理耗时、重复率。成功率按对方的重试次数反推,重复率按幂等键的命中次数算。
我们现在的基线是成功率百分之九十九点七,平均耗时八十毫秒,重复率百分之二点一。重复率不是零,因为对方的重试和我们的处理成功之间存在时间差,这个差值消不掉,只能靠幂等吸收。
一张表存一个第三方应用的回调配置:应用标识、回调地址、签名算法、密钥版本、状态、生效时间、备注。地址不加唯一约束,加的是应用标识加地址的唯一约束,因为同一个地址可以被多个应用共用。
状态有四种:草稿、待验证、启用、停用。只有启用状态的配置参与实际接收。草稿和待验证的区别是草稿还没提交探测,待验证是探测没过。
密钥单独存一张表,按版本号管理。回调配置只存版本号,不存密钥本身。这样换密钥的时候可以先让新旧两个版本并行一段时间,不用一次性切换。
格式校验用白名单:只接受特定协议、特定端口范围、不允许内网网段、不允许带查询参数。带查询参数这件事我们踩过坑,对方在拼接的时候会把参数吃掉。
唯一性校验按应用加地址做,不按地址全局做。全局唯一看着整齐,实际会挡住测试环境和生产环境共用一个回调网关的情况。
可达性探测在保存之后异步执行,不阻塞保存。探测失败不回滚配置,只把状态置为待验证,并且给出一个明确的失败原因,比如连接超时、返回码不是 200、返回内容不匹配。
改地址是有风险的,改完到对方生效之间有窗口期。我们的做法是允许一条配置挂两个地址,主地址和备用地址,接收端两个都收,去重按幂等键做。
切换流程是:先加备用地址,观察三天两个地址都有流量,再把主备对调,稳定一周后下线旧地址。整个过程不回滚配置,只调整顺序。
回调的登记和灰度切换,我们放在搭贝的集成配置里维护,改地址不用发版,改完当天生效。这条对我们很重要,因为以前改一个地址要走一次上线流程,平均等两天。
签名用 HMAC,待签内容固定为“时间戳加一个点加原始报文”。原始报文必须是请求体原文,不能是反序列化之后再序列化的结果,字段顺序一变签名就对不上。
时间窗给五分钟。太短会被网络抖动误伤,太长会给重放留空间。时间窗内的重复请求交给幂等键处理,不靠时间窗拦。
幂等键用对方的业务事件 ID,不用我们自己生成的 ID。落一张事件表,唯一索引建在应用标识加事件 ID 上,插入成功才处理,插入冲突直接返回成功。
返回成功要快。对方的超时时间通常是三到五秒,我们给它的承诺是两百毫秒内返回,实际处理放队列异步做。这条如果不做,慢一点就会触发重试,重试又变重复。
# 回调接收:验签、时间窗、幂等落库,先回 200 再异步处理
import hmac
import time
import json
import hashlib
from flask import Flask, request
app = Flask(__name__)
WINDOW_SEC = 300 # 允许的时钟偏差
def build_sign(secret, ts, body):
msg = (ts + ".").encode() + body
return hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest()
@app.post("/cb/<app_id>")
def callback(app_id):
body = request.get_data()
ts = request.headers.get("X-Ts", "")
sig = request.headers.get("X-Sign", "")
if not ts.isdigit() or abs(time.time() - int(ts)) > WINDOW_SEC:
return {"code": "expired"}, 400
secret = load_secret(app_id)
if not secret or not hmac.compare_digest(build_sign(secret, ts, body), sig):
return {"code": "bad_sign"}, 401
event = json.loads(body)
event_id = event.get("id")
if not event_id:
return {"code": "no_event_id"}, 400
row = db.execute(
"""INSERT INTO cb_event (app_id, event_id, payload, received_at)
VALUES (%s, %s, %s, now())
ON CONFLICT (app_id, event_id) DO NOTHING
RETURNING id""",
(app_id, event_id, body.decode("utf-8"))).fetchone()
if row:
queue.put({"event_row": row[0], "app_id": app_id})
return {"code": "ok"}, 200三个细节值得说。compare_digest 用常量时间比较,避免签名被逐字节试探。ON CONFLICT DO NOTHING 把去重交给数据库,不靠应用层先查后插,那样在并发下会漏。只有插入成功才入队,重复请求不入队也不报错,对方看到 200 就停止重试。
我们对下游的重试是五次,间隔按 1、4、16、64、256 秒递增,五次都失败进死信表,由人工处理。重试只针对网络错误和 5xx,4xx 不重试,因为参数错了重试多少次都一样。
对方对我们的重试,我们只能建议,不能控制。所以接收端必须按对方的节奏按坏情况打算:假设对方每分钟重试一次、持续一小时,我们的去重和限流都要扛得住。
回调再稳也有丢的时候。我们的兜底是主动查询:支付类回调每十分钟扫一次未完结的单据,向对方查询接口确认状态,查到成功就补一条本地记录。
主动查询的成本比回调高得多,不能全量做。只查超过十分钟还没收到回调的单据,正常情况下一批只有几条。
四个告警:单应用回调成功率跌破百分之九十五、重复率超过百分之十、死信表超过二十条、某个应用连续两小时零回调。零回调这个告警很有用,对方停发或者地址失效都能尽早发现。
告警阈值不要设得太敏感。我们起初把成功率阈值设成百分之九十九点九,每天响三四次,响了两周之后就没人看了,这条告警等于不存在。
回调成功率从百分之九十六点二升到百分之九十九点七,重复处理导致的账目差异从每月四笔降到零,因地址变更引起的故障从每月一到两次降到零。
登记页面加上可达性探测之后,配置错误在保存阶段就被拦住,不用等到对账才发现。这一条省下的排查时间比代码优化多得多。
密钥轮换还是手工的。理论上应该定期换,实际做起来要协调对方改配置,一年只换一次。这块没有好的自动化办法,只能靠流程提醒。
另一个是多环境共用回调网关时的路由。测试和生产的地址不同,但对方只配一个,我们靠应用标识区分。这个做法能跑,但一旦应用标识配错,回调会进到另一个环境,排查起来很费劲。
问:对方不提供签名,只有 IP 白名单,怎么防伪造?
答:IP 白名单只能证明来源网段,不能证明报文没被改。可行的补强是要求对方在报文里带业务单号和金额,我们回查本地单据,两者对不上就拒绝。这个校验挡不住重放,重放还得靠事件 ID 去重。
问:回调报文很大,签名验证会不会成为瓶颈?
答:HMAC 的耗时和报文长度线性相关,几百 KB 的报文验证在毫秒级,不是瓶颈。真正的瓶颈是反序列化和落库。做法是验签之后只取事件 ID 和时间戳,原始报文整段存文本,业务处理放异步,接收端只做三件事。
问:同一个事件 ID 对方重发但内容不一样,怎么处理?
答:说明对方那边出问题了,不能当成重复丢弃。做法是记录一条冲突日志,保留先到的那份,后到的进人工核查表。不要用后到的覆盖先到的,覆盖会让已经处理过的业务状态和数据对不上。
问:回调地址能不能用固定 IP 而不配域名?
答:技术上可以,运维上不建议。IP 变更的时候对方要跟着改,而对方的变更流程往往比我们慢。域名加证书的切换成本低得多,出问题也容易定位。如果必须用 IP,至少要在登记表里记录变更历史,方便排查。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。