说明:本文来自我自己的一套本地运维实践,命令、字段、退出码、字节数均为真实结构与实测值。为保护隐私,agent 名一律写作甲/乙/丙,工作目录写作 <workdir>,任务 id、主机名、端口、账号等信息已做泛化;文中出现的哈希前 16 位仅为改造留证的校验指纹,不含任何敏感数据。每个关键数字后用括号标注了它的原始来源文件名,便于逐条核对。

一、现象:同一段时间,日志里多了两行

事情从一个看起来很小的问题开始。我这套系统里有三个 agent 各管一摊,甲管理财线、乙管求职线、丙管工程运维。丙负责的"心跳"是一个按固定相位触发的定时任务:每半小时醒一次,醒来记一行日志,声明自己落在哪个时间"段"里。

某天做例行审计时,审计脚本报出一组重复段:一天之内有 14 个时间段,每段都出现了两行日志,而不是应有的一行。

先把口径说清楚,因为后面所有争论都卡在这个词上:

  • 客观重复:同一段确实有两行,这是个客观事实;
  • 待处置:这两行是不是"真重复劳动",需要人工判断。

审计脚本把这两件事分开报。当天处置前读数是:待处置段 14 个、待处置行 28 行;处置后 14 → 0、28 → 0(来源:<workdir>/reports/ops/HB_DUPSEG_DISPOSE_20261121.md §0、§2)。注意归零的是"待处置数",不是"客观重复数"——后者因为任务规矩禁止删历史行,永远不会归零。这个区别很重要,后面会反复提到。

二、第一次归因:不是锁坏了

看到重复,第一反应几乎都是"锁没生效"。我去查了写日志的那道段锁,结论是它一直好好工作。

那 14 段的第二行,几乎都带着类似的自我声明:

1
动作=NOOP(本段已完成) 目标段当天已有行(并发实例已抢先写入)

也就是说,后到的那个实例在动手之前,其实是撞到过段锁的——它看到本段已经有行了,于是并没有真的重做工作,只是按一条既定的"补写留痕"规则,追加了一行"我毂也触发了,但本段已完成,不重复做"。

这里就有个反直觉的点:重复行是"锁生效"的产物,不是"锁失效"的产物。 机制本身允许一种合法的第二行——只写一条 NOOP(本段已完成) 的留痕,不承载新主题、不覆盖正文数值。这条通道被设计出来是为了审计可追溯,结果每个并发实例都用它留了一次痕,于是一段就有两行。

所以"删掉第二行"是最容易想到、也最错的做法:它既抹掉了审计痕迹,又没有解决产生第二行的上游原因。

三、真正的根因:锁键的粒度错了

顺着"为什么会有并发实例"往上查,才摸到真正的洞——前置的单实例互斥闸。

这套系统在三道主闸门之前,还有一道"前置闸",作用是把同一时刻被并发派发的多个实例收敛成一个:先抢到锁的继续干活,后到的静默退出。它靠一把命名互斥锁实现,锁的名字由一把"键"拼出来。

问题就出在这把键上。改造前(v1)的键是这样算的:

1
2
3
# v1:键 = 任务短名 + 触发分钟
$key = "$jobShort-$minute"
$mutexName = "Local\\hb-job-$key"

看起来合理:同一个任务、同一分钟,只放一个实例。但它有两个隐含假设,而两个假设当天同时破了:

  1. 假设"同一任务"的 id 渲染稳定。实际运行里,同一个逻辑任务的 id 有时带后缀、有时不带,两种渲染下算出的 $jobShort 不同。
  2. 假设"同一分钟"足够精确。实际触发时刻可能相差几秒甚至跨分钟,:56 和 :57 算出的 $minute 不同。

两个假设一破,两把键就不同了。日志实证里有这样的组合:同一个时间段内出现两组不同键值的实例,它们触发分钟相同或相近,但任务 id 渲染不同、短名各异,于是 $key 不同 → 互斥锁不是同一把 → 两个实例都拿到 ACQUIRED,各走各的,最后各写一行。

当天 16:57 那段,第一次出现了真实的 OCCUPIED 记录——这是系统第一次明确告诉我们"有两个实例撞在一起了"。根因就是它暴露出来的。

一句话概括:锁没坏,锁键的粒度错了。 v1 用"任务 id + 触发分钟"做键,粒度太细,把本该互斥的同一时间段拆成了多把锁。

四、修法:把锁键换成段窗

修法的核心只有一句:既然这套系统本来就有明确的"段"概念(HH:27 和 HH:57 两个相位),那锁键就应该直接用段,而不是绕道去用任务 id 和触发分钟。

改造后(v2)的键是这样算的:

1
2
3
4
5
6
7
8
# v2:键 = 段窗,与任务 id、触发分钟都无关
$hh = [int]$minute.Substring(0,2)
$mm = [int]$minute.Substring(2,2)
if ($mm -ge 57)      { $segTag = ('{0:D2}:57' -f $hh) }
elseif ($mm -ge 27)  { $segTag = ('{0:D2}:27' -f $hh) }
else                 { $segTag = ('{0:D2}:57' -f (($hh + 23) % 24)) }
$key = "seg-$segTag"
$mutexName = "Local\\hb-job-$key"

段窗规则和日志审计、段锁里的归段函数同源,三处是同一套口径:

  • 分钟 ≥ 57 → 归到本小时 HH:57,段窗 [HH:57, 次日 HH:27);
  • 分钟 ≥ 27 → 归到本小时 HH:27,段窗 [HH:27, HH:57);
  • 分钟 < 27 → 归到上一小时的 HH:57(跨小时回绕)。

效果:任意两个实例,只要落进同一个段窗,无论任务 id 怎么渲染、触发分钟是 :56、:57 还是 :58,都争同一把命名锁;后到的那个直接 OCCUPIED 静默退出,从源头不再产生第二行。

改造面被刻意压到最小:只改键的派生逻辑这一处。段锁、补写留痕通道、三道主闸门、判据阈值、相位定义,一律不动。这条边界在后面第 8 节会给出逐行未动的证明。

五、实测数字,逐条标来源

下面是这次改造的关键数字,每一个都用括号标了原始来源文件(路径按隐私要求做了抽象):

指标 改造前 改造后 来源文件
待处置重复段 14 0 <workdir>/reports/ops/HB_DUPSEG_DISPOSE_20261121.md §0、§2
互斥闸脚本字节数 12,368 B 17,280 B <workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §1
selftest 断言数 13 条(13/13) 21 条(21/21) <workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §2、<workdir>/reports/ops/HB_MUTEX_SEGWINDOW_VERIFY_20261121-1757.md
互斥闸脚本 sha16 D43788E6B6ED1E1A 1CC0857D95A8DA1C <workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §1
selftest 脚本字节数 8,635 B 10,824 B <workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §1

几个值得展开的点:

字节数与哈希一起变,证明改造真的落盘了。 互斥闸脚本从 12,368 B 涨到 17,280 B,净增 4,912 B;前后 sha16 完全不同(来源:<workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §1)。如果只报"改了"却给不出字节差和哈希差,等于没证明——改造前那版以 .bak 留证件原样保留,两版并存可回滚。

selftest 复跑的真实末行(来源:<workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §2.1):

1
2
3
ASSERTIONS=21 PASS=21 FAIL=0
RESULT: HBMUTEX_SELFTEST = total=21/pass=21/fail=0
RESULT: HBMUTEX = key=seg-<HH:27|HH:57> (v1 key was <job8>-<HHmm>)

退出码 exit 0,且与判方的独立复跑结果一致(来源同上)。

生产侧也拿到了新键的实证。 改造后在一次真实段触发时,抢锁输出长这样(来源:<workdir>/reports/ops/HB_MUTEX_SEGWINDOW_VERIFY_20261121-1757.md「生产侧佐证」节):

1
HB_MUTEX = ACQUIRED | key=seg-17:57 | window=17:57-18:27 | hold=1860s

key=seg-17:57 说明段窗键在生产路径上真正生效了;hold=1860s 是段窗 30 分钟加 1 分钟余量、再被持锁上限截断后的值。

六、selftest 为什么从 13 条加到 21 条

新增的不只是"换了个键"那一条断言,而是净增 8 条(13 → 21,来源:<workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §2.2)。这 8 条不是凑数,每一条都对着 v1 的一个具体盲区:

# 新增断言 挡住的 v1 漏洞
1 首实例 key 必须是段窗形态 v1 只查"抢到了没",不查键长什么样;键退回分钟串也照样绿
2 持锁时长必须为正 v1 持锁字段没有断言,退化成 0 会让锁瞬间释放
3 同窗异分钟必须 OCCUPIED v1 恰恰断言"异分钟应放行",把跨分钟双跑当正常
4 键里不得含触发分钟 直接堵死"分钟混进键"的路
5 同窗异任务 id 必须 OCCUPIED v1 断言"异任务应放行",正是 16:57 那次的根因
6 异段窗键必须精确映射 防段窗归一化算错,误挡相邻段或漏挡同段
7 持锁者退出后仍保持占用 v1 完全没有"持锁存续/陈旧回收"类断言
8 正常抢锁不产生额外留痕行 v1 用文件计数(只增即过),太粗;v2 改成逐行精确计数

把 v1 的盲区归一下类就清楚为什么要加这么多:

  1. 不校验键的形态——键算错了测试也发现不了;
  2. 把跨分钟、异任务双跑当成正常行为——测试本身在保护 bug;
  3. 没有持锁存续与精确留痕校验——锁的生命周期没人管。

这三类被 8 条逐一对死。只补一条"键等于段窗"是挡不住的,因为 v1 的测试集里有两条断言是反向保护 bug 的(异分钟放行、异任务放行)——不把它们反转过来,新键一上,旧测试立刻报错,人或改测试或改回代码,最后又绕回原点。所以这次是连同测试语义一起重构:v1 的 13 条里,6 条保留、2 条改名等价、5 条被反转或取代(来源:<workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §2.3)。

七、为什么选"改键",不选"删留痕"

有人会问:既然第二行只是留痕,为什么大费周章改锁键,而不是干脆规定"同段只留一行"?

三个理由:

第一,留痕是审计资产,不是垃圾。 那 28 行留痕记录了"某时刻有第二个实例也被触发了、并主动让行"这一事实。它对排查并发问题有价值,删掉等于自废武功。这次处置的做法是给每条留痕加一个良性标记、登记进白名单,让审计脚本按指纹精确识别——而不是删行、也不是改历史数字(来源:<workdir>/reports/ops/HB_DUPSEG_DISPOSE_20261121.md §1、§5)。

第二,堵上游比清下游省事。 只要锁键还是"任务 id + 分钟",并发实例就会源源不断产生第二行。今天清 14 条,明天又来 3 条——事实上这次处置过程中,就有另一个实例在 15:57 段实时写入了一对新双行(来源同上 §2.3)。改键是从源头拧掉水龙头;清留痕只是反复拖地。

第三,最小改动面 = 最小回归风险。 这次只动了键的派生逻辑和它的两处文档描述,没有碰段锁、补写通道、闸门判据。改动面越小,越容易证明"别的都没坏"。

八、边界:这次没有动什么

技术复盘最怕把"做了什么"说清楚、把"没做什么"含糊过去。这里把边界列明:

  • 相位定义一字未动。 HH:27 和 HH:57 的段窗区间定义,改前改后字节级完全相同(来源:<workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §3.3)。
  • 三道主闸门和判据阈值一字未动。 文档改动只落在两行,且这两行只描述前置闸自身的锁键与触发范围,不含任何闸门条件、阈值或相位数值(来源同上 §3)。
  • 客观重复数没有归零。 审计里"同段两行"的计数仍然是 14(后来因实时新增变 15),这是对的——任务规矩禁止删历史行,这个数本来就不该归零。归零的是"待处置数"。把这两个数混为一谈,是这次复盘里最需要防的误读(来源:<workdir>/reports/ops/HB_DUPSEG_DISPOSE_20261121.md §2.2、§6)。
  • 改造前的留证件原样保留。 .bak 后缀的旧版脚本、改造时的复核件、selftest 复跑输出全部保留,可回滚(来源:<workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md 边界声明节)。

九、两个容易算错的地方

锁键换成段窗之后,还有两个数字容易被想当然,这里单独拎出来说,因为它们都出现在实测输出里。

一是持锁时长为什么是 1860 秒。 生产抢锁输出里 hold=1860s 不是随手填的。段窗本身是 30 分钟(1800 秒),但段与段之间需要留一点余量,防止持锁者在段窗结束的最后一刻释放、紧接着下一段的实例就冲进来;所以默认持锁时长是"到段窗结束再加 120 秒"。30 分钟加 2 分钟本该是 1920 秒,但它撞上了 1860 秒的持锁上限,被截断了——这就是 hold=1860s 的来历(来源:<workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §1.1、<workdir>/reports/ops/HB_MUTEX_SEGWINDOW_VERIFY_20261121-1757.md「生产侧佐证」节)。上限本身是必要的:万一持锁进程崩溃、没能主动释放,锁不能永久卡住后面所有实例。这里有个精妙之处——持锁者进程退出后很短时间内,同段窗仍须判定为占用,否则一个刚退出的旧实例会让新实例误以为锁空了。这正是新增断言第 7 条(持锁者退出 21 秒后仍 OCCUPIED)在守的事:陈旧回收的窗口必须比正常段执行更长,不能偏心到把还在干活的实例踢掉。

二是跨小时回绕为什么用 (hh + 23) % 24。 段窗规则里"分钟 < 27 归到上一小时的 HH:57",在 00:00 到 00:26 这段代码上会跨午夜。普通的 hh - 1 在零点会算出 -1,直接格式化就坏了;用 (hh + 23) % 24 让 0 点回绕到 23 点,于是 00:00–00:26 归到前一天的 23:57。这不是纯防御性写法——它每天都真实发生一次,是 24 小时循环里必然会走到的分支(来源:<workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §4,段窗规则与归段函数同源部分)。如果这段归一化算错,后果是相邻两段的键撞车或漏挡,新增断言第 6 条(异段窗分钟 23:26 必须精确映射到 seg-22:57)就是专门盯这个的。

把这两个细节和前面第 5、6 节连起来看会发现,这次改造真正增加的代码量,大半不在"$key 怎么拼"这一行,而在"怎么证明各种边界都算对"的断言和留证上。脚本净增 4,912 B、selftest 净增 2,189 B(来源:<workdir>/reports/ops/HB_MUTEX_SEG_KEY_20261121.md §1),增加的主要就是这部分。并发代码的价值从来不在"能跑通的正常路径",而在那些一天只走一次、一走就容易错的边界上。

十、收口

把这次的因果链连起来:

段锁 → 撞锁 → 走合法补写留痕通道 → 一段两行(审计报"重复")→ 一路追到上游 → 前置互斥闸的键掺了任务 id 和触发分钟 → 同段两实例键不同、互不排斥 → 把键换成段窗 → 同窗收敛成一实例 → 从源头不再产生第二行 → selftest 用 21 条断言把新语义钉死。

这件事最大的教训不是"锁要用对粒度"这么一句正确的废话,而是两条更具体的经验:

  1. 看到异常先分清"机制失效"还是"机制被合理使用"。这次的重复行是锁生效的产物,不是失效的产物。归因错了,后面全错——删行会抹掉审计,改判据会掩盖症状。
  2. 修 bug 时,测试集里可能有断言在保护 bug。v1 的测试明确写着"异分钟应放行、异任务应放行",这两条如果不同步反转,修复根本落不下去。所以改代码和改测试语义必须被视为同一个动作,selftest 从 13 条涨到 21 条,涨的正是这份"把新语义钉死"的成本。

锁键从"分钟"换成"段窗",字面上只改了几个字符,背后是把"什么算同一件事"这个定义重新说了一遍。并发系统里最难的不是加锁,是把"锁什么"这件事想清楚。