做链上收款这一块的朋友大概都被同一个场景折磨过运营在群里 你说客户明明在区块浏览器上看到了转账记录后台订单却还是待支付你去查发现交易确实上链成功了但监听任务卡在某个高度不动或者回调被对方服务端当成重复请求丢掉了。这类问题排查起来最费时间因为它横跨了链上数据、任务调度、状态机、HTTP 回调四层任何一层出问题表现都是钱到了但单没结。这篇内容就把TRC20 收款系统的核心链路完整拆一遍区块监听怎么做才不漏块交易确认要多深才敢置成功回调机制怎么设计才能扛住重复和乱序。适合已经有基本后端能力、正在做或准备做链上收款模块的同学也适合负责撮合、订单系统的同学理解对账口径。我不会只丢代码片段重点是讲清楚每个参数为什么这么定、每一步为什么这么排。踩过的坑我会原样写出来包括那些文档里绝对不会告诉你、只有线上跑崩了才会知道的细节。1. 系统整体设计与核心链路拆解1.1 一条收款链路到底包含哪些环节先把全景摊开。TRC20 收款系统的本质是把一条不可逆的链上事实映射成一条可被业务系统消费的订单状态。中间隔着的每一步都可能是故障点所以设计之初就要把链路切成职责清晰的几层。一条完整的链路大概是这样的用户在你的页面下单系统分配一个收款地址或者带 memo 的固定地址用户从钱包发起 TRC20 转账交易进入链上打包出块后产生交易回执和事件日志你的监听服务扫到这条日志做地址匹配、金额换算、合约地址校验写入本地流水表然后根据确认数把订单状态从待支付推进到已支付最后通过 HTTP 回调把结果推给商户业务系统商户侧返回 200 才算真正闭环。这条链路上有三个天然的时间边界理解它们非常关键。第一个是交易上链到事件日志可见一般在 3 秒左右TRON 的出块间隔大约就是 3 秒一个块。第二个是交易上链到固化块网络上普遍认为需要等 19 个块左右的共识确认换算下来大约 57 秒上下很多团队干脆取整到 60 秒。第三个是你判定为已支付到商户真正记账这个取决于回调的重试策略可能拖到几分钟甚至几小时。绝大多数钱到了单没结的投诉都出在第三个边界上。我在设计时习惯把这条链路拆成四个独立进程扫描器负责从链上拉数据落原始表匹配器负责把原始流水关联到订单推进器负责按确认数改状态通知器负责回调重试。拆开的好处太明显了——扫描器卡住不影响已经落库的流水继续匹配通知器挂掉不影响订单状态正确每一层都可以独立重启、独立扩容、独立监控滞后量。你要是把它们揉成一个定时任务那排查问题的时候就只能看日志猜非常痛苦。1.2 为什么选事件日志监听而不是余额轮询新手最容易想到的方案是轮询每 5 秒查一次收款地址的 TRC20 余额变了就说明收到钱了。这个方案在单地址、低频、测试环境里能跑通但上线就废原因有四条。第一余额是状态不是事件。余额增加 100 只能说明净变化你无法判断这是一笔转账还是三笔加一笔转出也无法知道是谁打的、什么时候打的、交易哈希是什么。而收款系统必须要拿到交易哈希因为对账、退款、客诉举证全靠它。第二精度和并发会打架。同一秒内两笔转账到账余额从 0 变成 100你只能看到一次变化另一笔就丢了。如果你的订单金额有重复比如两个用户都付了 50你连哪笔对应哪个用户都分不清。第三成本高且滞后。余额查询是典型的全量拉取地址越多成本越高而且轮询间隔天然带来延迟间隔短了压节点间隔长了用户体验差。第四无法处理归集。如果你的收款地址需要定期把资金归集到主钱包余额会减少轮询逻辑立刻误判成用户撤回了付款这在业务上是灾难性的。正确做法是订阅 TRC20 合约的Transfer事件。TRC20 标准强制要求每次转账都抛出这个事件包含from、to、value三个字段配合交易哈希和日志序号构成了一条唯一、可追溯、不可伪造在合约层面的流水记录。这就好比银行的交易流水单而不是账户余额截图——后者只能证明现在有多少钱前者才能证明这笔钱是谁在什么时候打给你的。1.3 技术栈选型与节点接入方式节点接入这块我给三个层次的方案按团队规模选。轻量方案第三方 HTTP API如 TronGrid 这类公共网关。优点是不用运维节点开箱即用免费额度对小体量业务够用缺点是有限流高峰期可能拉不到块而且你必须信任对方返回的数据完整性。适合日订单几百笔以内的场景或者项目刚起步验证阶段。用这个方案时一定要做好块高度连续性检查因为限流导致的漏块不会报错只会静默跳过。标准方案自建全节点 HTTP 接口。用官方的 java-tron 起一个 FullNode磁盘按 2TB 以上规划链数据会持续增长这是必须提前算的内存 32G 起步。好处是数据自己掌控、延迟低、没有限流坏处是要跟着做版本升级还要监控节点的同步高度节点落后了你扫到的数据也就落后了。进阶方案自建节点 事件订阅插件。官方节点自带事件插件能力可以把合约事件直接推到消息队列Kafka 之类或者自建服务省掉了主动拉块和解析回执的步骤。优点是实时性最好、不占业务进程的 CPU缺点是配置相对复杂事件重复投递需要自己做幂等而且插件一旦配置错了排查成本很高。我一般推荐标准方案起步因为可控性最好出问题能一眼看到原始数据。业务量上来之后再考虑加事件插件做双通道。存储选型上流水表建议用 PostgreSQL 而不是 MySQL。原因不是性能而是NUMERIC(38,0)这种大整数类型和部分唯一索引、ON CONFLICT DO NOTHING的语义在 PostgreSQL 上写起来更顺手。链上金额动辄十几位用BIGINT存储最小单位对 USDT 就是 6 位小数的整数值最大到 9.2e18理论上够用但NUMERIC(38,0)更保险也方便以后接 18 位精度的代币。绝对不要用浮点数存金额这个底线不能破。2. 区块监听的核心细节与实操要点2.1 区块与交易回执的数据结构拆解监听的第一步是搞清楚你拿到的数据结构。很多人一开始会犯一个错从区块对象里直接找转账信息结果什么都找不到。因为区块里只有交易的原始数据raw_data真正的执行结果和事件日志存在交易回执transaction_info里需要按交易哈希单独获取。具体来说区块对象里每笔交易包含txID交易哈希、raw_data.contract合约调用参数、raw_data.timestamp时间戳、ret上链打包的结果等字段。注意这里的ret只代表交易是否被打包进区块不代表合约执行成功。真正代表执行结果的是回执里的receipt.result值为SUCCESS才算真正成功。回执里最关键的是log数组每个元素代表一次事件抛出包含address合约地址hex 格式、topics事件主题数组、data事件数据hex 格式。TRC20 的Transfer事件结构是固定的topics[0]是事件签名的哈希恒为ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef就是Transfer(address,address,uint256)的 Keccak-256 哈希topics[1]是 from 地址32 字节前 12 字节补零topics[2]是 to 地址同样格式data是金额uint256hex。这里有个很容易踩的坑topics[1]和topics[2]是 32 字节而 TRON 地址的 hex 形式是 21 字节41开头所以你只能取后 40 个字符再拼上41。而data字段拿到的金额是最小单位对 USDT-TRC20 来说精度是 6也就是1000000代表1 USDT换算时不能忘。还有个细节一笔交易里可能有多个log比如某些聚合合约一次调用会触发多笔转账。如果你只取第一个log就会漏掉后面的。业务上必须遍历整个log数组并且用一个自增序号标记每个log的位置作为幂等键的一部分。2.2 增量扫描与断点续传的实现扫描器最核心的机制是游标。你不能每次都从最新块开始扫也不能每次都从第 1 块开始扫必须在数据库里持久化一个已处理到的高度每次启动从游标的下一个块开始。游标的更新有个铁律先处理完再提交游标且两者在同一事务内。如果你先把游标推进了再去写流水表中间进程被 kill 就会永久漏块。反过来如果你先写流水表再推进游标中间挂了会因为唯一索引冲突导致重复处理但重复是可以用ON CONFLICT DO NOTHING兜住的漏块则无法自动恢复。所以宁可重复不可漏块。下面是我常用的扫描循环骨架import time import logging from tronpy import Tron from tronpy.providers import HTTPProvider client Tron(HTTPProvider(endpoint_urihttp://127.0.0.1:8090)) TRANSFER_TOPIC ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef def scan_loop(start_height: int, tip_height: int, step: int 20): cursor start_height while cursor tip_height: end min(cursor step - 1, tip_height) for height in range(cursor, end 1): process_block(height) # 内部完成解析 入库 游标推进 cursor end 1 time.sleep(0.2) # 别把节点打满step这个参数是批处理窗口。设太小请求次数多效率低设太大单次失败回滚的成本高而且窗口内的块数据你要一次存在内存里。我实测下来20 到 50比较合适具体看单块里的交易量。关于节点返回的块高度最新块和固化块是两个不同的概念。最新块可能随时被回滚固化块才被认为不可逆。扫描器的游标推进到最新块 - 20左右比较安全剩下的 20 个块留给重组校验环节。这样即使中途发生链上重组游标也不会跨过去。2.3 地址匹配从全量遍历到索引化监听所有转账日志只关心属于自己平台的地址——这是最朴素的做法也是最容易把自己 CPU 打满的做法。USDT-TRC20 的日转账量是百万级别的你要是每笔都做一次数据库查询判断这个 to 地址是不是我的很快就撑不住。我推荐内存地址集合方案启动时把所有收款地址加载进一个set十万级地址也就几十 MB 内存扫描时先做内存判断命中之后再走数据库。地址格式统一成 base58 形式做 key避免 hex 和 base58 混用导致的匹配失败。内存集合必须支持热更新。新用户下单分配地址时通过消息队列或者定时刷新比如每 10 秒拉一次增量把新地址塞进集合。这里有个时序问题要注意地址必须在订单创建之前就进入监听集合。如果你先建订单再注册地址中间那几秒用户刚好转账这笔就会被漏掉。正确的顺序是申请地址 → 注册进监听集合 → 写入数据库 → 返回给用户。再说说地址形态的选择。三种主流方案各有取舍方案优点缺点适用场景单地址 memo 备注无需管理海量地址归集成本低依赖用户正确填写备注漏填就要人工处理大额、低频、有客服介入的业务每单独立地址无需备注用户体验好天然支持并发地址数量膨胀归集成本高需要地址池管理中小额、高频、自动化程度高的业务固定地址池轮转地址数量可控归集批量大同一地址可能并发多单需要靠金额时间窗匹配中等规模业务memo 方案有个坑必须提前说备注内容是用户手动填的会出现大小写不一致、多了空格、少了几位、干脆没填的情况。解析时必须做strip()和规范化处理而且不能因为备注格式错误就丢弃这笔流水——钱是真到了你得先落库再走人工匹配流程。我见过有团队直接把备注不匹配的流水丢了后面用户来投诉翻链上记录才补回来非常被动。2.4 链上重组与假到账的防御TRON 用的是 DPoS 共识出块由超级代表轮值完成理论上也存在短时分叉和重组的可能。重组发生时你之前看到的那笔交易可能从主链上消失换到另一条分支上交易哈希可能不变因为交易内容没变但所在块高度会变甚至可能彻底消失。防御手段有两个层次。第一层是确认数门槛这个在下一节细讲。第二层是重组检测对最近 N 个块定期重新拉取一次比对本地区块哈希记录。如果你之前记录的块 A 的哈希是 X重新拉取发现变成了 Y那说明发生了重组A 块里的所有流水都要标记为待复核不能直接推进订单。具体实现我会额外建一张block_cursor表记录每个高度对应的块哈希CREATE TABLE block_cursor ( height BIGINT PRIMARY KEY, block_hash VARCHAR(72) NOT NULL, parent_hash VARCHAR(72) NOT NULL, scanned_at TIMESTAMPTZ NOT NULL DEFAULT now() );每次扫描时先查这个高度有没有记录有的话比对哈希。不一致就触发回溯把该高度及之后的所有流水状态打回PENDING游标退回该高度减一重新扫一遍。这个逻辑平时不触发但一旦触发就是救命的。另外一个常被忽略的点是parent_hash校验。连续两个块之间后一个块的父哈希必须等于前一个块的哈希否则说明你中间漏块了或者节点返回的数据有问题。这个校验几乎零成本但能抓住绝大多数数据完整性问题。3. 交易确认与状态机的推进逻辑3.1 从广播到最终确认的完整生命周期一笔 TRC20 转账从用户点确认到你觉得可以安心发货中间经历的状态比大多数人想的要多。把它们完整列出来有助于你设计一个不混乱的状态机。用户钱包签名后把交易广播到网络交易进入待打包队列。这个阶段交易只存在于节点内存里你在链上查不到交易哈希能查到但状态是未确认。约 3 秒内某个超级代表把它打包进一个新区块此时交易有了块高度回执可查但receipt.result可能是SUCCESS也可能是REVERT比如用户能量不足、合约校验失败。打包成功之后块高度会随着新块产生不断被推深。推到约 19 个块时网络认为它进入了固化状态此时基本不可能被回滚。这个过程在 TRON 上大概需要 57 秒。再往后就是你的系统内部处理落库、匹配订单、推进状态、触发回调。这部分耗时完全取决于你的架构可能几十毫秒也可能因为重试拖到几小时。设计状态机时必须把链上状态和业务状态分开。链上状态只有三种PENDING已广播未打包、SUCCESS执行成功、FAILED执行失败。业务状态则丰富得多WAITING_PAY等待支付、PARTIAL部分到账、CONFIRMING确认中、PAID已支付、OVERPAID超额支付、EXPIRED已过期、REFUNDING退款中。两套状态用一个字段混着存早晚会出乱子。3.2 确认数阈值到底该定多少这是被问得最多的问题也是最多人凭感觉拍脑袋的地方。我给出一个可以直接抄的结论TRC20 收款场景确认数取 19 到 20 个块折算时间 60 秒左右是性价比最高的选择。理由是这样的TRON 的 DPoS 共识里27 个超级代表轮流出块理论上超过 2/3也就是 19 个代表确认的块就不可回滚。所以 19 是一个有共识依据的数字不是随便定的。很多钱包和网关默认也是这个值。但不可回滚和业务上敢不敢认是两回事。你得按业务风险分级业务类型建议确认数折算时间理由虚拟商品、小额充值1 到 33 到 10 秒单笔损失可控体验优先实物电商、中等金额19 到 20约 60 秒共识安全边界风险与体验平衡大额、可退款业务30 以上90 秒以上宁可慢不可错涉及二次分发的场景必须固化块约 60 秒分发出去就收不回来了有个经验很多人不知道判断固化这件事不要自己数块高直接用节点的固化块高度接口。节点会返回一个solid_block_number比它小的块就是网络公认固化的。这比自己算 19 个块准得多因为它反映的是真实的共识进度。如果节点不支持这个接口那就退而求其次用最新块 - 20作为近似。另外强烈建议加一道金额维度的二次校验。比如订单金额是 500 USDT确认数达到 1 就先给用户一个已到账处理中的提示达到 19 再真正发货。这样用户不用干等一分钟你的风险也没有增加。这个体验优化很值得做。3.3 状态机推进的幂等设计状态推进最容易出的事故是重复推进和乱序推进。重复推进会导致回调被触发两次商户重复发货乱序推进会让订单从已支付退回确认中数据直接乱掉。幂等的根基在数据库约束。流水表必须有唯一键我一般用(tx_id, log_index)联合唯一CREATE TABLE chain_transfer ( id BIGSERIAL PRIMARY KEY, tx_id VARCHAR(64) NOT NULL, log_index INT NOT NULL, block_height BIGINT NOT NULL, block_hash VARCHAR(72) NOT NULL, contract VARCHAR(42) NOT NULL, from_addr VARCHAR(42) NOT NULL, to_addr VARCHAR(42) NOT NULL, amount_raw NUMERIC(38,0) NOT NULL, decimals SMALLINT NOT NULL DEFAULT 6, order_no VARCHAR(64), match_status SMALLINT NOT NULL DEFAULT 0, confirmations INT NOT NULL DEFAULT 0, created_at TIMESTAMPTZ NOT NULL DEFAULT now(), UNIQUE (tx_id, log_index) ); CREATE INDEX idx_to_addr_amount ON chain_transfer (to_addr, amount_raw, created_at); CREATE INDEX idx_order_no ON chain_transfer (order_no);写入时统一用INSERT ... ON CONFLICT (tx_id, log_index) DO NOTHING返回值判断是否真的插入了。只有插入成功的那一次才继续走后续的匹配和推进逻辑。这一招能吃掉 90% 的重复问题。状态推进则用带条件的 UPDATE而不是先查再改UPDATE pay_order SET status 3, paid_at now(), tx_id $1 WHERE order_no $2 AND status IN (0, 1) -- 只允许从 待支付/确认中 推进 AND amount_raw $3 -- 金额必须精确匹配 RETURNING order_no;有返回行才说明状态真的推进了才触发回调。没有返回行说明要么已经推进过要么金额对不上两种情况都不该重复通知。这种写法在高并发下是安全的因为它把判断和修改压成了一步原子操作。金额匹配这里要特别小心。必须用最小单位的整数比较绝不能用浮点数。用户付 10 USDT链上给的是10000000你用float相除再和10.0比较会碰上9.999999999这种浮点误差直接判定不匹配。统一成数据库存整数、比较用整数、展示时再除以 10 的 decimals 次方这条规则我在所有项目里都坚持。4. 回调机制与可靠性保障4.1 回调协议的设计要点回调是这套系统里最容易出问题的环节因为它跨越了两个不受你控制的系统。设计时要把对方可能不可靠当成默认前提而不是例外情况。协议层面建议至少包含这几个字段order_no商户订单号、tx_id交易哈希、amount金额字符串形式的整数最小单位、currency币种标识、confirmed_at确认时间、status最终状态、timestamp签名时间戳、nonce随机串。金额用字符串传输避免 JSON 浮点精度丢失这是个必须养成的习惯。HTTP 语义上POST JSON是最省事的组合。要求对方返回 HTTP 200 且响应体包含约定的成功标识才算投递成功。不要用连接成功作为成功判据很多服务端返回 500 但 TCP 是通的你要是不看状态码会以为投递成功了这是非常隐蔽的坑。超时设置要短我一般设5 秒。回调接口正常响应应该在几百毫秒内超过 5 秒还没返回说明对方系统大概率有问题继续等只是浪费你的重试窗口。设短超时 多次重试总体成功率远高于长超时 少重试。4.2 签名验签与防重放回调如果不签名任何人抓到你的接口格式都能伪造一条已支付通知这在金融场景里是致命的。签名方案我推荐 HMAC-SHA256简单够用。规则是这样的把时间戳和请求体按固定顺序拼接用双方共享的密钥做 HMAC结果放在请求头里。请求体要做规范化序列化key 排序、无多余空格否则对方按自己的 JSON 序列化方式算出来的签名和你的对不上。这个坑我踩过排查了两个小时才发现是字段顺序问题。import hmac, hashlib, json, time def build_signature(payload: dict, secret: str) - str: ts str(int(time.time() * 1000)) body json.dumps(payload, separators(,, :), sort_keysTrue, ensure_asciiFalse) msg f{ts}.{body}.encode(utf-8) sig hmac.new(secret.encode(utf-8), msg, hashlib.sha256).hexdigest() return ft{ts},v1{sig}验签这一侧要额外做两件事。一是时间窗校验签名里的时间戳和当前时间差超过 5 分钟就拒绝防止有人拿旧请求反复重放。二是 nonce 去重把用过的 nonce 存进一个有 TTL 的集合比如 Redis 里SETNX加 10 分钟过期重复的直接丢弃。两道加起来重放攻击基本没戏。对商户侧还要提醒一句验签通过不等于可信还要校验订单金额和状态。我见过有商户接完回调只要验签过就发货结果被自己的测试环境重放过一次旧回调白发了货。业务校验这一步不能省。4.3 重试策略与退避算法回调失败是常态所以重试策略决定了系统的实际可靠性。我用的方案是指数退避 上限封顶 最大次数限制。具体参数第 1 次失败后等 5 秒第 2 次等 10 秒第 3 次等 20 秒第 4 次等 40 秒以此类推单次间隔封顶 30 分钟总共重试8 到 10 次总跨度约 6 到 10 小时。这个窗口对绝大多数商户够用了——对方系统半夜挂了第二天早上恢复你的重试还在跑能自动补上。def next_delay(attempt: int) - int: base 5 cap 1800 delay min(base * (2 ** attempt), cap) jitter random.randint(0, max(1, delay // 5)) # 加抖动避免同时打过去 return delay jitter那个jitter抖动很容易被忽略但非常关键。假设你有一批订单在同一秒推给同一个商户对方服务挂了所有重试任务会在同一时刻齐刷刷打过去形成尖峰对方刚恢复又被你打挂形成雪崩。加个 20% 的随机抖动就能把请求摊平。重试任务本身要落库不能只放内存队列。我见过太多团队用进程内的定时器做重试服务一重启待重试的任务全丢了然后就只能人工补发。用一张notify_task表记录任务状态待发送、成功、失败、已放弃配合一个扫描待办的后台进程才是可靠的。4.4 对账机制与人工兜底自动化做到 99% 也不够剩下那 1% 必须有兜底路径。对账体系我一般做三层。实时层每次流水落库后立刻尝试匹配订单命中就走推进流程。这一层处理 95% 以上的正常单。准实时层每 5 分钟跑一次未匹配流水 vs 未支付订单的配对任务规则是地址相同 金额相同 时间在订单有效期内。这一层能救回备注没填、消息丢了、顺序乱了的单。日终层每天固定时间把当天所有已支付订单的金额汇总和链上该地址当天的入账总额做比对。差额不为零就报警。这一层看着笨但它是唯一能发现系统性错误的机制——比如你的解析逻辑把某个代币的精度搞错了实时层和准实时层都会一致地错下去只有整体对账能发现。人工兜底界面必须做而且要好用。运营需要能按地址、按金额、按时间范围搜到链上流水能手动关联到订单能强制触发回调能标记已人工处理。这个界面不用做得漂亮但要能三秒内搜到结果。我经历过一次线上事故因为没有这个界面排查用了整整一天事后第一件事就是把它补上。5. 常见问题与排查技巧实录5.1 高频问题速查表下面这张表是我这些年攒下来的遇到问题时按顺序对一遍八成能定位现象最可能的原因排查动作链上有记录后台无流水扫描器停了 / 游标卡住 / 节点不同步查游标高度和节点最新高度差差值持续增大就是停了流水有了订单没变地址或金额没匹配上 / 订单已过期拿流水去比对订单的地址和金额注意最小单位换算订单变了商户没收到回调失败 / 签名验签不过 / 商户侧异常查通知任务表的重试记录和响应码同一笔通知被处理两次幂等缺失 / 商户侧未做去重查唯一键是否生效要求商户按订单号去重金额显示差 10 的 N 次方精度搞错核对代币的 decimalsUSDT 是 6不是 18交易成功但没解析出日志receipt.result不是 SUCCESS / 合约地址不对拉完整回执看 result 字段和 log 数组收到陌生代币的入账用户打了错误币种 / 同名假币严格校验合约地址白名单符号相同不代表同一个币扫描器 CPU 打满全量遍历地址做数据库查询改成内存地址集合预筛这里面我想重点说同名假币这一条。TRC20 是个开放标准任何人都能部署一个叫USDT的合约符号、名称、精度全部照抄唯独合约地址不同。如果你的匹配逻辑只按符号判断用户打过来一堆毫无价值的假币你的系统会当成真 USDT 给用户发货。防御方法很简单也很有效维护一个合约地址白名单只有白名单里的合约地址的转账才进入业务流程其他的一律落异常流水表只做记录不做处理。这个白名单必须是硬编码或者数据库配置的绝不能从链上动态读取。5.2 几个只有上线才会遇到的坑坑一能量不足导致的转账失败。TRC20 转账需要消耗能量用户钱包里如果只有 USDT 没有 TRX交易会执行失败。失败交易同样上链、同样有回执但receipt.result是REVERT。如果你的逻辑只看交易是否被打包就会把失败交易当成成功。必须检查receipt.result SUCCESS这一条不能省。踩过这个坑之后我在所有解析逻辑里都加了这个判断并且把失败交易单独存一张表方便用户来问的时候快速回答。坑二批量转账时的日志序号。有些归集脚本会用一次多签或者批量合约调用转多笔一笔交易里产生十几个Transfer日志。如果你只用tx_id做幂等键后面的日志会全部被ON CONFLICT DO NOTHING吃掉。必须用(tx_id, log_index)。同理回调也要考虑这种情况——一笔交易可能对应多个订单别默认一对一。坑三时间戳的时区问题。链上时间戳是毫秒级的 UTC 时间你的数据库如果存的是本地时间做时间窗匹配时会整体偏移 8 小时导致大量明明地址金额都对但就是匹配不上的诡异现象。统一用 UTC 存储展示层再转这个规矩要从建表那天就定下来。坑四节点落后导致的数据回退。自建节点有时候会因为磁盘 IO 或者网络问题落后主网你扫到的最新块其实是几分钟前的。这时候如果游标已经推到了更高的高度就会出现游标比节点最新块还高的情况扫描直接空转。要在扫描循环里加一道保护如果节点最新块高度小于游标说明节点异常暂停扫描并告警等节点追上再继续。5.3 监控指标该埋哪些系统做完能跑只是起点能不能在出问题时第一时间发现靠的是监控。我必埋的指标有六个游标滞后量节点最新块高度 - 本地游标高度。正常应该在 20 以内波动持续增大就是扫描器出问题了。这个指标设两个阈值超过 100 告警超过 500 严重告警。扫描吞吐每分钟处理的块数。突然掉零或者掉一半说明有阻塞。未匹配流水数落库但没关联到订单的流水总量。正常应该是个位数持续增长说明匹配规则有问题。待发通知积压量待重试的回调任务数。持续增长说明商户侧有问题该联系对方了。回调成功率按小时统计。低于 95% 就该看一眼。确认中订单滞留数状态卡在确认中超过 10 分钟的订单数。正常应该是零有就说明推进器卡住了。监控之外我还会做一个健康检查接口返回当前游标高度、节点高度、滞后量、各状态订单数。运维和运营都能调省掉大量现在系统正常吗的沟通成本。6. 我个人在这套系统上的几点体会做了这么多版收款系统最大的感受是这套系统的难点从来不在技术而在边界情况。正常流程写起来一天就能跑通真正花时间的是那些用户付了钱但备注填错商户服务端半夜重启节点突然落后三分钟的场景。我现在的习惯是每加一个功能先问自己三个问题这一步失败了会怎样重复执行会怎样顺序颠倒了会怎样想清楚这三个代码写出来才踏实。另一个体会是别过度追求实时。很多团队一开始追求3 秒内到账提示为了这个目标把确认数降到 1结果遇到一次重组就要人工处理几十单得不偿失。分层提示1 个确认给处理中、19 个确认给已完成这个方案既照顾了体验又守住了风险是我目前最推荐的折中。最后分享一个实用的小设计给每条流水都存一份原始 JSON 快照单独字段或者单独表都行。解析逻辑改了、字段映射错了、需要重新跑历史数据的时候有原始快照就能一键重放没有就只能重新拉链上数据。这个字段占不了多少空间但它在排查问题时的价值远超那点存储成本。我现在的做法是所有链上数据先原样落原始表解析结果落业务表两张表通过主键关联任何时候都能追溯到最原始的输入。
