Holdfast：用Gemma解释Webhook故障，代码做安全兜底

Webhook 丢消息这件事，做过集成的人多少都遇过。Stripe 或 GitHub 把事件发过来，如果应用当时宕机、响应慢，或者刚好某个字段被改了名，这条消息往往就悄无声息地没了。等发现的时候，通常是客户两天后打来电话问：为什么有三笔付款没到账？

开发者 Tanay 在 Hacktoberfest 开源 AI 挑战赛中提交的 Holdfast，想解决的正是这个问题。他把消息队列里那条朴素但绝对的原则搬到了 Webhook 上——消息在被安全存储之前，不算确认收到。

核心设计：代码决定，模型解释

Holdfast 位于服务提供方（Stripe、GitHub）和应用之间，做五件事：先落盘再应答、校验签名并隔离伪造或重放的消息、耐心重试或安全搁置、用两种口吻解释出了什么问题、以及安全地重发消息而不是重复发送。

这个项目最值得关注的设计约束是一句话：模型永远不决定消息的去向。重试、搁置、去重、重发全部是普通的、有测试覆盖的 Go 代码。Gemma 3 4B 只负责两件事：从固定的八种原因里选一个（受 JSON schema 约束），以及撰写解释文案。写完之后，代码会逐字检查。

面向客户的说明如果包含「HTTP」「payload」「endpoint」这类术语，或者承诺了没人执行的动作，就会被拒绝并替换为内置规则的措辞。标题永远由代码生成。这条边界划得很清楚，也是在给所有想把 LLM 塞进关键链路的开发者提了个醒：让模型做它擅长的事，别让它做决定。

JSON schema 约束指的是在调用大语言模型时，随请求传入一份结构化的输出规范（如字段名、类型、枚举取值范围、长度上限），要求模型只能产出符合该规范的 JSON。它把「自由文本生成」变成「受限填空」，让下游代码可以安全地解析和校验。与之配套的通常是逐字后置校验：模型输出先经过 schema 解析，再由业务代码检查语义（例如是否出现禁用词、是否承诺了未执行的动作），任一环节不通过就回退到规则引擎生成的文案。这种「schema + 代码检查」的双层结构，是把 LLM 放进关键链路时的常见做法，因为模型本身不保证遵守约束，真正的兜底必须由确定性代码完成。

一个把作者教明白的 Bug

第一版在「字段改名」场景下，Gemma 原因判断对了，但给客户的摘要写着「通知已被安全保存并正在审核」。实际上没有任何人在审核。更糟的是，给开发者的说明写反了方向——说应用「现在需要 customer_id」，可事实是 Stripe 变了，应用没变。

作者的处理方式不是换个更好的 prompt，而是把更多工作挪进代码：

• 由代码识别改名。 一个 shape-diff 遍历两个 JSON 体，发现 data.object.customer_id 消失、data.object.customer.id 出现，这就是一次带方向的改名。模型收到的是「发送方现在发 X 而不是 Y；应用没有变化」，而不是一串原始的路径列表。
• 摘要必须有固定结构：这笔付款发生了什么（谁、多少钱）、用日常语言说明原因、接下来会怎样。
• Promise 检查拒绝「正在审核」「将会重发」「我们团队正在…」这类表述。
• 开发者修复建议必须指出移动了的字段，否则回退到规则生成的版本。

修复后同一个场景的输出：「发送方现在使用 data.object.customer.id 而不是 data.object.customer_id。请修改应用以接受 data.object.customer.id。」方向对了，也没有虚构动作。

模型选型靠测量，不靠感觉

作者对 Gemma 3 1B 和 4B 做了实测对比。1B 在改名场景下写出「应用将重发被搁置的事件」这类承诺，还让发送方去改——两个错误都被现在的检查拦下并回退到规则答案。4B 在笔记本 GPU 上约 16 秒，能准确说出客户、金额和具体字段。

部署到 Render 的两核 CPU 上，质量相同，但一次解释要 92 秒；做了一轮优化后，两次线上实测分别是 48 秒和 83 秒。这也解释了产品层面的一个设计：页面先秒出内置规则的答案，等 Gemma 写好再替换上去。延迟没有消失，只是被挡住了。

Ollama 是一个本地运行开源权重模型的工具，默认在 11434 端口提供 HTTP 接口，常被用来在自有服务器上跑 Gemma、Llama 等模型。llama.cpp 则是它底层常用的推理引擎，负责加载权重、管理 KV 缓存和上下文内存。文中提到的 LLAMA_ARG_* 环境变量用于限制上下文长度、批大小和缓存大小，防止引擎按宿主机资源而非容器配额来分配内存。在容器化部署中，llama.cpp 如果不显式设限，可能读取到宿主机的总内存和核数，从而保留过大的 prompt 缓存，最终触发 OOM。理解这一层有助于判断「本地小模型」在云上的真实成本与稳定性边界。

上线当天踩的三个坑

部署头一天，所有 Gemma 调用都以 connection refused 失败，指向 holdfast-ollama:10000。Ollama 在 11434 端口运行正常，但 Render 的服务间地址用了默认端口。规则引擎自动接管，站点全程可用——这正是设计好的降级路径。在 render.yaml 里加一行 PORT=11434 就修好了。

同一天下午还有两个问题。一是内存溢出：容器里的 llama.cpp 看到的是整台宿主机（60GB+ 内存、16 核），而不是 4GB 的套餐配额，于是保留了一个可能涨到 8GB 的 prompt 缓存和一份重新打包的权重副本。三个 LLAMA_ARG_* 设置把它压回了 4GB 以内。

二是回答失控。有些诊断输出几百个 token 还闭合不了 JSON。作者在笔记本 CPU 上用 Render 的完全相同设置复现：5 次里有 3 次，Gemma 试图用弯引号（”}）结束字符串，JSON 把它当普通字符，于是模型停不下来、开始自我重复。另一个诱因是 Go 按字母序写 JSON 字段（cause、fix、summary），导致模型把整段故事塞进开发者说明，只给店主留了一行。修复包括每个字段加长度上限、代码在游离的弯引号处截断、检查摘要像句子一样结束、以及把字段顺序调整为 cause、summary、fix。修复后从 5 次里 2 次可用变成 4 次全部可用，耗时 16–40 秒。

这三次事故有个共同点：无论 Gemma 出什么问题，访客拿到的都是规则引擎给出的正确、平实的答案。Gemma 让解释更好，但它从来不是保住一笔付款的那一环。

安全细节没有省

Live 模式允许用户填写 Holdfast 转发到的 URL，这天然带来 SSRF 风险——不加防护，任何人都能把目标指向 holdfast-ollama:11434 或云元数据地址，然后在事件页面上读到回复。Holdfast 在保存时检查一次目标地址，在每次拨号时再检查一次，所以一个后来才解析到私有 IP 的主机名依然会被拒绝。另外，提供方至少投递一次，重发计划按到达顺序每个事件只发一次，已投递过的、签名失败的都不会被重发。

**SSRF（服务端请求伪造）**是指攻击者诱导服务器向内部地址发起请求，从而访问本不该暴露的服务，例如同一私有网络内的模型服务 holdfast-ollama:11434 或云厂商的元数据地址 169.254.169.254。仅校验用户提交的 URL 字符串不够，因为域名可能在保存后才解析到私有 IP，所以需要在真正拨号时再次检查解析结果。DNS 重绑定正是利用这种时间差：第一次解析返回公网地址通过校验，之后改解析到内网地址。双重校验加禁用私有网段，是转发类服务的基本防护。

第一个用户和它的诚实

作者的第一个用户是他自己的小应用 Tasklet，一个把 GitHub issue 变成待办的小工具。实测流程：连接仓库后 GitHub 测试 ping 在 0.27 秒内被确认；打开 issue #1，4 秒内待办出现在 Tasklet；把 Tasklet 切到维护模式（返回 503）后打开 issue #2，Holdfast 在 34 秒内重试 5 次（分别等待 2、4、8、16 秒）后安全搁置，Gemma 用 40 秒解释了原因；关掉维护模式后点「重发全部搁置消息」，issue #2 的待办出现了一次，什么都没丢。

作者明确写了「没有任何人付钱」，第一个用户就是他自己和自己的应用，所以不宣称有销售。他还列了没做完的部分：Stripe Connect 需要平台账号，他没有，所以 Stripe 只能手动配置——粘贴一个地址到 Stripe 的 Webhook 设置，再把签名密钥填进 Holdfast，网站上也照实说明了。

开源模型在这里意味着什么

支付 Webhook 里带着客户姓名、金额和地址。用同一私有网络内的开放权重模型，这些数据不会流向任何 AI 公司，自由职业者可以对客户如实这么说。一家小店一天可能产生几百个事件，一台服务器上的一个小模型能用固定成本解释每一次失败。更实际的是，当 Gemma 承诺了一个不存在的人工审核时，作者能看清它到底收到了什么、改掉代码告诉它的内容、用 JSON schema 约束输出——这是工程，不是等厂商更新模型。

模型只是一个配置项（HF_MODEL）。选 1B 还是 4B，靠的是实测数据。

如果你也在维护几个小客户的集成，这个项目提供的思路值得借鉴：把 LLM 放在解释层，把决定权留在代码里，再为模型失效的那一天准备好一条可用的退路。