~/notes/singbox-merlin-async-save-and-runtime-rollback.md1321 字

项目实战sing-box 梅林插件学习笔记 · 01/03

梅林插件(一):异步保存任务与幂等重试

从已保存设置与运行配置的区别开始,讲解客户端任务编号、请求摘要、持久化任务历史和结果未知时的恢复方式。

目录 4 节

singbox-merlin 是面向华硕 TUF-BE6500 梅林官改的软件中心插件。“保存并启动”会经过浏览器、Go 管理网关、DBus 和后台脚本,执行时间可能超过一次普通 HTTP 请求。

本系列依据 0.5.42 已提交的保存与运维改造整理。第一篇先讲保存状态和异步任务:响应丢失后为什么还能找到任务,重试时又怎样避免重复启动。

一、先把“保存”和“应用”分开

这个项目最需要讲清楚的状态,是已保存设置和当前运行配置。

“保存并启动”的实际语义是先保存设置,再尝试应用。如果新配置启动失败,旧运行配置恢复使用,刚保存的设置仍然保留,方便继续修改。

对象 表达什么 应用失败后的状态
浏览器草稿 用户当前正在编辑的内容 根据编辑与任务状态保留或同步
已保存设置 下次生成配置时读取的输入 保留本次保存结果
运行配置 当前内核实际使用的配置 恢复旧版本

因此,启动失败不能统一显示成“什么都没有保存”,保存成功也不能提前显示成“新配置已经运行”。

这三个状态明确以后,错误提示、页面刷新和重试才有一致的解释。否则用户看到旧节点还在工作,很容易误以为设置没有保存,再次提交一遍相同操作。

二、HTTP 响应丢了,不代表任务没有执行

路由器上的启动、订阅更新和配置重建,都可能比一次普通接口请求慢。浏览器中途断网或者刷新,服务器仍然可能继续执行。

如果前端只根据最初那个请求的响应判断成败,就会遇到两个问题:执行成功但页面显示失败;用户重试后又启动了一次相同任务。

这次改造把操作记录成可以查询的异步任务,并持久化最近 32 个任务。前端能够按任务编号恢复查询,后续操作也不会立即让上一条任务消失。

同一编号的重复请求还需要检查操作内容。项目使用请求摘要核对编号与操作:相同编号、相同内容可以查询已有结果;相同编号却提交不同配置,必须报冲突,不能悄悄忽略新内容。

提交操作 → 创建任务 → 执行保存或应用 → 更新任务结果
浏览器恢复连接 → 查询任务 → 读取最新配置和运行状态

任务历史有明确容量。超出保留范围的旧任务无法继续恢复,这个能力不能被描述成永久保存所有操作。

在 internal/gateway/tasks.go 中,任务结构保存了 ID、操作、状态和请求摘要。下面保留与幂等判断直接相关的字段:

type Task struct {
    ID          string `json:"id"`
    Action      string `json:"action"`
    Status      string `json:"status"`
    RequestHash string `json:"requestHash,omitempty"`
}

任务编号由浏览器在提交前生成,通过 X-SBM-Task-ID 传入。这个时间点很关键:即使首个响应丢失,浏览器仍然知道要查询哪个编号,而不必重新创建操作。

请求摘要包含操作、执行环境参数和请求体。项目会对可解析的 JSON 先重新序列化,再计算 SHA256。省略读取和校验后的核心表达式是:

fingerprint := sha256.Sum256([]byte(
    action + "\x00" + strings.Join(env, "\x00") + "\x00" + string(body),
))
requestHash := hex.EncodeToString(fingerprint[:])

SHA256 在这里用于识别重复提交的内容,不是鉴权。它也不是任意两份“业务等价”配置的证明,例如数组顺序变化仍可能改变摘要。

完整处理先在任务锁内查询旧编号:同编号同摘要返回已有任务;同编号不同操作或摘要返回 409。只有确认是新任务,才持久化任务并启动后台执行。浏览器重试和新提交由此有了不同语义。

持久化任务记录也不等于持久化执行引擎。管理网关重启后,原先处于 running 的任务会被标为结果未知,提示检查实际运行状态,不会假装它已经成功或自动重做。

三、任务记录能恢复什么

任务历史让页面恢复查询能力,幂等检查让相同提交能够找到原操作。它没有把所有后台动作变成可在崩溃后自动续跑的工作流:管理网关重启后,进行中的任务会明确报告结果未知。

学习时可以从 internal/gateway/tasks.go 的 startTask 开始,再对照 tasks_test.go 中首个响应丢失、同编号重试和旧任务恢复的用例。先区分可重复查询的结果与仍需核对的运行状态,再设计重试按钮。

本系列对应仓库目前为私有,代码片段取自已核对的实现;删去的字段或流程已在相关段落注明。

系列阅读

下一章:梅林插件(二):刷新恢复、编辑草稿与配置读取

  1. 梅林插件(一):异步保存任务与幂等重试
  2. 梅林插件(二):刷新恢复、编辑草稿与配置读取
  3. 梅林插件(三):跨进程互斥与运行状态回滚