hoelee-blog/src/content/posts/zh/architecting-sea-payment-and-offline-licensing-pipelines.md at 403d4c0d9fa4c7246cc92e3b5d06857086809388

hoelee/hoelee-blog

0 Fork 0

Files

T

hoelee 403d4c0d9f

Deploy / build (push) Successful in 29s

Details

fix(posts): consultant final review — release ready (v1.2)

02 comfyui (EN+ZH)
- unify the asset numbers end to end: 108 cover pairs = 216 banner+OG
  assets. The intro, the frontmatter metric, the description and the
  `ws.close()` comment all still carried the old "89", which contradicted
  the 216/25.9-min figure in the result section (consultant finding).
- state the timing scope explicitly: end-to-end per slug, diffusion plus
  the Pillow clearance audit and the two-size WebP encode.
- disclose the limit of the mtime evidence: mtime keeps only the last
  write, so gate-rejected re-queues from an earlier pass do not lengthen
  the measured window.

01 payments (EN+ZH)
- the idempotency comment now names the 72h bank reconciliation window,
  which is the boundary that makes EXPIRED a legitimate fulfilment entry
  point (line count unchanged at 27).

2026-10-29 14:29:03 +08:00

14 KiB

Raw Blame History

ogImage, banner, title, description, pubDate, category, blueprint, blueprintLayer, tags, draft, summary, dynamicCta

ogImage

banner

title

description

pubDate

东南亚区域商业交付的现实断层

在面向东南亚区域（尤其是马来西亚、新加坡和印尼）的企业客户与独立专业人员交付桌面客户端工具时，直接套用欧美的常规 SaaS 支付架构往往会在上线第一天遭遇滑铁卢。

如果在结账页面上直接套用常规的 Stripe Elements 或 PayPal，系统会立即撞上两堵现实高墙：

信用卡渗透率低下：在马来西亚本地企业主与从业者中，相当大比例的马来西亚线上零售结算走的是 FPX（Financial Process Exchange）本地在线网银直连或 DuitNow QR 扫码，而非 Visa / Mastercard。只渲染信用卡表单的结账页不会慢慢变差——它在第一屏就直接失效。
离线桌面软件的盗版风险：如果是纯离线运行的高性能工具（例如批量视频转码器），二进制包一旦交付，如果缺乏基于物理硬件的授权签名机制，极易在团队内部被无限制复制扩散。

为了解决一款商业级媒体转码桌面软件的商业变现与履约闭环，我主导设计并落地了一套全自动化的计费与授权分发架构。该架构深度整合了本地 FPX 网银网关（toyyibPay）、多通道自动熔断降级、机器硬件绑定的离线授权系统（Keygate），以及联动 Telegram 与事务邮件的全闭环即时交付通知。

支付结算与授权履约状态机

在生产级支付流水线中，绝对不能依赖用户的浏览器重定向（Redirect）来确认支付成功。用户可能会在手机网银跳转途中手抖关闭浏览器，银行 App 的返回通知可能被拦截，甚至本地银行网关可能在深夜对同一笔交易重放多次 Webhook。

整个结算引擎由严格的有限状态机（FSM）驱动，确保每一次状态扭转具有原子性与幂等性：

[用户发起结账]
        │
        ▼ (创建账单)
   [PENDING] ─── (超时未付 / 用户取消) ───► [EXPIRED]
        │
        ├── (接收 Webhook: 校验数据签名与金额)
        ▼
   [PROCESSING] ─── (获取行级排他锁 → 提交事务 → 入队)
        │
        ├── (调用 Keygate API 签发专属机器码 License)
        ▼
   [FULFILLED] ───► (通过邮件与 Telegram 实时推送下载包与密钥)
        │
        └── (下游授权 API 偶发超时) ───► [RETRY_QUEUE] (告警并进入死信重试)

1. Webhook 签名与幂等性校验

当 toyyibPay 的异步回调到达端点时，控制器首先在事务内执行幂等拦截与金额一致性校验：

public function callback(): ResponseInterface
{
    $refNo   = (string) $this->request->getPost('refno');
    $status  = (string) $this->request->getPost('status');   // 1=成功 2=处理中 3=失败
    $billId  = (string) $this->request->getPost('billcode');
    $orderId = (string) $this->request->getPost('order_id');
    $amount  = (string) $this->request->getPost('amount');
    $hash    = (string) $this->request->getPost('hash');

    // 1. 网关校验和。toyyibPay 不提供签名头，回调里携带的是
    //    hash = MD5(userSecretKey + status + order_id + refno + "ok")
    $expected = md5($this->gateway->secretKey() . $status . $orderId . $refNo . 'ok');
    if (!hash_equals($expected, $hash)) {
        $this->logger->warning('toyyibpay.callback.bad_hash', ['bill' => $billId]);
        return $this->response->setStatusCode(401)->setBody('INVALID_HASH');
    }

    // 非成功状态一律不改动订单：2=处理中，3=失败
    if ($status !== '1') {
        return $this->response->setStatusCode(200)->setBody('IGNORED');
    }

    // 2. 一个事务、一把行级排他锁：读取与状态扭转属于同一个临界区，
    //    因此不存在 TOCTOU 竞态窗口。
    $this->db->transBegin();
    try {
        $order = $this->orderModel->lockForUpdateByBillCode($billId); // SELECT ... FOR UPDATE
        if (!$order) {
            $this->db->transRollback();
            return $this->response->setStatusCode(404)->setBody('UNKNOWN_BILL');
        }
        // 只有两种状态可以进入履约：全新的 PENDING，或 72 小时对账窗口内银行延迟结算的 EXPIRED。
        // 其余状态（PROCESSING 已占一个队列位、FULFILLED 已完成、RETRY_QUEUE 在重试）
        // 都属于重放，必须在此吸收——只判 'FULFILLED' 会留下整个 PROCESSING 窗口，
        // 让第二次推送穿透幂等检查。
        if (!in_array($order['status'], ['PENDING', 'EXPIRED'], true)) {
            $this->db->transCommit();
            return $this->response->setStatusCode(200)->setBody('OK_IDEMPOTENT');
        }

        // 3. 金额永不使用浮点比对，双方统一为整型分（cents）
        if ($this->toCents($amount) !== (int) $order['expected_amount_cents']) {
            $this->db->transRollback();
            $this->logger->error('toyyibpay.callback.amount_mismatch', [
                'bill' => $billId, 'got' => $amount,
                'expected_cents' => $order['expected_amount_cents'],
            ]);
            return $this->response->setStatusCode(409)->setBody('AMOUNT_MISMATCH');
        }

        $this->orderModel->updateStatus($order['id'], 'PROCESSING');
        $this->db->transCommit();
    } catch (Throwable $e) {
        $this->db->transRollback();
        throw $e;
    }

    // 4. 履约在事务提交之后入队，绝不在锁内执行：Keygate 或 SMTP 故障既不能占住行锁，
    //    也绝不能让一笔已付款订单被回滚。这才让 [PROCESSING] → [RETRY_QUEUE] 成为安全状态。
    $this->fulfillmentQueue->push($order['id']);

    return $this->response->setStatusCode(200)->setBody('OK');
}

/** "12.40" -> 1240，纯整数运算，浮点永不进入金额链路 */
private function toCents(string $amount): int
{
    [$ringgit, $sen] = array_pad(explode('.', trim($amount), 2), 2, '0');
    return ((int) $ringgit) * 100 + (int) str_pad(substr($sen, 0, 2), 2, '0');
}

校验和只能证明回调来自网关，不能证明回调确实到达。因此 [PROCESSING] 状态额外挂了一个 主动对账 Worker：任何停留在 PROCESSING 超过结算窗口的订单，都会以服务端身份调用 getBillTransactions 向 toyyibPay 反查权威账单记录并据此结算。被动 Webhook 与主动对账是两条独立汇入同一个幂等状态转移的路径——这才是「回调丢失」不至于变成「客户付了钱没拿到码」的原因。

2. 基于 Keygate 的硬件指纹绑定与非对称离线验活

订单扣款成功后，系统不会生成毫无约束的通用明文激活码，而是即时调用授权中心 API，为买家签发绑定其特定计算机硬件特征的专属 License：

授权码内部编码了功能等级（standard / pro / enterprise）、过期时间戳与特征权限集。
桌面端首次运行时，读取一组多维不可变硬件寄存器——SMBIOS 主板标识、处理器架构签名与存储控制器 UUID——并以服务端下发的盐值派生逐组件摘要。具体取哪些寄存器、盐值如何派生属于私有实现，本文有意不公开：公开它等于直接告诉逆向者该 Hook 哪几个系统调用。
Keygate 服务端使用 Ed25519 私钥 对逐组件摘要与授权元数据执行数字签名。
桌面客户端仅内置对应的 Ed25519 公钥。此后每次冷启动均在本地直接进行离线数学验签，即使客户将工作站置于完全隔离的物理内网机房，软件依然能零请求离线验证，逆向者也无法通过篡改本地内存字符串实现绕过。

逐组件摘要的存在，是为了让授权能扛住合法的硬件变更。 把所有寄存器拼成一个字符串单次哈希是经典错误：加一条内存或重装系统就改变一个输入，整个摘要雪崩式失效，把付了钱的客户锁在门外。正确做法是让签名负载分别携带各组件摘要，客户端按两级裁决：两项机身锚定件（SMBIOS 主板 UUID 与 CPU 架构签名）具决定权，其余辅助寄存器（存储控制器 UUID、网卡永久 MAC）只做仲裁。两项锚定件同时命中即无条件放行——重装系统或换硬盘只会改变辅助寄存器，属于合法升级。若其中一项锚定件已变（换主板或换 CPU），只要其余辅助摘要全部命中，授权依然放行：既让付费客户扛过硬件翻新，又不会把口子开大到足够把授权移植到一台无关的机器上。

一键极速直下与 CDN 动态容灾

在东南亚交付体积庞大的桌面安装包（通常包含数百兆的 FFmpeg 二进制依赖），另一个致命痛点是跨国跨境网络路由抖动。将包托管在遥远的欧美云厂商 S3 存储桶，经常会导致本地客户下载速度掉到几百 KB/s 甚至中途断流。

我构建了双层文件分发网络：

主通道极速直下：安装包托管于挂接在 Cloudflare 边缘反代之后的自建高带宽分发节点，开启边缘字节级缓存，买家支付完毕在结果页点击一次即可直连高速下载。
备用镜像动态容灾：当监控探测到主通道延迟毛刺或命中流量异常时，结账账单卡片下方会自动点亮经过身份鉴权的备用 Publitio CDN 镜像下载链接。

拒绝多层跳转诱导页，杜绝垃圾广告与冗长人机验证：一次支付成功，一键拿到经过数字签名的专属安装包。

🔍 查看多渠道履约通知调度逻辑（Python 关键片段，27 行）

def notify_fulfillment(order_id, customer_email, bill_code, license_key, download_url):
    """向内部运维群推送实时交易监控，并向客户发送双语交付确认函"""
    # 1. 内部 Telegram 运营频道实时秒级告警
    tg_payload = {
        "chat_id": OP_TELEGRAM_GROUP,
        "text": (
            f"💰 *新商业软件授权已履约*\n"
            f"账单单号: `{bill_code}`\n"
            f"买家邮箱: `{customer_email}`\n"
            f"授权密钥: `{license_key[:8]}...{license_key[-4:]}`\n"
            f"支付通道: toyyibPay (FPX 本地网银)"
        ),
        "parse_mode": "Markdown"
    }
    requests.post(f"https://api.telegram.org/bot{TG_TOKEN}/sendMessage", json=tg_payload, timeout=5)

    # 2. 事务邮件通道推送带有安全下载链接的正式交付清单
    send_smtp_transactional(
        to=customer_email,
        subject="您的软件授权激活码与安装包下载信息",
        body_template="fulfillment_v2",
        context={
            "license": license_key,
            "download": download_url,
            "support": "[email protected]"
        }
    )

东南亚区域部署的核心架构认知

为新兴市场搭建商业软件系统，必须对通用技术习惯进行本土化重构：

必须容忍异步结算延迟：马来西亚部分本地银行在深夜维护窗口（例如 Maybank2u 每日 00:00 结算周期）内，FPX 交易的 Webhook 回调可能会延迟 3 到 10 分钟。前端界面必须设计友好的轮询提示状态（PROCESSING_BANK_CONFIRMATION），切忌轻易将订单标为失败。
数据库排他锁是防重发的底线：银行回调在超时重试时极易形成瞬时并发，使用 SELECT ... FOR UPDATE 悲观锁保护订单状态，是防止重复签发许可证的绝对护城河。
交付流程必须做到“零跳转”：B2B 客户在看到支付绿标的瞬间就渴望拿到 .zip 或 .exe。每多一层外部跳转或落地页，客户的信任度就会指数级暴跌。

交付结果

该全自动计费与分发流水线投产后：

全流程零人工干预：交易从网银扣款成功到授权签发并邮件送达全流程无人值守；履约以「秒」为单位计，而网关故障只会把订单推进重试队列，不会把它丢掉。
杜绝私下窜码扩散：依托硬件级 Keygate 指纹绑定，彻底终结了盗版秘钥在多台设备上的随意复制。
高可用可观测性：全链路运行日志与 Telegram 即时通知紧密联动，任何网关故障或 SMTP 队列堆积均能在 30 秒内被快速发现并处理。

14 KiB Raw Blame History Unescape Escape