工作流跑了两次,工单建了两遍:Agent 的重试与幂等

上游重投、节点重试、人工重跑,一次客户反馈建了三张工单。真正管用的不是入口去重,而是从业务事实派生幂等键、只对超时和 5xx 重试,并把写操作拆成“待确认”和“确认后续跑”两段。

一条"客户在群里反馈问题"的自动化工作流:IM 回调进来 → 模型判断类型 → 建工单 → 发通知。测试阶段跑了二十遍都正常,上线第三天出了一次事故——同一份反馈建了三张工单,客服挨个去合并。

翻日志才看清链路:IM 平台的回调因为我们的响应超过 3 秒,重投了一次;n8n 里 HTTP 节点的重试又补了一次;中间还有一次超时其实请求已经成功,只是响应没回来。三次请求,同一件事。问题的本质是把"至少执行一次"当成了"恰好执行一次",而所有网络调用的默认语义都是前者。

一、重复从三个地方来

第一个是回调重投:上游平台等不到 200 就再发一次,间隔往往只有几秒,而我们的处理要跑模型,很容易超过它的超时阈值。第二个是工作流自身的重试策略:只要开了"失败重试",超时也会被算作失败,但超时的那次请求可能已经在服务端执行完了。第三个最容易被忽略——人工重跑。运维看到某条执行显示失败,点了"重新执行",而失败是因为最后一步通知超时,前面的建单早就成功了。

这三种来源在日志里长得几乎一样:同一个业务事件,多条执行记录,状态还不完全相同。所以"防重"不能放在入口做判断,必须放在写操作这一步。

二、先把响应和业务拆开

上面三个来源里,前两个都可以从根上缓解:让入口在超时预算内返回,把实际处理挪到异步。IM 平台一般给 3 秒,处理要跑模型,无论如何都超时。所以入口只做两件事——校验签名、把原始事件落库——然后立刻返回 200,后续步骤由队列消费。

from fastapi import FastAPI, Request, BackgroundTasks
import json, uuid, sqlite3

app = FastAPI()
Q = "work.sqlite3"

@app.post("/hook/im")
async def hook(req: Request):
    body = await req.body()                 # 先拿原始字节,避免解析失败丢事件
    ev = json.loads(body)
    if not verify_signature(req.headers, body):
        return {"code": 401}
    con = sqlite3.connect(Q)
    con.execute("INSERT OR IGNORE INTO events(id, payload, ts) VALUES(?,?,strftime('%s','now'))",
                (ev["event_id"], body.decode()))     # event_id 天然去重
    con.commit()
    return {"code": 0}                      # 200 立刻返回,处理交给 worker

INSERT OR IGNORE 配合主键 event_id,重投的同一条事件在入库这一步就被吃掉了,后面的重试、人工重跑都拿不到重复数据。这一步做掉之后,线上重复建单的次数下降了大概八成,剩下的两成来自响应已经回了但 worker 重跑。

顺带一个细节:先读原始字节再解析。我先写的是直接 await req.json(),有一次上游发了个不带 Content-Type 的请求,解析抛错,事件根本没落库,平台重投三次全丢。

三、幂等键:别用时间戳,用业务事实

我最初的想法是给每次执行生成一个 UUID 当去重键,结果毫无用处——三次执行三个 UUID,谁都不等于谁。幂等键必须从业务事实派生,同一件事无论来几次都算出同一个值:

import hashlib, sqlite3, json, time

DB = "idempotency.sqlite3"

def make_key(source: str, external_id: str, step: str) -> str:
    """同一上游事件 + 同一处理步骤 = 同一个键。"""
    raw = f"{source}|{external_id}|{step}"
    return hashlib.sha256(raw.encode()).hexdigest()[:32]

def run_once(key: str, fn, ttl_hours: int = 72):
    con = sqlite3.connect(DB)
    con.execute("""CREATE TABLE IF NOT EXISTS done(
        k TEXT PRIMARY KEY, result TEXT, ts REAL)""")
    row = con.execute("SELECT result FROM done WHERE k=?", (key,)).fetchone()
    if row:                                   # 已经做过,直接返回上次结果
        return json.loads(row[0])
    result = fn()                             # 真正调下游
    con.execute("INSERT OR REPLACE INTO done VALUES(?,?,?)",
                (key, json.dumps(result, ensure_ascii=False), time.time()))
    con.commit()
    return result

key = make_key("im", msg["message_id"], "create_ticket")
ticket = run_once(key, lambda: create_ticket(...))

这里的关键是 msg["message_id"]:上游保证同一条消息的 id 不变,重投时也带着同一个 id。如果上游连这个都不给(有些平台只有时间戳),退而求其次用"会话 id + 内容哈希",虽然可能误合并,但比重复建单可控。

ttl_hours 不是必需的,但我习惯定期清理:两周前的幂等记录留着没有价值,反而会让表越来越大。

四、不是所有失败都该重试

开了重试之后,第二类问题来了:一个参数错误(400)被重试了三次,每次都在下游日志里留一条脏记录。正确的划分是看这个错误"重试有没有可能变好":

错误类型 例子 是否重试 处理方式
连接超时 / 读超时 下游 30 秒没响应 重试,但必须带幂等键 2 次,指数退避 2s/6s
5xx 网关 502、服务 503 重试 3 次,加随机抖动
429 限流 下游返回 rate limit 重试 按 Retry-After 等待
400 参数错误 缺少必填字段 不重试 直接失败,进人工队列
401/403 token 过期、权限不足 不重试 告警,修配置后人工重跑
业务拒绝 工单已关闭,不能再追加 不重试 记为业务失败,不影响执行状态

在 n8n 里这些设置落在 HTTP Request 节点的 Settings 下:Retry On Fail 打开、Max Tries 设 3、Wait Between Tries 设 2000(毫秒)。但要注意它只认"节点抛错",对 4xx 也会抛错——所以更稳的做法是节点设 Never Error,让工作流自己根据状态码分支,重试只发生在分支里。

五、LLM 节点不能当事务

第二类事故更隐蔽:模型节点输出了结构化的建单参数,但下一步建单失败,重跑时模型又生成了一遍参数——两次语义相同、字段措辞不同,下游拿不到任何去重依据。

解决办法是让模型节点"只产出,不执行副作用",并且把输出落盘。工作流里变成:模型输出 JSON → 写入中间记录(带 trace_id)→ 建单步骤读这条记录、用固定的字段值调下游。这样重跑时读到的还是同一份参数,不会因为模型重新采样而漂移。

顺带一个约束:模型节点的输出必须带 trace_id 和 confidence。前者用来串日志,后者用来决定是否需要人工确认。没有这两个字段的工作流,出问题之后基本没法复盘。

六、写操作前加人工卡点

不是所有步骤都值得自动化到底。我给"建工单"加了卡点,规则很简单:涉及金额、涉及对外承诺、或者模型置信度低于阈值时,先发一条确认消息给值班人,人点了"确认"才继续。

实现上不是让工作流阻塞等人——那样会超时——而是拆成两段:第一段跑到"待确认"就结束,把上下文存进表里;人点确认时触发第二个 webhook,从表里读出上下文继续。这样两段各自都是短执行,不会因为等待被重投。

这个改动让自动化率从 100% 掉到大概 85%,但误建单的数量归零。对一个会给客户发通知的流程来说,这个取舍不用犹豫。

七、用一条 trace 串起所有执行

重复问题最终是在复盘时被解决的,靠的是能一眼看出"这三次是同一件事"。所以每个入口生成一个 trace_id,透传到每个 HTTP 请求头(X-Trace-Id)和每条日志里,幂等键也算在同一个前缀下。

排查时的查询就很直接:

# 某个上游事件触发了多少次执行
rg "trace-8f3c2a" workflow.log | awk '{print $1, $5}' | sort | uniq -c

# 下游收到了几次建单请求
rg "POST /api/tickets" downstream.log | rg "trace-8f3c2a"

两条命令一比,重复发生在哪一层就清楚了:如果上游执行只有一次、下游请求有三次,说明是重试没带幂等键;如果上游执行三次,说明是重投没被挡住。

小结

  • 网络调用的默认语义是"至少一次",重复执行的防线必须放在写操作上,不能在入口判断。
  • 幂等键要从业务事实派生(上游消息 id + 步骤名),用随机 UUID 等于没做。
  • 只对超时、5xx、429 重试;4xx 和鉴权错误重试只会制造脏数据。
  • 模型节点只产出参数并落盘,由固定步骤执行写操作,避免重跑时参数漂移。
  • 高风险写操作拆成"待确认"和"确认后续跑"两段,避免阻塞等待被超时重投。
  • 入口生成 trace_id 并透传,复盘时才能确认重复发生在哪一层。
查看「AI 应用」全部文章 →

同分类文章

查看 0 评论 0

评论

正在加载评论…

留言提交后自动审核:正常内容立即显示,含敏感信息的会转人工复核。

工作流跑了两次,工单建了两遍:Agent 的重试与幂等 - 起航社区