自动化 · XB 现场笔记

Horizontal Pod Autoscaler 依赖明确的指标语义

Wed, 22 Dec 2027 00:00:00 +0000

HorizontalPodAutoscaler 把配置的指标转换为副本建议，因此选择指标与聚合口径本身就是应用设计的一部分。增加副本应该能够降低所测压力，或提升真正有用的吞吐量，否则控制器可能只增加费用，却无法缓解瓶颈。应设置明确的最小与最大副本数，但成本上限不等于性能保障，更不代表到达上限之后仍能处理任何规模的请求。

区分测量与控制

HPA 通常周期性协调，控制器默认同步间隔为十五秒。对于按 Pod 平均的目标，基本计算是当前副本数乘以当前指标与目标指标的比值，再向上取整。CPU 利用率相对于资源 requests 计算，不是相对于 limits，也不是整台节点的总容量。把分母理解错，会让看起来合理的百分比对应完全不同的扩容时机。

跨 Pod 求平均，与对时间序列做移动平均是两回事。Metrics Server 的 CPU 用量来自一个测量窗口，自定义适配器则有自己的查询与取样语义。HPA 并不会统一替每种输入做一个可配置时间窗口的平滑。容差、就绪处理、稳定窗口与速率策略属于控制层，是围绕指标建议的不同机制，不能全部称作“先平滑再决策”。

先确定单位，再讨论目标数字。按 Pod 的自定义指标使用 AverageValue；对象和外部指标可使用 Value 或 AverageValue，扩缩意义不同。整个队列的总积压与每副本平均积压不是可以随意互换的输入。资源利用率还要求提供相应资源请求。即使接口返回正常数字，如果它衡量的不是实际瓶颈，控制器依旧可能做出没有业务价值的动作。

选择增加副本能够改善的信号

CPU 常适合计算密集型服务，但必须先有可用的资源指标接口，并非所有集群天然具备。工作者等待数据库时，可能 CPU 很低、延迟很高；增加更多工作者反而加重数据库压力。依赖自动扩缩之前，应验证目标值是否对应每副本能够持续承担的真实工作，而不是只确认图表会随着请求变化。

请求速率、在途工作与消费积压都需要明确范围。按 Pod 的指标应保留必要的逐 Pod 观测，不能一概预聚合成每工作负载一条序列；对象或外部指标则要聚合到指定工作负载或队列，排除无关流量。避免不必要的用户级、请求级标签，防止查询成本膨胀和选择条件变得难以解释。聚合不是越少越好，而是必须与指标类型的契约一致。

副本字段要有明确负责人

HPA 会读取目标的 scale 信息，并修改副本数。Deployment 初始 replicas 不是 HPA 下限，真正配置的地板是 minReplicas。若部署流程反复提交一个固定副本数，便可能与 HPA 争抢同一字段。应明确配置所有权，并提前安排取消自动扩缩之后使用什么静态规模；不要把最初的副本值说成控制器永远不读取、也完全无关的数字。

坏掉的样子

自定义指标不可用时，不会自动转去读取 CPU。配置多个指标后，HPA 选择可用建议中的最大值；若某一路失败，而其他可用建议要求缩容，则跳过这次缩容。若有效指标要求比当前更多的副本，仍可能扩容。因此显式加入 CPU 是增加一条输入，并不是在两个方向上都无条件接管的故障切换机制。

还要区分整个指标来源失败，与部分 Pod 缺失测量。后者也会在资源算法里触发保守调整，但不是同一种问题。应检查 conditions 与 events，不要断言任何单个样本缺失都会让 ScalingActive=False。有效读数、失败来源与副本上下限可能同时存在，单看某个显示为未知的数值无法还原整个决策过程。

适配器数据过旧，会让控制器在队列已清空之后才扩容。调目标值前，先检查时间戳、查询范围、缓存与采集延迟。接口报错与“读数有效但选错了指标”也不同：把内存当作不合适的延迟代理，不会仅因为相关性差就把读数变成 Unknown。先判断是取不到数据，还是数据根本无法指导有效动作。

快速验证

保存为 hpa_metric_sim.py，执行 python3 hpa_metric_sim.py。这个标准库模型使用已经计算好的每副本平均值，初始副本位于上下限内，展示多指标取最大值和来源失败时的缩容保护。它并没有实现每一种 HPA 指标类型，更没有访问真实集群。

import math
import sys


def desired_for(current, value, target):
 assert current > 0 and target > 0
 if value is None:
 return None
 assert value >= 0
 return math.ceil(current * value / target)


def decide(current, metrics, min_replicas, max_replicas):
 assert 0 < min_replicas <= current <= max_replicas
 recommendations = [desired_for(current, value, target)
 for _, value, target in metrics]
 available = [want for want in recommendations if want is not None]
 if not available:
 return current
 want = max(available)
 if None in recommendations and want < current:
 return current
 return max(min_replicas, min(max_replicas, want))


def check(actual, expected, message):
 assert actual == expected, (message, actual, expected)
 print(f"OK: {message} -> {actual}")


def main():
 current = 4
 cpu = ("cpu", 80, 50)
 queue = ("average_queue", 900, 300)
 missing_queue = ("average_queue", None, 300)
 cool_cpu = ("cpu", 10, 50)
 check(decide(current, [cpu, queue], 1, 20), 12, "maximum wins")
 check(decide(current, [cpu, missing_queue], 1, 20), 7, "missing allows scale-up")
 check(decide(current, [cool_cpu, missing_queue], 1, 20), 4, "missing blocks scale-down")
 check(decide(current, [("cpu", None, 50), missing_queue], 1, 20), 4, "all missing holds")
 check(decide(current, [cpu, queue], 1, 10), 10, "upper bound")
 check(decide(current, [cool_cpu, ("average_queue", 30, 300)], 1, 20), 1, "valid low metrics shrink")
 check(decide(current, [cool_cpu], 2, 20), 2, "lower bound")
 print("PASS: 7 model scenarios; no Kubernetes controller was exercised")
 print(sys.version.split()[0])


if __name__ == "__main__":
 main()

七条断言分别检查热指标提出十二与七副本、失败来源伴随缩容建议时保持四个、全部来源失败时也保持四个，以及两个边界和完整有效的缩容到一个。两种语言中的代码副本都在本轮通过 Python 3.12.14 本地运行。相同代码确保公式和保护条件一致，输出中的数字可以逐项与正文解释对应。

实验没有运行集群控制器、指标适配器、容差、就绪调整、稳定窗口或扩缩速率策略。学习目标是代码中明确写出的失败来源保护条件。要证明生产自动扩缩可用，仍需另行核对真实时间戳、状态条件和伸缩事件；算术断言成功不能替代这条端到端证据。

来源

Kubernetes 水平自动扩缩，说明算法与指标来源，已核验 2026-10-15。
资源指标流水线，说明指标服务与资源指标接口，已核验 2026-10-15。
HorizontalPodAutoscaler walkthrough, Pods metrics use AverageValue; object/external types differ，已核验 2026-10-15。

Cron 按日历重复触发任务

Thu, 30 Sep 2027 00:00:00 +0000

Cron 按日历字段匹配时间，并在匹配时启动命令。它不会天然等待同一个命令的上一次执行结束。如果每分钟触发的任务要运行七十秒，下一分钟就可能再启动一份。因此，触发规则、并发规则和成功完成状态必须分别设计，不能因为写好了一个周期表达式，就认为重复工作的所有行为都已经确定。

把字段理解为日历选择

传统用户 crontab 一行依次包含分钟、小时、月内日期、月份、星期，然后是命令。星号表示该字段的全部取值。分钟位置的 */15 是在每个小时内选择相应分钟值，不是从上次任务结束之后再计时十五分钟。步长如果不能均匀划分字段范围，跨过边界时就可能出现不同长度的间隔，不能把它当作连续经过时长。

Debian/Vixie 格式对于两个日期字段有特殊规则：当月内日期和星期都受到限制时，满足其中一个日期条件就可能运行，而分钟、小时和月份限制仍然必须满足。这不是月份与星期之间的“或”关系。安装简短表达式之前，应列出具有代表性的实际日期核对意图，避免以为“每月某日恰好是周五”却写成两个日期条件各自都能触发。

时区、夏令时变化和停机都会影响日历调度，不同实现对跳过或重复时段的处理并不完全相同。Debian 文档为部分小幅时钟调整和固定时间任务定义了特殊行为，从其他调度器复制结论可能不适用。本实验没有修改时钟，也没有覆盖这些切换情况。日历触发同样不等于持久队列，不能自动保证停机期间错过的每次任务都会补跑。

坏掉的样子

重叠任务可能重复产生副作用、争夺资源或相互覆盖文件。如果要求同一时刻只有一个实例，就要明确实现这一政策。非阻塞建议锁可以让后来的实例记录跳过；阻塞锁则可能留下等待进程。两种选择都不自动提供业务效果恰好一次，也不能修复已经执行了一半的操作。是否允许跳过，应来自任务自己的业务要求。

本地文件锁只协调使用同一相关锁机制的参与者，不会自动串行化无关主机上的工作。网络文件系统的锁语义也需要单独确认。锁必须覆盖实际工作生命周期，跳过结果则应能被观察。如果一个实例永久卡住，后来每次触发都静默丢弃，表面上调度器还在工作，但业务可能早已停止推进，因此还要监控最近成功完成距今多久。

Cron 也并非一律没有日志。Debian 默认通过 syslog 记录任务启动，并提供更细的日志选项。命令输出可能在可用邮件链路存在时被投递，但极简容器经常没有这样的链路。应把启动、完成、失败和跳过结果写到明确目的地。启动记录只能证明任务被派发，不能证明真正的应用工作已经成功完成。

快速验证

使用全新的临时 Debian 12 Docker 容器，以 root 运行，确保没有既有 root 任务表或 cron 进程。通过 apt 安装 python3、cron 和 procps，将下面代码保存为 cron-overlap.py，再执行 python3 cron-overlap.py。需要预留约两分钟，因为程序等待的是实际日历触发，没有用模拟调度器替代 cron，也没有加速或调整宿主时钟。

from pathlib import Path
from tempfile import TemporaryDirectory
import json
import os
import subprocess
import time

assert os.geteuid() == 0 and Path('/.dockerenv').exists(), 'use a disposable root Linux container'
assert subprocess.run(['pgrep', '-x', 'cron'], capture_output=True).returncode == 1
assert subprocess.run(['crontab', '-l'], capture_output=True).returncode != 0

with TemporaryDirectory(prefix='cron-overlap-') as directory:
 root = Path(directory)
 events_path = root / 'events.jsonl'
 stop = root / 'stop'
 worker = root / 'worker.py'
 worker.write_text('''from pathlib import Path
import fcntl,json,os,sys,time
root=Path(__file__).parent
kind=sys.argv[1]
def record(event):
 data=json.dumps({'event':event,'kind':kind,'pid':os.getpid(),'monotonic':time.monotonic()})+'\\n'
 fd=os.open(root/'events.jsonl',os.O_WRONLY|os.O_CREAT|os.O_APPEND,0o600)
 try: os.write(fd,data.encode())
 finally: os.close(fd)
lock=None
if kind=='locked':
 lock=open(root/'job.lock','a')
 try: fcntl.flock(lock,fcntl.LOCK_EX|fcntl.LOCK_NB)
 except BlockingIOError:
 record('skip')
 raise SystemExit(0)
record('start')
try:
 until=time.monotonic()+70
 while time.monotonic()<until and not (root/'stop').exists(): time.sleep(0.1)
finally:
 record('end')
 if lock: lock.close()
''')
 table = ''.join(f'* * * * * /usr/bin/python3 {worker} {kind} >>{root}/worker.log 2>&1\n'
 for kind in ('plain', 'locked'))
 subprocess.run(['crontab', '-'], input=table, text=True, check=True)
 daemon = subprocess.Popen(['cron', '-f'], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
 def read_events():
 if not events_path.exists():
 return []
 return [json.loads(line) for line in events_path.read_text().splitlines()]
 try:
 deadline = time.monotonic() + 140
 while time.monotonic() < deadline:
 assert daemon.poll() is None, 'cron exited'
 events = read_events()
 plain = [e for e in events if (e['kind'], e['event']) == ('plain', 'start')]
 locked = [e for e in events if (e['kind'], e['event']) == ('locked', 'start')]
 skipped = [e for e in events if (e['kind'], e['event']) == ('locked', 'skip')]
 if len(plain) >= 2 and skipped:
 break
 time.sleep(0.2)
 else:
 raise AssertionError('two real cron ticks were not observed')
 assert len(plain) == 2 and len(locked) == 1 and len(skipped) == 1
 assert plain[1]['monotonic'] - plain[0]['monotonic'] < 70
 assert not any(e['event'] == 'end' and e['pid'] == plain[0]['pid'] for e in events)
 print(json.dumps({'actual_cron_starts': len(plain), 'overlap_observed': True,
 'seconds_between_starts': round(plain[1]['monotonic']-plain[0]['monotonic'], 3),
 'locked_starts': len(locked), 'locked_skips': len(skipped)}), flush=True)
 finally:
 daemon.terminate()
 stop.touch()
 daemon.communicate(timeout=5)
 subprocess.run(['crontab', '-r'], check=True)
 deadline = time.monotonic() + 5
 while time.monotonic() < deadline:
 events = read_events()
 started = {e['pid'] for e in events if e['event'] == 'start'}
 ended = {e['pid'] for e in events if e['event'] == 'end'}
 if started <= ended:
 break
 time.sleep(0.1)
 else:
 raise AssertionError('test workers did not finish')

两条每分钟执行的记录会运行原本持续七十秒的工作进程。plain 分支没有锁；locked 分支使用共享文件和非阻塞独占 flock，未取得锁时记录 skip 并退出。每个事件包含进程标识和单调时间，能够直接区分不同实例，并检查第二次启动发生时第一次是否仍在执行，而不是仅根据配置推测并发。

在 Debian cron 3.0pl1-162 中，普通分支相隔 60.003 秒启动两次，而且第二次启动时第一次尚未结束。加锁分支只真正启动一次，另一次记录跳过。所有断言已经运行成功。清理阶段先停止 cron，通过停止文件通知实验工作结束，移除临时任务表后等待结束记录，不留下测试后台进程。

这个实验验证本机的重叠执行与显式互斥，没有实现持久重试、分布式锁、重启后恢复或业务效果恰好一次。真实任务需要这些能力时，应按当前业务契约选择并验证相应机制，不能认为日历表达式已经隐含提供了全部保障。

来源

Debian 12: crontab(5)，日历字段、步进及两个日期字段的组合，已核验 2026-09-13。
Debian 12: cron(8)，守护进程执行、日志和时钟变化处理，已核验 2026-09-13。
Linux: flock(2)，建议锁及非阻塞获取，已核验 2026-09-13。

GitHub Actions 工作流给构建把门槛

Thu, 02 Sep 2027 00:00:00 +0000

工作流能够为合并决定提供证据，但只有 YAML 并不会让这些证据成为强制要求。可靠的构建门禁需要连接正确的事件、实际测试的准确版本、有意义的测试结果，以及要求对应检查通过的仓库规则。审阅时应把这些环节一起核对，不能看到早先某次运行有绿色标志，就认为这次拟合并的内容已经满足当前要求。

区分执行与强制要求

.github/workflows/ 下的文件描述触发器和作业。on 选择事件，分支保护或规则集则另行决定合并之前必须通过哪些检查。应记录稳定的检查名称，并在改名时同时审阅相应规则。不同工作流也应避免产生含糊的同名作业；如果规则指定检查来源，还需确认结果确实由预期的可信应用提供。

还要查看合并请求检查框显示的版本。pull_request 运行通常检查的是合成的合并提交，而不只是贡献者分支末端。合并队列为候选组合生成检查时，需要独立的 merge_group 事件。本地构建成功，或者手动触发过某份工作流，都不能自动替代规则要求的事件与版本；检查对象不一致时，即使输出相同，也不构成同一次验证。

明确依赖结果

没有依赖的作业可以并行运行，单个作业里的步骤通常顺序执行。needs 建立前置关系，条件控制失败或跳过之后哪些工作仍会执行。只有一个必需测试作业的工作流，并不需要人为增加依赖作业，也不必额外添加事件条件。因此，把缺少这些字段一律判成错误的检查器，无法准确判断门禁是否有效。

如果使用汇总门禁，应等待每个必需作业，并显式检查其结果。通过 if: ${{ always() }} 避免前置失败后只把门禁跳过，再要求结果确实为成功。如果某项可选工作允许跳过，应明确编码这个例外，而不是把所有缺失结果都视为通过。必需测试也不能随意开启忽略错误，否则一条普通的成功提示就可能掩盖没有完成的验证。

权限声明约束令牌，不约束所有凭据

permissions 控制的是 GITHUB_TOKEN，不会限制另行传给命令的其他秘密凭据。严格的工作流级声明可以由作业继承，不需要每个作业机械重复同样内容。只有真正需要的地方才增加权限。下面的离线实验没有检出私有源码，也不调用 GitHub 接口，因此不使用令牌；真实项目接入源码时，应重新检查实际最低权限需求。

普通的复刻仓库合并请求通常收到只读令牌，而不会收到仓库秘密，具体仍受仓库设置影响。“秘密只读”不是准确说法，令牌权限与秘密可用性是两个问题。不能为了取得秘密，就改用具有更高权限的 pull_request_target 并执行不可信的请求代码。日志遮盖只是辅助保护，不是打印凭据的许可，也不保证经过转换后的值绝不会泄漏。

坏掉的样子

整个工作流因路径或分支过滤没有运行时，对应必需检查可能一直等待；作业因条件而跳过，却可能在没有执行测试的情况下满足检查规则。这是两种不同结果。修改检查名称时应小心，并在托管服务上验证失败、跳过和取消路径，不能只用一次成功运行证明规则配置正确。检查能否出现、是否真正运行和能否阻止合并，需要分别确认。

缓存需要兼容的键，也需要按依赖声明执行可靠安装。普通合并请求产生的缓存属于该请求的合并引用，仅仅键相同，并不意味着基础分支可以恢复它。不能笼统声称任何复刻请求缓存都能污染主分支；应结合事件、引用范围和信任关系判断风险。另外，测试取消与部署恢复也不同：取消正在运行的作业，不会自动撤销它已经产生的外部变化，重试必须了解实际完成到了哪里。

快速验证

下面实验单独检查一项汇总门禁决定：只有前置作业的结果严格等于 success 才接受。在真实工作流中，这个值应来自 needs.test.result，并通过 needs 声明前置依赖。这里的输入则刻意采用合成状态，是本地判断练习，不是工作流校验器，也不能替代项目真实测试。它不会安装工作流或启动托管运行，只让这一项判定逻辑能够独立复现。

把下面仅用标准库的探针保存为 gate_check.py，在有 Python 3 和 Bash 的环境运行 python3 gate_check.py。它向同一条 Shell 判断传入合成结果，并包括一个故意失败的测试断言。程序不写文件，不访问任何服务，也不使用真实仓库凭据；需要的解释器和 Shell 必须已经可用。

import os
import subprocess
import sys

subprocess.run([sys.executable, "-c", "assert 2 + 2 == 4"], check=True)
negative = subprocess.run([sys.executable, "-c", "assert 2 + 2 == 5"],
 capture_output=True, text=True)
assert negative.returncode != 0 and "AssertionError" in negative.stderr
print("test-negative-control: rejected")
command = 'test "$TEST_RESULT" = success'
for result in ("success", "failure", "cancelled", "skipped", "", "unexpected"):
 run = subprocess.run(["bash", "--noprofile", "--norc", "-c", command],
 env={"PATH": os.environ["PATH"], "TEST_RESULT": result},
 capture_output=True, text=True)
 accepted = run.returncode == 0
 assert accepted == (result == "success"), (result, run)
 print(f"{result or '<missing>'}: {'accept' if accepted else 'reject'}")
print("PASS: local predicate only; GitHub enforcement not exercised")

预期故意失败的测试被拒绝，只有 success 被接受，最后输出范围提醒。缺失、异常、失败、取消及跳过结果都不能被当成真实成功。这证明了本地命令和拒绝分支，但没有解析任意 YAML、求值 GitHub 表达式、调度作业、读取仓库规则，也没有证明线上合并会被阻止。这些仍需针对真实仓库配置进行托管集成检查，不能用离线探针的成功代替。

来源

GitHub：工作流语法，依赖、条件和令牌权限继承，已核验 2026-10-15。
GitHub：Actions 入门，工作流、事件、作业和步骤，已核验 2026-10-15。
GitHub：排查必需状态检查，版本身份、跳过检查和合并队列，已核验 2026-10-15。
GitHub：工作流事件，复刻请求和高权限触发器的边界，已核验 2026-10-15。
GitHub：依赖缓存，分支与合并请求缓存范围，已核验 2026-10-15。
GitHub：使用秘密，秘密可用性与日志处理，已核验 2026-10-15。

systemd timer 安排服务启动，不保证任务成功

Mon, 21 Jun 2027 00:00:00 +0000

systemd timer 把调度规则与执行工作的服务分开。定时器决定何时请求激活，服务则定义命令、执行身份、环境、超时和结果。因此，维护任务可以使用普通单元工具检查，但一个按时发出的启动请求，并不能证明备份、清理或报表已经正确完成。调度是否运转与工作是否成功，需要不同证据；只有两者都符合要求，周期任务才真正达到目的。

坏掉的样子

活动的定时器可以与失败的服务同时存在。如果监控只检查 timer 是否活动，就会漏掉真正执行工作的失败。同样，最近触发时间只说明调度发生过，不代表业务输出成功。应检查服务结果，以及任务本来要生成的产物或状态变化，并保留足够上下文区分前后两次激活，避免把昨天留下的文件误当成今天任务已经完成。

除非通过 Unit 指向别的目标，定时器通常激活同名的 service。如果目标服务已经活动，就不会再启动另一份独立副本。这阻止的是同一个单元重叠激活，不是分布式锁，也不能阻止另一个服务执行相同命令。oneshot 如果使用 RemainAfterExit=yes 保持活动，后续计划执行就可能一直不再运行命令；保留状态是否合适，取决于任务真正需要表达什么。

停止定时器会停止后续调度，但不会自动停止已经开始的服务调用。事故期间暂停维护工作时，这个区别尤其重要：需要检查目标服务，再有意决定让当前工作结束还是中断它。即使停止命令成功，先前已经发生的文件或数据库修改也不会因此自动回滚，因此不能把“停了 timer”当成系统已经没有维护副作用。

快速验证

在 PID 1 为 systemd 的一次性 Linux 系统中，以管理员身份运行下面的 Python 脚本。实测环境是 Debian 12、systemd 252.39。它创建唯一命名的定时器与服务，以及临时工作程序。工作程序记录真实进程进入和完成时刻，成功任务则通过显式释放文件等待，以便直接观察调度行为：

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,time,uuid

name='xbcatm-timer-'+uuid.uuid4().hex[:8];service=name+'.service';timer=name+'.timer'
paths={unit:Path('/run/systemd/system')/unit for unit in (service,timer)}
assert all(not p.exists() for p in paths.values())
def run(*args):
 result=subprocess.run(args,text=True,capture_output=True,timeout=10)
 assert result.returncode==0,(args,result.stderr)
 return result.stdout.strip()
def value(unit,key):return run('systemctl','show',unit,'-p',key,'--value')
def wait_for(check):
 deadline=time.monotonic()+5
 while not check():
 assert time.monotonic()<deadline,'transition timed out'
 time.sleep(0.02)
with TemporaryDirectory(prefix=name+'-',dir='/run') as directory:
 root=Path(directory);worker=root/'worker.py'
 worker.write_text(r'''from pathlib import Path
import json,sys,time
root=Path(__file__).parent;number=len(list(root.glob('start-*.json')))+1
def record(kind):
 temp=root/'record.tmp';temp.write_text(json.dumps(time.monotonic()))
 temp.replace(root/(kind+'-'+str(number)+'.json'))
record('start')
if (root/'fail').exists():sys.exit(7)
while not (root/('release-'+str(number))).exists():time.sleep(0.01)
record('end')
''')
 paths[service].write_text(f'[Service]\nType=oneshot\nTimeoutStartSec=10s\nExecStart=/usr/bin/python3 {worker}\n')
 definition='[Timer]\nOnActiveSec=100ms\nOnUnitInactiveSec=10s\nAccuracySec=1ms\n'
 paths[timer].write_text(definition);(root/'fail').touch()
 try:
 run('systemd-analyze','verify',*[str(p) for p in paths.values()])
 run('systemctl','daemon-reload');run('systemctl','start',timer)
 wait_for(lambda:value(service,'ActiveState')=='failed')
 assert value(service,'ExecMainStatus')=='7' and value(timer,'ActiveState')=='active'
 run('systemctl','stop',timer)
 print('timer active while its first job failed with exit status 7')
 (root/'fail').unlink();run('systemctl','reset-failed',service)
 paths[timer].write_text(definition.replace('OnUnitInactiveSec=10s','OnUnitInactiveSec=250ms'))
 run('systemctl','daemon-reload');run('systemctl','start',timer)
 wait_for(lambda:(root/'start-2.json').exists())
 time.sleep(0.65)
 assert len(list(root.glob('start-*.json')))==2
 (root/'release-2').touch();wait_for(lambda:(root/'start-3.json').exists())
 gap=json.loads((root/'start-3.json').read_text())-json.loads((root/'end-2.json').read_text())
 assert gap>=0.25,gap
 print('no overlapping launch; next job starts at least 250ms after prior deactivation')
 pid=value(service,'MainPID');assert pid!='0'
 run('systemctl','stop',timer)
 assert value(service,'MainPID')==pid and value(service,'ActiveState')=='activating'
 print('stopping timer leaves its already running oneshot alive')
 (root/'release-3').touch();wait_for(lambda:value(service,'ActiveState')=='inactive')
 time.sleep(0.4)
 assert len(list(root.glob('start-*.json')))==3 and value(service,'Result')=='success'
 print('released job completes; stopped timer schedules no further run')
 finally:
 run('systemctl','stop',timer,service)
 for unit,path in paths.items():
 if value(unit,'ActiveState')=='failed':run('systemctl','reset-failed',unit)
 path.unlink()
 run('systemctl','daemon-reload')

第一次触发的工作进程故意以状态七退出，服务变为失败，定时器却继续活动。此时相对服务结束的下一次间隔先设置为十秒，让脚本有时间检查这个状态，并在再次尝试前停止定时器。结果证明调度器完全可能正常工作，而它安排的业务任务一直失败；仅凭 timer 状态不能得出任务可靠的结论。

修正样本的故障条件后，脚本清除失败状态，把间隔改为二百五十毫秒，再次启动调度。第二个工作进程在释放门槛处等待，即使超过两个名义间隔，也没有第三个进程出现。因为 OnUnitInactiveSec 从服务结束活动时计算，尚未完成的工作还没有提供那个参考事件；它不是简单从上次进程启动就开始固定倒计时。

释放第二个工作进程后，它完成执行，第三个进程才开始，且与前一完成标记至少相隔配置的间隔。真正的单元结束活动发生在该标记之后，因此断言验证的是“相对完成”的关系，不要求某个容易受调度影响的精确启动时间。实验使用 AccuracySec=1ms 减少短间隔下的合并延迟，但这不构成实时执行保证，机器负载仍然可能推迟工作开始。

脚本在第三个进程继续等待时停止定时器，进程编号没有变化，oneshot 仍处于激活中。只有释放这个工作进程，服务才成功完成。再经过一个间隔，调用次数保持不变，说明已停止的 timer 没有继续安排工作。最后清理双方运行时单元与临时程序；暂停计划和结束当前执行的不同效果，都有真实进程状态作为证据。

同时迁移执行契约

从 cron 迁移任务时，不能只翻译时间表达式。还应检查工作目录、明确的命令路径、必要环境、合适的运行用户与执行时限。systemd 命令行不会隐式成为 shell 程序；管道、重定向和 shell 展开，需要有意调用 shell，或放入行为已经验证的独立脚本。否则同一段看似熟悉的命令，可能在新的执行环境中改变含义。

安装与激活也应区分。手动启动一次运行时定时器，不等于配置开机启用；启用服务本身，又可能额外引入一次不需要的开机运行。应按部署策略安装和启用 timer，再检查已载入定义与下次触发时间，并让服务可以独立受控执行，以便诊断真实工作流程。调度入口与人工诊断入口应遵守相同的执行契约。

失败如何重试、如何报告，需要另外决定。下一个 timer 事件可能再次尝试，服务的重启设置又有自己的规则与限制；两者叠加之前，应明确实际会发生几次调用。让重复副作用安全，并保留绑定真实结果的最近成功信号。运维目标是让有用工作在规定窗口内完成，而不是只得到一个长期显示活动的定时器。

来源

systemd 252 systemd.timer，目标选择、目标活动时的行为与相对完成间隔，已核验 2026-09-12。
systemd 252 systemd.service，oneshot 生命周期、保留状态、执行失败与超时，已核验 2026-09-12。
systemd 252 systemctl，启动、停止、启用以及检查定时器与服务单元，已核验 2026-09-12。

Ansible 任务可以声明可重复收敛的目标状态

Sun, 17 Jan 2027 00:00:00 +0000

Ansible 的 playbook 按顺序编排任务。具有状态感知能力的模块可以记录机器应该拥有的状态，在部署中途失败后比较真实现状并补齐差异。收敛来自所选模块与参数，并不是执行引擎保证任何任务重跑都安全。它是一份可以执行的契约：inventory 决定对象，模块实现比对，操作者审阅即将发生的变化。

只写终点，不写每一步

命令式 shell 脚本会说“按顺序执行这些命令”；面向状态的任务则说“这个包应该已安装、这个文件应该是这些字节、这个服务应该启用并运行”。模块在动作前比较目标主机与目标状态，已经满足的任务报告 ok，只有不一致才报告 changed。同一份声明可以用于全新的机器、只配置了一半的机器，也可以用于被人手工改过的机器。

这里的目标不能只是模糊意图。state: present、模板的精确内容、所有者和权限、服务的 enabled/running 都是契约的一部分。把多台机器共用的值放到变量或 role 没问题，但最终值应该对审阅者可见。隐藏的默认值，或者绕过模块直接改变状态的命令，都会让这份契约难以推理。每一个 task 都应回答“运行完成后应该看到什么”，而不是“我习惯先敲哪一条命令”。

模块让重跑逐渐收敛

多数内置模块都围绕幂等性设计。ansible.builtin.copy 会先比较文件内容和元数据，只有不同才替换；ansible.builtin.package 向包管理器询问目标状态；ansible.builtin.service 使用 state: started 时只在运行状态不符时调整；state: restarted 则要求每次运行都重启。第二次运行应该是一份安静的确认，而不是再次重启、追加重复行或再写一条记录。幂等不是“什么都不做”，而是“已经达到目标，所以没有必要再做”。

并非所有动作天然幂等。直接用 command 创建用户、轮换密钥或调用外部 API，若没有条件限制就会重复副作用。优先找专用模块；没有时先 register 查询结果，再用 when 判断是否执行，或者使用精确的 creates/removes 文件条件。changed_when 只决定变更报告和 handler 通知，不控制任务是否执行；设成 false 不能阻止重复变更，还可能隐瞒真实副作用。对外部接口仍要定义超时、重试与部分成功后的恢复方法，不能把网络调用假装成普通文件复制。

Inventory 是地图

playbook 描述结果，inventory 选择主机，变量提供上下文。ansible_user 选择登录身份，SSH agent 或 Vault 提供认证材料，避免将明文秘密提交到仓库。组变量让同一份声明覆盖整支机器队伍，同时保留端口、区域等主机差异。在 CI 中使用显式 inventory，避免“localhost”意外指向执行器本身。执行前打印解析后的主机集合，确认别名、组继承和变量优先级都与审阅时一致。

--check（检查模式）要求模块预测变化但不真正应用，--diff 则为支持它的模块显示内容差异。预测不是证明：不支持检查模式的模块可能跳过工作，任务级的 check_mode: false 还会在 --check 下真正执行。需要审阅这种覆盖设置，秘密也不应出现在 diff。把检查报告当成审阅材料，再用同一份 inventory 运行正常模式，并把结果记录在部署记录中。检查模式发现的差异还需要解释来源，是首次安装、配置漂移，还是模板变量变化。

坏掉的样子

任务调用 shell、模块的 check mode 不完整，或者未锁定版本的包明天解析出另一版，都会让机器继续漂移。某台主机失败可能留下部分已变更的机群；serial 限制批次，却不提供自动回滚。应明确每批通过条件、失败时 handler 是否运行，以及恢复方案。依赖前一任务事实的动作必须显式表达依赖，不能靠偶然的排列顺序。把多个不相关的副作用塞进一个 task，也会让失败后的重试难以判断到底完成了哪一半。

另一个常见故障是范围弄错：localhost, 配合 local 连接会操作执行器本机，而 all 选择实际 inventory 中匹配的全部主机，并不会自动纠正错误对象。语法检查只能发现 YAML 错误，不能发现目标选错。审阅解析后的 inventory 和 --list-hosts，再跑 check mode。幂等性也只覆盖系统边界；数据库迁移和云 API 仍需要各自的事务与重试语义。不要因为第二次运行显示 ok，就推断外部系统一定已经达到相同状态。

还要警惕变量优先级造成的“看起来声明了，实际被覆盖”。命令行变量、组变量、主机变量和 role 默认值有明确的优先级；ansible-inventory --host 只能帮助检查 inventory 变量，仍须结合 playbook 和命令行覆盖理解任务实际收到的值。并行策略会改变多个主机同时失败时的影响面，滚动发布则需要为每一批定义通过条件。把变更摘要、失败主机和未执行任务写入构建产物，下一次重跑才知道哪些状态已经落地。对包含秘密的任务设置 no_log 和 diff: false，避免把秘密放进结果或差异日志。最后，升级 ansible-core 或 collection 后要重新跑同一夹具，因为模块默认值和检查模式支持可能变化。

快速验证

把下面的 YAML 保存为 site.yml，Python 保存为同目录的 verify_ansible.py，再运行 shell 命令。实验使用本地连接，只操作临时文件；它先建立隔离虚拟环境，再执行语法检查、缺失文件的 check mode、正常收敛、漂移预览和修复。

python3 -m venv .venv-ansible
.venv-ansible/bin/python -m pip install ansible-core==2.21.4
.venv-ansible/bin/python verify_ansible.py

- name: Converge a disposable local file
 hosts: localhost
 connection: local
 gather_facts: false
 tasks:
 - name: Declare the banner content and mode
 ansible.builtin.copy:
 dest: "{{ fixture }}"
 content: "managed by ansible\n"
 mode: "0644"

import json
import os
from pathlib import Path
import re
import stat
import subprocess
import sys
import tempfile

playbook = Path(__file__).with_name("site.yml").resolve()
ansible = Path(sys.executable).parent / "ansible-playbook"
print(subprocess.check_output([str(ansible), "--version"], text=True).splitlines()[0])
with tempfile.TemporaryDirectory(prefix="ansible-state-") as directory:
 work = Path(directory)
 banner = work / "banner"
 config = work / "ansible.cfg"
 config.write_text("[defaults]\nstdout_callback=default\n", encoding="utf-8")
 env = dict(os.environ, ANSIBLE_CONFIG=str(config), ANSIBLE_NOCOLOR="1",
 ANSIBLE_LOCAL_TEMP=str(work / "local-tmp"))
 variables = {"fixture": str(banner), "ansible_python_interpreter": sys.executable,
 "ansible_remote_tmp": str(work / "module-tmp")}
 command = [str(ansible), "-i", "localhost,", str(playbook),
 "--extra-vars", json.dumps(variables)]

 def run(*options):
 result = subprocess.run(command + list(options), cwd=work, env=env,
 check=True, text=True, capture_output=True, timeout=60)
 print(result.stdout)
 return result.stdout

 def changed(expected, *options):
 output = run(*options)
 recap = re.search(r"localhost\s+:\s+ok=(\d+)\s+changed=(\d+)\s+"
 r"unreachable=(\d+)\s+failed=(\d+)", output)
 assert recap and tuple(map(int, recap.groups())) == (1, expected, 0, 0)
 return output

 run("--syntax-check")
 assert "managed by ansible" in changed(1, "--check", "--diff")
 assert not banner.exists(), "check mode created the absent file"
 changed(1)
 assert banner.read_bytes() == b"managed by ansible\n"
 assert stat.S_IMODE(banner.stat().st_mode) == 0o644
 changed(0)
 banner.write_bytes(b"manual drift\n")
 before = (banner.read_bytes(), banner.stat().st_mtime_ns, banner.stat().st_mode)
 diff = changed(1, "--check", "--diff")
 assert "manual drift" in diff and "managed by ansible" in diff
 assert before == (banner.read_bytes(), banner.stat().st_mtime_ns, banner.stat().st_mode)
 changed(1)
 assert banner.read_bytes() == b"managed by ansible\n"
 changed(0)
print("PASS: syntax, absent-file preview, convergence, drift preview, and repair")

在 Ansible Core 2.21.4 中，语法检查成功；缺失文件的 check mode 报告 changed=1 但不创建文件，正常运行创建文件，第二次运行报告 changed=0。手工写入 manual drift 后，--check --diff 显示前后内容而不改变文件字节、权限或修改时间，正常运行修复漂移，随后再次收敛为 changed=0。这些断言证明的是这一项 copy 任务的行为；其他模块和版本升级仍需各自检查，真实发布也仍须审阅主机模式、权限与秘密的 diff 策略。

来源

Ansible playbook 入门，playbook 结构、任务与目标状态，已核验 2026-09-09。
Ansible 检查模式与 diff 模式，预测变化和预览差异，已核验 2026-09-09。
Ansible 错误处理，变更报告与 handler 通知，已核验 2026-09-10。
Ansible service 模块，started 与 restarted 的行为差异，已核验 2026-10-15。

为 systemd 定时器选对时钟和补跑规则

Fri, 20 Nov 2026 00:00:00 +0000

一份计划必须先说清楚“时间”是什么意思。“纽约每天早上九点”指向民用日历，“任务结束十五分钟后”则指向经过时长和一个参考事件。systemd timer 同时支持这两类表达，但它们使用的时钟与起算点不同，在时区变化、系统休眠和定时器停用期间会表现出不同结果。只把它们统称为周期调度，会隐藏本来应该由需求决定的差别。

坏掉的样子

OnCalendar 按墙钟日历表达式触发，省略时区通常使用系统本地时区，因此同一份配置在不同机器上可能代表不同实际时刻。夏令时规则变化时，每天相同的本地时间也可能相对 UTC 移动。应使用固定参考日期预览预期表达式，而不是把今天的 UTC 偏移当成全年不变的事实。调度语法能解析，只证明表达式有效，不证明它符合业务要求的地区时间。

单调计时选项明确命名参考事件。OnActiveSec 从 timer 本身激活起算，OnStartupSec 从服务管理器启动起算，OnUnitInactiveSec 从目标单元结束活动起算。这些并不是“隔几分钟运行”的可互换写法。普通单调计时在系统休眠期间暂停，WakeSystem 会改变时钟选择，并依赖平台支持。因此是否计入休眠时间，也应该属于调度需求，而不是部署后的偶然发现。

Persistent=yes 对日历计时器生效。它记录触发时刻，在定时器恢复活动且至少错过一个事件时请求一次补触发；不会逐次重放所有错过的日历时刻，也不能证明上次业务执行成功。如果配置了随机延迟，补触发仍受其影响。触发历史不是一条持久业务队列，不能据此推定停机期间应做的所有工作都已完整保存。

快速验证

在 PID 1 为 systemd、安装了时区数据库的一次性 Linux 系统中，以管理员身份运行下面的 Python 脚本。记录中的环境为 Debian 12、systemd 252.39。脚本先预览日历表达式，再安装两个唯一命名的定时器与服务组合，双方使用同样三个即将到来的日历时刻，全程不会调整机器时钟：

from pathlib import Path
from tempfile import TemporaryDirectory
from datetime import datetime,timezone
import subprocess,time,uuid

name='xbcatm-calendar-'+uuid.uuid4().hex[:8]
names=[name,name+'-plain'];paths=[]
def run(*args):
 result=subprocess.run(args,text=True,capture_output=True,timeout=10)
 assert result.returncode==0,(args,result.stderr)
 return result.stdout.strip()
preview=run('systemd-analyze','calendar','--base-time=2026-03-07 00:00:00 UTC',
 '--iterations=3','*-*-* 09:00:00 America/New_York')
for expected in ('2026-03-07 14:00:00 UTC','2026-03-08 13:00:00 UTC','2026-03-09 13:00:00 UTC'):
 assert expected in preview,preview
print('09:00 New York: 14:00 UTC before spring DST, 13:00 UTC after it')
with TemporaryDirectory(prefix=name+'-',dir='/run') as directory:
 root=Path(directory);worker=root/'worker.py'
 worker.write_text("from pathlib import Path\nimport sys\np=Path(sys.argv[1])\nwith p.open('a') as output:output.write('run\\n')\n")
 now=int(time.time());events=[now+3,now+4,now+5]
 calendar=''.join('OnCalendar='+datetime.fromtimestamp(t,timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')+'\n' for t in events)
 try:
 for index,prefix in enumerate(names):
 service=Path('/run/systemd/system')/(prefix+'.service');timer=service.with_suffix('.timer')
 assert not service.exists() and not timer.exists()
 service.write_text(f'[Service]\nType=oneshot\nExecStart=/usr/bin/python3 {worker} {root}/{index}.log\n');paths.append(service)
 timer.write_text('[Timer]\n'+calendar+'AccuracySec=1ms\nRandomizedDelaySec=0\nPersistent='+('yes' if index==0 else 'no')+'\n');paths.append(timer)
 run('systemd-analyze','verify',*[str(p) for p in paths]);run('systemctl','daemon-reload')
 run('systemctl','start',name+'.timer');run('systemctl','stop',name+'.timer')
 assert not (root/'0.log').exists() and time.time()<events[0]
 while time.time()<events[-1]+0.15:time.sleep(0.05)
 run('systemctl','start',name+'.timer',name+'-plain.timer')
 deadline=time.monotonic()+3
 while not (root/'0.log').exists():
 assert time.monotonic()<deadline,'catch-up did not run';time.sleep(0.02)
 time.sleep(0.15)
 assert (root/'0.log').read_text()=='run\n' and not (root/'1.log').exists()
 print('three elapsed calendar events: persistent timer catches up once; plain timer does not')
 run('systemctl','stop',name+'.timer');run('systemctl','start',name+'.timer')
 time.sleep(0.2);assert (root/'0.log').read_text()=='run\n'
 print('reactivating with no newly missed event does not replay the job')
 print('timer inactivity was tested without changing the system clock or rebooting')
 finally:
 if paths:
 run('systemctl','stop',*[p.name for p in paths])
 run('systemctl','clean','--what=state',name+'.timer')
 for path in paths:path.unlink(missing_ok=True)
 run('systemctl','daemon-reload')

预览从二〇二六年三月夏令时切换前的固定日期开始，询问纽约早上九点的后续发生时刻。第一次对应 UTC 十四点，后两次对应 UTC 十三点，本地钟表时间却始终是九点。这检查的是日历解释，并不是修改主机时区，也不是把系统时间跳到那些日期。对指定地区的每日任务而言，这种偏移变化可能正是正确行为。

持久化 timer 在第一个实验时刻到来前先启动，再停止；首次启动建立它的时间戳状态。停用期间，三个指定时刻全部经过。再次激活时，它恰好运行一次服务，结果文件只有一行。非持久化 timer 同样在这些时刻之后才激活，却没有生成结果文件。因此差别来自已经实际存在的停用区间及对应补触发策略，而不是两份命令做了不同的工作。

这个实验真实经历了定时器停用，没有手工修改时间戳文件来伪装漏跑，也不需要重启机器。三个过去事件合并为一次激活；如果应用必须处理三个独立结算周期，就需要自己发现并记录这些周期。不能让“已经补跑一次”的系统状态替代业务层对遗漏范围和处理结果的判断。

随后再次停止并启动持久化 timer，结果文件没有新增行，因为期间没有新的事件被错过。清理时先停止运行时单元，再通过 systemctl clean --what=state 删除持久化 timer 的状态；非持久化 timer 没有对应状态资源，不执行这项清理。最后删除配置文件和无害结果目录，让生命周期验证包括本次创建资源的实际回收。

实验把 AccuracySec 设为一毫秒，随机延迟设为零，让较短的过程容易观察。但这些设置不保证任意负载下进程都在精确时刻开始。代码会在有限等待窗口内观察实际完成，并断言调用次数，而不是把预测截止时间直接当成命令已经执行。计划时刻、管理器发出激活请求和程序开始运行，本来就是不同事件。

明确哪些漏掉的工作必须补齐

对于备份，停机后生成一份新的快照可能符合恢复策略；对于计费，每个遗漏周期可能都需要独立核对。这种差别应放进应用状态与幂等规则。服务在 timer 到点时已经活动，不会自动复制成另一个实例；保留活动状态的 oneshot，也可能阻止命令再次运行。因此补触发能力必须与目标服务生命周期一起考虑，不能只看 timer 配置。

检查调度时应查看已载入配置和下次、上次触发属性，检查执行时则查看目标服务结果。日历 timer 排在时间相关 target 之后，本身并不证明远端时间源已经完成校时；如果业务需要这个保证，实际时间服务配置必须提供它。只有顺序关系，没有兑现条件的服务，就不能当成可靠的同步屏障。

依赖一份计划之前，应验证有代表性的日期与生命周期变化，包括时区边界、定时器禁用和任务预期耗时。经过时长需求选择合适的单调参考事件，民用时间需求选择明确地区的日历规则。同时把“有用工作已完成”的证据与“管理器发出过触发”的证据分别保存，才能解释计划正确却业务结果缺失的情况。

来源

systemd 252 systemd.timer，参考时钟、日历持久化、精度与随机延迟，已核验 2026-09-12。
systemd 252 systemd.time，日历表达式与具名时区语法，已核验 2026-09-12。
systemd 252 systemd-analyze，固定参考时间的日历预览与多次发生时刻，已核验 2026-09-12。
systemd 252 systemctl，定时器激活与持久化状态清理，已核验 2026-09-12。

定时任务需要能够安全重跑

Sat, 15 Aug 2026 00:00:00 +0000

调度器启动的是一次尝试，业务关心的通常是某个逻辑任务是否完成。一笔每日额度可能因为报错、重启或人工补跑而尝试多次。如果每次尝试都生成新的身份，重复执行就无法与新工作区分。应使用能够代表预期任务的键，例如任务名称与名义计划时间，并在修改业务状态之前定义重复键的含义。尝试日志中的唯一编号可以保留，但不能代替业务层面的去重身份。

调度触发与业务执行是两件事

不能假设所有调度器都会补跑遗漏工作。普通 cron 的具体行为随实现变化，没有统一补跑承诺。启用 Persistent=true 的 systemd 日历定时器，在停用期间至少错过一次触发时，可以在重新启用后补触发；这不等于把所有错过的时间点逐个重放。Kubernetes 文档也明确说明，某些情况下 CronJob 可能重复创建 Job，或者没有创建对应任务。

因此要先确定业务规则：过时任务直接跳过、每个缺失周期都处理，还是对当前状态做一次校正。去重键应使用名义上的逻辑周期，并明确时区。实际启动时间会随重试变化，不能用于识别同一次计划工作。诊断需要的尝试编号与业务身份应分开记录，这样才能同时看见执行了几次尝试，以及到底完成了几个逻辑周期。

坏掉的样子

先查询有没有处理过，再单独修改数据，存在竞态。两个工作进程可能都看到键不存在，然后都应用业务效果。进程锁也许能阻止一台机器上的重叠运行，却不能让业务更新与完成标记文件自动形成原子操作。如果更新成功后、写标记之前失败，重试就会重复生效；先写标记再执行业务，则可能把尚未发生的工作误记为完成。调整两个步骤的先后顺序不能消除中间窗口。

当业务状态与完成记录位于同一个事务数据库时，应在唯一约束下共同提交。提交之前失败，两者都不应留下；提交之后重试，应识别已经完成的逻辑键。SQLite 的 BEGIN IMMEDIATE 会提前开始写事务，其他写入者可能等待，也可能因为繁忙而失败。超时限制等待长度，并不保证任何并发量下都不会冲突；调用方仍需正确区分重试、失败和重复完成。

这个原子性边界不覆盖外部邮件、支付或 HTTP 调用。本地回滚无法撤销远端已经接受的效果。此类流程需要远端提供合适的幂等契约，或采用持久投递设计并在接收方去重。同一个键如果可能携带不同负载，还需要明确拒绝这种冲突的规则。下面示例始终增加固定额度，因此只验证同一逻辑操作的重复尝试，没有把变更参数的重用键视为新请求。

快速验证

本轮以 Python 3.12.14 与 SQLite 3.53.1 完整运行下列示例，实际使用临时数据库与并发线程。

保存为 idempotent-jobs.py 后运行 python3 idempotent-jobs.py。脚本使用临时 SQLite 数据库和八个工作线程，每个线程建立独立数据库连接。业务效果是给余额增加十个单位；非空主键记录已经完成的每日逻辑额度发放，并与余额修改处于同一个事务中。实验不需要实际修改系统定时器，也不会访问外部服务。

from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
from tempfile import TemporaryDirectory
from threading import Barrier
import json
import sqlite3

with TemporaryDirectory() as directory:
 database = str(Path(directory) / 'jobs.db')
 with sqlite3.connect(database) as connection:
 connection.executescript('''
CREATE TABLE balance (id INTEGER PRIMARY KEY, units INTEGER NOT NULL);
INSERT INTO balance VALUES (1, 0);
CREATE TABLE completed (logical_key TEXT PRIMARY KEY NOT NULL);
''')

 def run(key, fail=False, gate=None):
 connection = sqlite3.connect(database, timeout=10, isolation_level=None)
 try:
 if gate:
 gate.wait(timeout=5)
 connection.execute('BEGIN IMMEDIATE')
 inserted = connection.execute(
 'INSERT INTO completed VALUES (?) ON CONFLICT(logical_key) DO NOTHING', (key,))
 if not inserted.rowcount:
 connection.execute('COMMIT')
 return 'duplicate'
 connection.execute('UPDATE balance SET units = units + 10 WHERE id = 1')
 if fail:
 raise RuntimeError('injected failure before commit')
 connection.execute('COMMIT')
 return 'applied'
 except Exception:
 if connection.in_transaction:
 connection.execute('ROLLBACK')
 raise
 finally:
 connection.close()

 key = 'daily-credit:2026-09-13T00:00:00Z'
 try:
 run(key, fail=True)
 except RuntimeError as error:
 assert str(error) == 'injected failure before commit'
 with sqlite3.connect(database) as connection:
 assert connection.execute('SELECT units FROM balance').fetchone() == (0,)
 assert connection.execute('SELECT count(*) FROM completed').fetchone() == (0,)
 gate = Barrier(8)
 with ThreadPoolExecutor(max_workers=8) as pool:
 results = list(pool.map(lambda _: run(key, gate=gate), range(8)))
 assert results.count('applied') == 1 and results.count('duplicate') == 7
 assert run(key) == 'duplicate'
 assert run('daily-credit:2026-09-14T00:00:00Z') == 'applied'
 with sqlite3.connect(database) as connection:
 units = connection.execute('SELECT units FROM balance').fetchone()[0]
 completed = connection.execute('SELECT count(*) FROM completed').fetchone()[0]
 assert (units, completed) == (20, 2)
 print(json.dumps({'rolled_back_attempt_left_no_state': True,
 'concurrent_applied': results.count('applied'),
 'concurrent_duplicates': results.count('duplicate'),
 'final_units': units, 'completed_logical_jobs': completed}))

第一次尝试在完成插入和余额更新之后、提交之前故意抛出异常。脚本验证回滚之后余额仍为零，也不存在完成键。随后八个工作线程同时处理同一个逻辑时间点，必须只有一个返回 applied，另七个返回 duplicate。唯一键判断与业务修改依靠真实数据库串行化，不是通过假的内存锁预先安排好结果。并发开始屏障让竞争条件实际存在。

成功提交后再重放同一个键，仍然是重复；换成下一个名义日期，才是新的逻辑任务，并再次增加十个单位。最终余额应为二十，完成键应为两个。这个结果覆盖单个 SQLite 数据库中的回滚、并发去重和提交后重放，没有验证调度器一定送达、进程被强制终止时的恢复，也没有证明外部系统的效果可以恰好发生一次。

让失败与完成都能被看见

记录逻辑键、每次尝试的结果、耗时与最近成功完成的业务周期。正常重复与数据库错误要区分；如果捕获所有异常后都标成完成，就会把丢失工作隐藏起来。还要定义完成记录需要保存多久，删除记录后再收到旧重试，可能重新应用业务效果。可用的运行证据应让值班人员判断预期周期是否完成，而不只是证明定时器曾经启动过某个进程。

来源

SQLite: transactions，写入串行化、提交和回滚语义，已核验 2026-10-15。
SQLite: UPSERT，针对指定唯一约束冲突的处理，已核验 2026-10-15。
systemd.timer，持久日历定时器补触发的适用范围，已核验 2026-10-15。
Kubernetes: CronJob，近似调度以及重复或遗漏任务的可能性，已核验 2026-10-15。

自动化 · XB 现场笔记

Horizontal Pod Autoscaler 依赖明确的指标语义

区分测量与控制

选择增加副本能够改善的信号

副本字段要有明确负责人

坏掉的样子

快速验证

延伸阅读

来源

Cron 按日历重复触发任务

把字段理解为日历选择

坏掉的样子

快速验证

来源

GitHub Actions 工作流给构建把门槛

区分执行与强制要求

明确依赖结果

权限声明约束令牌，不约束所有凭据

坏掉的样子

快速验证

延伸阅读

来源

systemd timer 安排服务启动，不保证任务成功

坏掉的样子

快速验证

同时迁移执行契约

延伸阅读

来源

Ansible 任务可以声明可重复收敛的目标状态

只写终点，不写每一步

模块让重跑逐渐收敛

Inventory 是地图

坏掉的样子

快速验证

延伸阅读

来源

为 systemd 定时器选对时钟和补跑规则

坏掉的样子

快速验证

明确哪些漏掉的工作必须补齐

延伸阅读

来源

定时任务需要能够安全重跑

调度触发与业务执行是两件事

坏掉的样子

快速验证

让失败与完成都能被看见

来源