.NET Core 控制台程序在 K8s 上的优雅停机(graceful shutdown):没有“流量”可摘时,该怎么做?

文章目录
- .NET Core 控制台程序在 K8s 上的优雅停机(graceful shutdown):没有“流量”可摘时,该怎么做?
-
- 先厘清:没有流量,那“优雅”的定义是什么?
- .NET Core 的优雅停机基础:Generic Host 已经替你做了第一层
- 三种任务类型,三种不同的收尾策略
-
- 类型 A:可中断、可重跑的短任务
- 类型 B:须完成、有副作用的短/中等任务
- 类型 C:时长不可预测的长任务(分钟级以上)
- 类型 A:可中断、可重跑的短任务
- K8s 侧:`preStop` 是“窗口”,宽限期是“硬上限”
- 几个应该避免的反模式
- 一份可以照着走的落地清单
把 .NET Core 控制台程序(定时任务调度器)部署到 Kubernetes 后,你很快会发现:那套 Web 应用熟悉的 readinessProbe + preStop sleep 组合,在这里几乎派不上用场。Pod 不在 Service 的 Endpoints 里,没有“流量可摘”;preStop 中的 sleep 15 也只不过把问题往后推了 15 秒——一个正在跑的长任务并不会因为这 15 秒的缓冲就变得“可以安全中断”。
定时任务程序的优雅停机,需要换一套问题框架来回答。
先厘清:没有流量,那“优雅”的定义是什么?
对于 Web 服务,“优雅”的核心是排干在途 HTTP 请求。请求的粒度是毫秒到秒级,排干之后即可退出。对于定时任务程序,“在途工作”是一轮正在执行的 Job:它可能在访问数据库、可能在调用外部 API,执行时长从几秒到几十分钟不等。
因此,定时任务 Pod 的“优雅”定义应该变成:收到终止信号后,停止触发新的 Job,妥善处置当前正在运行的 Job,然后主动退出。这句话拆开来看是三个独立的问题:
- 停止调度:应用不能再在停机过程中“手滑”启动下一轮 Job;
- 处置当前 Job:根据任务性质,选择“等它跑完”“通知它收尾”或“保存进度后放弃”;
- 主动退出:在 K8s 宽限期耗尽之前,应用自己决定什么时候结束,而不是被动等
SIGKILL。
下面从 .NET Core 的运行时机制开始,逐步落到代码模式和 K8s 配置。
.NET Core 的优雅停机基础:Generic Host 已经替你做了第一层
如果你使用的是 .NET Generic Host(Host.CreateDefaultBuilder 或 Host.CreateApplicationBuilder),那么 .NET 6+ 已经在运行时层面处理了 SIGTERM。ConsoleLifetime 会监听 SIGTERM,触发主机停止流程,而不是让进程直接被信号杀死。
这个停止流程会依次做几件事:触发 IHostApplicationLifetime.ApplicationStopping,然后调用所有 IHostedService 的 StopAsync,最后触发 ApplicationStopped,主机退出。对于 BackgroundService,StopAsync 会触发传入 ExecuteAsync 的那个 stoppingToken,并且主机会在 StopAsync 中阻塞等待 ExecuteAsync 完成。
这意味着:你不需要自己注册 PosixSignalRegistration 或 AppDomain.ProcessExit 来“捕获 SIGTERM”。Generic Host 已经把信号翻译成了你代码中可感知的取消令牌。真正的挑战不在于“怎么接住信号”,而在于接住信号之后,你的 Job 循环怎么响应。
三种任务类型,三种不同的收尾策略
你的多个 Job 执行周期和单次时长各不相同,这天然要求差异化处理。把所有 Job 都塞进同一个“等待 60 秒”的模板里,要么短任务被无谓拖慢,要么长任务依然被拦腰截断。
类型 A:可中断、可重跑的短任务
例如一次缓存刷新、一次轻量数据同步。这类任务中断后重跑的成本很低,而且通常幂等或可以设计成幂等。
策略:收到取消令牌后立即退出当前轮次,不做等待。新 Pod 启动后,调度器自然会重新触发。
在 BackgroundService 中,ExecuteAsync 里的循环在每次“等待下一轮”时都应该响应 stoppingToken:
1protected override async Task ExecuteAsync(CancellationToken stoppingToken) 2{ 3 using var timer = new PeriodicTimer(TimeSpan.FromSeconds(30)); 4 while (!stoppingToken.IsCancellationRequested) 5 { 6 try 7 { 8 await DoLightweightJob(stoppingToken); 9 await timer.WaitForNextTickAsync(stoppingToken); 10 } 11 catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested) 12 { 13 break; // 停机导致的取消,安静退出 14 } 15 } 16} 17
关键在于把 stoppingToken 传进 Job 内部的 I/O 调用(数据库、HTTP 客户端)。这样停机信号到达时,正在进行的 ExecuteNonQueryAsync 或 GetAsync 会抛出 OperationCanceledException,循环退出,ExecuteAsync 完成,主机的 StopAsync 随之返回。整个过程不需要额外等待。
类型 B:须完成、有副作用的短/中等任务
例如一次扣款、一次发券、一次对外部系统的不可逆调用。这类任务一旦开始,中途放弃的代价高于等待它完成。
策略:收到取消令牌后停止触发新轮次,但等待当前正在执行的 Job 自然结束。如果任务时长可控(比如不超过 30 秒),等待是完全合理的。
一个显式的模式是:在 BackgroundService 中维护当前执行任务的 Task 引用,在 StopAsync 中“不再启动下一轮,但等待当前轮”:
1public class SideEffectJobService : BackgroundService 2{ 3 private Task? _currentRun; 4 5 protected override async Task ExecuteAsync(CancellationToken stoppingToken) 6 { 7 while (!stoppingToken.IsCancellationRequested) 8 { 9 _currentRun = RunOneJobSafelyAsync(CancellationToken.None); // 注意:Job 内部不传 stoppingToken 10 await _currentRun; 11 12 try 13 { 14 await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken); 15 } 16 catch (OperationCanceledException) { break; } 17 } 18 } 19 20 public override async Task StopAsync(CancellationToken cancellationToken) 21 { 22 // 不再触发新轮次:ExecuteAsync 中的 Delay 会被取消,循环退出 23 await base.StopAsync(cancellationToken); 24 25 // 等待正在执行的当前轮次自然完成 26 if (_currentRun is { IsCompleted: false }) 27 { 28 await Task.WhenAny(_currentRun, Task.Delay(Timeout.Infinite, cancellationToken)); 29 } 30 } 31} 32
这里有一个关键设计:传给 Job 的令牌是 CancellationToken.None,不是 stoppingToken。这意味着停机信号不会在 Job 执行到一半时打断它;Job 照常跑完,然后 ExecuteAsync 的等待环节感知到取消,循环退出。StopAsync 中的 Task.WhenAny 再用主机给的 cancellationToken 作为上限——如果当前 Job 在主机允许的停止预算内跑完了,干净退出;如果没跑完,WhenAny 返回,StopAsync 结束,主机继续走它的关闭流程(最终由 K8s 宽限期或主机自身的 shutdown timeout 兜底)。
类型 C:时长不可预测的长任务(分钟级以上)
这是最棘手的一类。你无法用“等它跑完”来保证,因为“跑完”可能需要 40 分钟,而 K8s 宽限期不可能设成 40 分钟(否则一个卡死的任务会让滚动更新停滞)。对于这类任务,“不中断”是一个错误的目标;“中断后不丢进度”才是正确的目标。
策略:任务内部实现 checkpoint。收到取消令牌时,不追求完成整个 Job,而是在下一个安全点保存当前进度并主动退出;新 Pod 启动后从 checkpoint 恢复,而不是从头开始。
checkpoint 的粒度取决于业务语义:数据库批处理可以记录最后处理的 Id 或时间戳游标;文件/分片处理可以记录已完成的分片号;外部 API 调用序列可以记录已成功调用的步骤索引。退出时的行为从“等完”变成“存好就走”。
同时,幂等是最后的兜底。即使 checkpoint 稍旧、新 Pod 重跑了一小段,唯一约束或条件状态迁移应该保证不会产生重复副作用。checkpoint 减少重做量,幂等保证重做安全——两者配合,才能让你在“不等完整任务”的前提下安心退出。
K8s 侧:preStop 是“窗口”,宽限期是“硬上限”
应用层具备了主动退出的能力之后,K8s 侧配置的逻辑就清晰了。
1spec: 2 terminationGracePeriodSeconds: 90 3 containers: 4 - name: job-runner 5 lifecycle: 6 preStop: 7 exec: 8 command: ["sh", "-c", "sleep 10"] 9
preStop 中的 sleep 在定时任务场景下的含义需要重新理解。它不是“等任务跑完”,而是给应用一个在收到 SIGTERM 之前的短暂窗口,用于让外部调度系统(如果你使用了调度中心)有机会将这个实例标记为下线,或者让某个恰好即将结束的短任务不受干扰地完成。10 秒通常足够,不必更长。
terminationGracePeriodSeconds 是硬上限,不是“等待承诺”。它应该这样反推:
宽限期 >
preStop耗时 + 应用层主动退出逻辑自己设定的最大等待/保存时间
例如:preStop sleep 10,应用层在 StopAsync 中最多等待当前任务 30 秒(通过 Task.WhenAny 带一个 30 秒超时的令牌),则宽限期设为 60–90 秒是合理的,留出了容器内 .NET 主机自身收尾的余量。绝对不要让应用层的等待时间逼近宽限期,否则 SIGKILL 会在应用还没来得及保存 checkpoint 之前到达。
还有一个容易忽略的点:如果主机的 HostOptions.ShutdownTimeout(默认通常较短)小于你应用层需要的等待时间,StopAsync 会被主机自身提前终止。对于需要“等待当前 Job”或“保存 checkpoint”的服务,需要在构建 Host 时显式调整这个值,使其与你的应用层策略匹配,而不是让默认值在背后偷偷截断你的优雅逻辑。
几个应该避免的反模式
不要给定时任务 Pod 硬配 HTTP readinessProbe。它不在 Endpoints 里,探针失败不会“摘流量”,只会制造无意义的未就绪状态和日志噪音。如果要探活,用 exec 检查进程或一个轻量级的内部状态文件即可。
不要把 terminationGracePeriodSeconds 设成覆盖最长任务时长的巨大值。一个卡死的任务会让旧 Pod 长期占用节点,滚动更新“卡住”,而 K8s 的调度和抢占机制并不会因为你设了 1800 秒就尊重你的任务进度。
不要只依赖 preStop sleep 而不改应用代码。sleep 只是在 SIGTERM 之前买时间,它无法让一个不感知取消令牌的 Thread.Sleep 或同步数据库调用变得可中断。应用层的协作取消才是根本。
不要用 Environment.Exit 来“优雅退出”。在 Generic Host 模型中,Environment.Exit 不会走正常的 StopAsync 流程,finally 块和 IHostedService 的清理逻辑都可能被跳过。需要触发停机时,用 IHostApplicationLifetime.StopApplication()。
一份可以照着走的落地清单
- 确认使用 Generic Host,并且没有在
Main中手动吞掉或绕过主机生命周期。ConsoleLifetime已经处理了SIGTERM,你只需要在BackgroundService或IHostedService中正确响应取消令牌。 - 给每个 Job 打标签:可中断可重跑 / 须完成 / 长任务。不同类型采用不同的停止策略,不要一刀切。
- 可中断任务:把
stoppingToken贯穿到 Job 内部的 I/O 调用,让取消真正生效。 - 须完成的中短任务:停机时停止调度新轮次,但等待当前轮自然结束;用显式的
Task引用 + 带超时的WhenAny控制等待上限。 - 长任务:实现 checkpoint + 幂等,退出时“存好就走”,不追求“跑完再走”。
- K8s 配置:
preStop sleep保持短(5–15 秒);terminationGracePeriodSeconds按“preStop+ 应用层主动退出预算 + 余量”反推,不要设得过大。 - 验证:在测试环境用
kubectl delete pod或滚动更新,观察日志确认应用是主动完成StopAsync后退出,而不是在宽限期结束时被SIGKILL(退出码 137 是一个明确的信号:宽限期不够或应用没有响应取消)。
定时任务程序的优雅停机,本质上是一个预算管理问题:K8s 给你一个硬性时间窗口,你需要在应用层决定在这个窗口内做什么——是安静地取消、是等当前任务跑完,还是保存进度后放弃。把这件事想清楚、写进代码,比在 YAML 里调大任何一个参数都更有效。
参考文档
- Primers 编程伙伴/Bash/帮助手册/sleep
- Primers 编程伙伴/Bash/帮助手册/break
- Primers 编程伙伴/Bash/帮助手册/false
- Primers 编程伙伴/Bash/帮助手册/exec
《.NET Core 控制台程序在 K8s 上的优雅停机(graceful shutdown):没有“流量”可摘时,该怎么做?》 是转载文章,点击查看原文。