架构解释图（确定性渲染）｜幂等键负责重放，参数指纹负责拒绝漂移

✦ 01｜一次真实的重试现场

线上最常见的重试不是“再点一次保存”，而是“换个措辞再试一次”。第一次提交超时，第二次把提示词改得更明确、顺手换了个语气，客户端复用了同一个请求标识——结果接口既不生成，也不查询，直接返回冲突。

工程师的第一反应通常是让幂等键“宽容一点”：既然已经有结果，就按新参数重跑一次好了。这个改法会把幂等语义直接拆掉——重放安全的前提是请求内容相同；请求内容变了却复用旧结果，等于把一次新的生成偷偷换成旧产物。

下面按当前 Microi吾码AI 后台任务队列的真实实现拆这件事：请求怎么被指纹化、冲突在哪里被拦住、跨节点同时提交时谁赢，以及为什么状态投影宁可返回“不确定”也不伪造图片。

幂等键回答的是“这是不是同一件事”，它不负责判断参数有没有换过

✦ 02｜直觉方案为什么不够：两件长得很像的事

幂等键和参数指纹经常被合成一个概念，因为它们在正常路径上几乎同时出现：客户端带着标识提交，服务端查到已有任务，把结果回放给它。看上去只做了一个判断。

把两条失败路径摆出来，区别立刻清楚。第一条：同一次请求真的被投递了两遍，标识和参数都一样。第二条：两次是不同的请求，只是复用了标识。前者必须回放原结果，后者必须拒绝——而“拒绝”这一个动作，光靠键本身做不到。

• 键的作用域：租户 + 用户 + 请求标识，三者共同决定这算不算“同一件事”。
• 指纹的作用域：真正参与生成的参数集合，决定这次的请求是不是原来那一件。
• 键可以复用：同一件事重试时，客户端本来就该复用同一个标识。
• 指纹不可复用：参数一旦变化，就不能再声称是同一件任务了。

这也解释了为什么冲突响应里通常不带图片。它不是在告诉你“失败了”，而是在说“你提交的内容对不上号”。

提示词、比例、数量、参考图任一变化，指纹就变，旧结果不能再被声称复用

✦ 03｜键怎么派生：租户、用户、请求标识三层作用域

键的派生逻辑很短，但它决定了多租户环境里会不会串号。以图片任务为例，稳定键由租户标识、用户标识和请求标识拼接后再做一次摘要，最后再包一层任务类型前缀。

public static string BuildIdempotencyKey(string osClient, string userId, string requestId)
{
    return $"Microi:{NormalizeSegment(osClient)}:Ai:MiniMaxImage:{Sha256(userId)}:{Sha256(requestId)}";
}

public static string BuildTaskIdempotencyKey(string osClient, string userId, string requestId)
{
    using (var sha = SHA256.Create())
        return "ai-image:" + BitConverter.ToString(sha.ComputeHash(Encoding.UTF8.GetBytes(
            MiniMaxImageSupport.BuildIdempotencyKey(osClient, userId, requestId))))
            .Replace("-", "").ToLowerInvariant();
}

这里有三个刻意的选择。租户被归一化后写进明文前缀，便于运维按租户定位记录；用户和请求标识只保留摘要，避免把账号和业务标识直接写进索引字段；外层再套一层任务类型前缀，图片、音乐、语音各自独立，互相不会抢同一个键。

• 同一租户同一用户同一请求标识 → 同一键，允许回放。
• 换租户或换用户 → 键必然不同，不会跨身份复用别人的结果。
• 同一用户换请求标识 → 键不同，视为一件全新的任务。

架构解释图（确定性渲染）｜待执行、执行中、成功、参数冲突四种状态的处理路径

✦ 04｜指纹怎么否决：参数不一样就返回冲突

命中已有键之后，服务端并没有直接把旧结果丢回去，而是先把存下来的指纹和本次请求的指纹比一遍，并且顺带核对任务归属和任务类型。三项里任一项对不上，就落到冲突分支。

private static DosResult ReadMatchingTask(string osClient, string userId,
    BackgroundTaskRecord task, string fingerprint)
{
    var param = JObject.Parse(task.ParamJson ?? "{}");
    if (!string.Equals(task.UserKey, userId, StringComparison.Ordinal)
        || !IsImageWorker(task.ApiEngineKey)
        || !string.Equals(param["Fingerprint"]?.ToString(), fingerprint, StringComparison.Ordinal))
        return new DosResult(0, new { Status = "Conflict" },
            "相同 RequestId 已用于另一组图片参数，未重复生成。");
    return GetStatus(osClient, userId, task.Id);
}

注意三个比较全部用序数比较，没有大小写宽松或去空白处理。指纹本身是参数对象的稳定序列化摘要，所以提示词里多一个空格、比例从竖版换成横版、参考图换一张、生成数量从 1 改成 2，指纹都会变。

为什么归属和任务类型也要一起比：键是由用户标识参与派生的，但数据库里的唯一索引跨越了运行类型和网络类型，同一个键仍可能被另一条类型的记录先占。多比两项，等于把“看起来同一个键”收紧成“确实是同一件事”。

冲突发生在生成之前：它拦住的是参数漂移，不是一次失败的任务

✦ 05｜跨节点竞争：数据库唯一键才是最终裁决

先查后写天然有窗口。两个 API 节点同时收到同一次重试，可能同时读到“没有这条记录”，然后同时插入。读多写一次在这里救不了场，最终裁决必须落在数据库的唯一索引上。

所以入队路径在插入失败时并不立刻抛错，而是再查一次：如果另一个节点已经赢了这次竞争，就把它的记录当作本次提交的结果返回。提交动作本身就是幂等的，重复提交不会变成两条任务。

try
{
    BackgroundTaskStore.Insert(item, userId, userName);
}
catch when (!requestedIdempotencyKey.DosIsNullOrWhiteSpace())
{
    // A concurrent node can win the tenant-scoped unique key between
    // read and insert. Readback makes the submission itself idempotent.
    var concurrent = BackgroundTaskStore.FindByIdempotency(osClient, requestedIdempotencyKey);
    if (concurrent != null)
    {
        CacheProjection(concurrent);
        SignalWorkerIfPending(concurrent);
        return ApplyRuntimeFields(concurrent);
    }
    throw;
}

支撑这段逻辑的索引也有一段历史。早期只有租户加幂等键的窄定义，后来扩成包含运行类型和网络类型的宽定义。升级过程刻意不做“先删后建”：新建索引并回读成功之后，才移除旧的窄定义。这样即使有节点在迁移中途被强杀，也不会出现一段没有任何幂等边界的窗口。

• 窄定义：租户 + 幂等键，早期版本的最终边界。
• 宽定义：租户 + 幂等键 + 运行类型 + 网络类型，跨运行环境隔离。
• 迁移顺序：先建并回读，再删旧定义；中途被杀不会留下无边界窗口。

先查后写只能降低概率，唯一索引才能把并发竞争收成一个赢家

✦ 06｜状态回读：宁可返回不确定，也不伪造图片

幂等队列的另一个坑不在写入，而在回读。任务还在排队或执行中时，接口返回的不是成功也不是失败，而是一个明确的“继续用同一个任务号查询”的信号；投影层只回任务号、状态来源和轮询间隔，不会顺手补一个空的图片数组。

终态判断同样严格：任务记录标记成功，但结果里没有真实图片项时，仍然按失败处理。反过来，调用方拿到“不确定”时只允许查询原任务，不能新建任务——队列不会因为上游超时替调用方重投。

1. 排队中、执行中、重试中：返回继续轮询的信号，不返回图片。
2. 成功但结果缺少图片项：按失败处理，不把状态字段当作产物。
3. 上游超时或状态不确定：只允许查询原任务号，换号重投需要明确的失败终态。
4. 失败终态且留有结果：允许在同一个任务上做受控恢复，不新建任务。

状态投影只回任务号与轮询信号；没有真实图片项就不算成功

✦ 07｜怎么写调用方：三条可搬走的规则

把服务端的约束翻译成调用方代码，只有三件事要做对：标识在重试期间保持不变；参数变更必须换标识；冲突响应要当成需要人工或业务决策的状态，而不是可以静默重试的错误。

// 1. 标识在整次业务动作里稳定：先算出来，再重试
const requestId = `settlement:${orderId}:close`;

// 2. 参数变化必须换标识：不同参数不是“同一件事的重试”
async function generate({ prompt, aspectRatio, requestId }) {
  const response = await post('/api/AiEngine/GenerateMiniMaxImage', {
    RequestId: requestId,
    Prompt: prompt,
    AspectRatio: aspectRatio,
  });
  if (response.Code === 2) return poll(requestId, response.Data.TaskId);   // 排队中：继续查询原任务
  if (response.Data && response.Data.Status === 'Conflict') {
    throw new Error('相同 RequestId 已用于另一组参数，请换用新的 RequestId');
  }
  return response;
}

规则不复杂，但它纠正了一个很常见的习惯：把请求标识当成“这次调用的编号”。它其实是“这次业务动作的名字”。名字在重试期间不能改，参数变了也不能沿用旧名字。

架构解释图（确定性渲染）｜提交、指纹比对、跨节点竞争、终态回读

✦ 08｜证据边界：哪些已经验证，哪些还没有

上面每个结论都能指回当前源码。除此之外还有一层可执行验证：聚焦测试覆盖了键的稳定性、租户与用户的隔离、唯一键非法值拒绝，以及“提示词变化不能回放旧图片”这一条。

验证记录（确定性渲染）｜聚焦测试 34 项通过，另有实时接口回执留档

1. 已验证：键的派生与作用域、冲突判定、排队状态不返回图片、成功必须有真实图片项。
2. 已验证：升级迁移顺序为“先建并回读、再删旧索引”，不在迁移窗口内移除幂等边界。
3. 已实测：真实接口对同标识同参数返回排队而非新任务，对同标识不同参数返回冲突。
4. 未宣称：跨数据库类型的索引行为差异仍需按目标库单独回读，本文不把它写成通用结论。

把幂等键和参数指纹分开之后，“为什么会冲突”就不再是一个玄学问题：它不是系统不够智能，而是它替你把一次参数漂移挡在了生成之前。

升级期间也必须有幂等边界，先建并回读成功才能移除旧定义

文中架构解释图由AI生成；源码摘录、测试记录与接口回执均来自当前工作区与实时接口。

文中已标注的概念图由AI生成；源码与实测证据均来自当前工作区。