服务优雅停机完全指南:从一次"一发版就冒 500、用户请求被拦腰斩断"看懂 SIGTERM 与连接排空

2021 年我做一个后端服务,部署、重启这件事我压根没多想。第一版我做得很省事:要发新版本?把旧进程 kill 掉,再起一个新的,不就完了。本地开发时——真不错:Ctrl+C 停掉、改完代码、再跑起来,一气呵成,我从没觉得"停掉一个进程"这件事有什么讲究。我心里很踏实:"重启嘛,不就是杀掉旧的、起来新的?进程而已,说停就停。"可等这个服务真正上线、要在有真实流量时反复发版,一串问题冒了出来。第一种最先把我打懵:每次一发版,监控面板上就准时冒出一波 500 和 502——我反复查代码,逻辑没毛病,可发布那几秒,就是有一批用户的请求凭空失败了。第二种最隐蔽:有一次发版后我对数据,发现库里躺着一条"半截"的数据——一个写操作做到一半,进程就被杀了,事务没走完,留下一条不一致的脏记录。第三种最磨人:我的服务里有个消息队列消费者,某次重启,一条消息正在处理、还没来得及 ack,进程就没了——这条消息要么丢了,要么被下一个实例重复消费了一遍。第四种最反直觉:我以为"kill 之后稍微等一会儿"就能缓解,结果发现两件事——我习惯用的 kill -9 根本不给进程任何反应时间,而就算用普通的 kill,我的进程压根没监听那个信号,等于白等。我盯着这一连串问题想了很久才彻底想明白,第一版错在一个根本的认知上:我以为"停一个服务,就是把进程 kill 掉"。这句话把"停止服务"当成了一个瞬间动作。可它不是。一个正在运行的服务,在你想停它的那一刻,它的身上挂着一大堆"没做完的事":有正在处理、还没返回响应的请求;有打开着的数据库连接、写到一半的事务;有从队列里取出来、还没 ack 的消息;有正在跑的后台任务。你把进程瞬间杀掉,这些事就全部被拦腰斩断——在途请求变成给客户端的 502,半截事务变成脏数据,没 ack 的消息变成丢失或重复。所以"停止服务"根本不是一个瞬间动作,它是一个需要设计的、有先后顺序的过程:先不再接新活,再把手上的活干完,然后按顺序关掉各种资源,最后才退出。这个过程,就叫优雅停机。真正做好服务停机,核心不是"把进程杀掉",而是理解停机是一个有顺序的过程、捕获 SIGTERM 信号、先摘流再排空在途请求、按序关闭资源、并用超时兜底。这篇文章就把服务优雅停机梳理一遍:为什么"kill 掉再起一个"是错的、SIGTERM 信号怎么捕获、怎么摘流并排空在途请求、资源怎么按顺序关闭、超时怎么兜底,以及健康检查摘流、K8s 的 preStop、消息消费者停机这些把停机真正做扎实要避开的坑。

问题背景

先把那串问题的现象和我的误判讲清楚,后面所有的设计都是冲着纠正这个误判去的。

现象:一套"发版就 kill 进程"的服务,上线后冒出一串问题:每次发版,监控就准时冒出一波 500/502;一个写操作做到一半进程被杀,库里留下半截脏数据;消息消费者被杀,一条没 ack 的消息要么丢、要么被重复消费;kill -9 根本不给进程反应时间,而进程又没监听普通 kill 发的信号,等于白等。

我当时的错误认知:"停一个服务,就是把进程 kill 掉,再起一个新的。"

真相:这个认知错在它把"停止"想成了一个没有时长、没有过程的瞬间。可一个正在服务真实流量的进程,在任何一个时刻,身上都挂着一堆"进行到一半的事":可能有十几个请求正在它的线程里跑着、还没返回;可能有一个数据库事务刚 INSERT 完、还没 COMMIT;可能有一条消息刚从队列里 poll 出来、业务逻辑做了一半。这些"半成品",每一个都需要时间才能收尾。而你瞬间杀掉进程,等于不给任何收尾的时间:在途请求的调用栈凭空消失,客户端那头等不到响应,只能报 502;事务没等到 COMMIT,留下不一致的中间状态;消息没等到 ack,队列不知道它到底处理完没有。一旦你接受"停止服务是一个需要时间的过程,不是一个瞬间"这个定位,那串问题的答案就全有了:服务需要先知道"自己要停了",所以它得捕获停机信号;它不能再接新活,所以要先从负载均衡里摘出去、并拒绝新请求;它得把手上的活干完,所以要等在途请求排空;它要善后,所以要按顺序关闭连接、事务、消费者;它又不能无限期拖着,所以要有超时兜底。这些不是吹毛求疵,而是"让一次停机不伤害任何一个正在被服务的用户"的最低要求。

要把服务优雅停机做对,需要几块认知:

• 为什么"kill 掉再起一个"是错的——停止服务是过程,不是瞬间;
• SIGTERM——停机信号,进程要先"听得见"它;
• 摘流与排空——先不接新请求,再等在途请求做完;
• 按序关闭资源——先停入口,再排空在途,最后关底层依赖;
• 超时兜底、健康检查摘流、消息消费者停机这些工程坑怎么处理。

一、为什么"kill 掉再起一个"是错的

先把这件最根本的事钉死:一个进程,和它"正在做的事",是两回事。kill 掉的是进程——操作系统层面那个执行实体,它确实可以瞬间消失。但进程消失的那一刻,它"正在做的事"并不会被妥善收尾,而是被硬生生切断在当前那一行。一个请求处理到一半,调用栈断了;一个事务提交到一半,连接断了;一条消息处理到一半,确认断了。这些"断在半路"的事,不会自己愈合——它们会变成客户端的报错、数据库里的脏数据、消息队列里的悬案。所以"停止服务"这件事,你真正要管的不是"怎么让进程消失",而是"怎么让进程在消失之前,把手上的事都安全地收尾"。前者是一瞬间,后者是一个过程——优雅停机,就是把这个过程,认认真真地设计出来。

下面这段代码,就是我那个"一发版就出事"的第一版:

# 反面教材:服务直接跑,没有任何停机处理
def main():
    server = create_server()
    server.serve_forever()       # 一直跑,直到被外部信号打断
    # 部署时:运维 kill 掉这个进程 —— 它会怎样?
    #   破绽一:进程瞬间消失,正在处理的请求被拦腰斩断,客户端收到 502。
    #   破绽二:写到一半的数据库事务、没 ack 的消息,全部丢在半路。
    #   破绽三:进程根本没监听停机信号,kill 给的"温柔提醒"它听都听不见。

这段代码在本地开发时表现不错,因为本地根本没有"在途请求"这回事:你按 Ctrl+C 停服务时,通常没有任何真实用户的请求正在里面跑,没东西被斩断,你自然感受不到问题。停机的所有缺陷,都被"本地没有真实流量"这件事掩盖了。它的问题不在某一行代码上——serve_forever 本身没错——而在一个被忽略的前提:它默认"进程被停掉的那一刻,它手上是干净的、没有任何未完成的工作"。可线上恰恰相反:一个有流量的服务,几乎任何一个瞬间,手上都有没做完的事。于是那串问题就有了解释:发版冒 500/502,是因为进程被杀时,正有一批请求在里面跑,它们的响应永远发不出去了;半截脏数据,是因为事务执行到一半,COMMIT 还没来得及发,连接就断了;消息丢失或重复,是因为消息处理完了、ack 还没发出,进程就没了,队列无从判断它的死活。问题的根子清楚了:做好停机的工程量,全在"承认停止服务是一个需要时间收尾的过程"之后——你不给它收尾的时间和步骤,它就在每一次发版时,伤害一批正在被服务的用户。先从这个过程的第一步——让进程"听见"停机信号——说起。

二、SIGTERM:停机信号,进程要先听得见

优雅停机的第一步,是进程得知道"自己要被停了"。这个"通知",在 Linux 上是通过信号传递的。这里要分清两个关键信号。SIGTERM:是"请你停一下"的礼貌通知——运维执行 kill(不带 -9)、Kubernetes 要终止一个 Pod,发的都是它。它可以被进程捕获,进程收到后有机会执行自己的停机逻辑。SIGKILL:就是 kill -9 发的——它无法被捕获、无法被处理,操作系统直接把进程杀死,不给一丝反应时间。所以,优雅停机能成立的大前提,是停机用 SIGTERM,而你的进程要捕获它。捕获的方式,是注册一个信号处理器:

import signal
import threading

# 一个全局的"该停机了"开关
_shutdown = threading.Event()


def _on_signal(signum, frame):
    """收到停机信号:不立刻退出,只是把开关打开。"""
    print(f"收到信号 {signum},开始优雅停机...")
    _shutdown.set()


# 注册:SIGTERM 是 K8s/运维 发出的标准停机信号;SIGINT 是 Ctrl+C
signal.signal(signal.SIGTERM, _on_signal)
signal.signal(signal.SIGINT, _on_signal)

注意这个处理器里有个关键的克制:它什么实事都没干,只是_shutdown.set() 把一个标志位置位。这是故意的——信号处理器是一个非常受限的执行环境,它会打断主程序的任意一行,在里面做耗时操作、申请锁,极易出问题。正确的模式是:处理器只负责"把停机标志立起来"这一件极快的事;真正的停机流程,交给主流程去看到这个标志、再从容地执行。这里的认知要点是:信号是"通知",不是"动作"。进程收到 SIGTERM,意味着"外界希望你停下",但具体怎么停、按什么步骤停、停多久,完全是你自己代码的事——操作系统只管把这声招呼递到,不管你怎么收尾。这就引出两个绝不能省的前提:第一,你的进程必须真的注册了 SIGTERM 处理器,否则这声招呼就被默认行为(直接终止)给吃掉了,你精心设计的停机流程一行都不会跑;第二,停机信号必须是 SIGTERM 而不是 SIGKILL——对一个还在好好运行的服务直接 kill -9,等于剥夺了它收尾的全部权利。进程能听见停机信号了,接下来就是这个停机过程的第一个实质动作——别再接新请求。

三、摘流与排空:先不接新请求,再等在途做完

收到停机信号后,第一件实质的事,不是关资源,而是"截断新流量的来源"。这件事要分两个层次。第一层是"摘流":让负载均衡器知道"别再往我这儿发新请求了"——这通常通过让健康检查(readiness 探针)失败来实现。第二层是"拒新":对那些在摘流生效前、已经发过来的新请求,直接回一个 503,让上游去重试别的健康实例。先看摘流——把 readiness 探针和停机标志绑在一起:

# 健康检查:停机一开始,就先让 readiness 探针失败,把自己摘出负载均衡
def readiness_probe():
    """负载均衡/K8s 调这个接口,判断'要不要把流量发给我'。"""
    if _shutdown.is_set():
        return Response(status=503)        # 停机中:别再给我发新流量了
    return Response(status=200)            # 正常:可以接流量
    # 关键:readiness 失败要先于"停止接收",给上游一点反应时间。

摘流之后,新请求会逐渐断流,但不会立刻断干净(负载均衡感知到探针失败需要一点时间)。所以业务入口还要对停机中到达的请求做拒新,同时把"在途请求"统计起来——我们需要知道"还有多少请求没做完":

import threading


class InflightTracker:
    """记录当前有多少个请求正在处理中,并能等待它们全部归零。"""

    def __init__(self):
        self._count = 0
        self._lock = threading.Lock()
        self._idle = threading.Condition(self._lock)

    def enter(self):
        with self._lock:
            self._count += 1

    def leave(self):
        with self._lock:
            self._count -= 1
            if self._count == 0:
                self._idle.notify_all()

    def wait_until_idle(self, timeout):
        """阻塞,直到在途请求归零,或到达超时。"""
        with self._lock:
            return self._idle.wait_for(lambda: self._count == 0, timeout)

有了它,业务入口就既拒新、又登记在途:

inflight = InflightTracker()


def handle_request(request):
    # 已经在停机了:不再接新请求,直接回 503,让上游重试别的实例
    if _shutdown.is_set():
        return Response(status=503, body="服务正在停机,请重试")
    inflight.enter()                       # 登记:又一个请求进来了
    try:
        return do_business(request)        # 正常处理业务
    finally:
        inflight.leave()                   # 无论成败,都要登记离开

下面这张图,把从收到信号到进程退出的整个优雅停机过程画出来:

这里的认知要点是:优雅停机的核心,是一个严格的先后顺序:先切断"进",再等待"出"。"切断进"——让 readiness 失败、拒绝新请求——必须排在最前面,因为只有新流量先停了,"在途请求"这个集合才会只减不增,才有"排空"的可能;否则你一边等老请求做完、一边还在收新请求,这个集合永远清不零。而"摘流"还要比"拒新"更早一点点:你得给负载均衡留出感知探针失败的时间,在这段时间里,新请求还会零星进来,这时的 503 拒新就是兜底。一句话:先让自己在负载均衡眼里"不健康",再优雅地拒掉漏网的新请求,最后安心地等存量请求跑完。新流量切断、在途请求也排空了,接下来才轮到关闭那些底层资源。

四、按序关闭资源:先入口,再在途,最后底层依赖

在途请求都做完了,进程就可以关闭它持有的各种资源了:数据库连接池、Redis 连接、消息队列消费者、后台定时任务……但关闭这些资源有讲究——它有顺序。原则是:先关"上层"(靠近入口的),后关"下层"(被上层依赖的底层资源)。道理很直白:如果你先把数据库连接池关了,可此刻还有一个在途请求正要查库,它就会因为"连接池已关"而失败。正确的顺序是反过来的:先停接入、再排空在途(前两节做的),最后才关数据库这种被业务依赖的底层资源。工程上,常用一个"后进先出"的清理钩子链来保证这个顺序:

# 关闭资源是有顺序的:先停"入口",再排"在途",最后关"底层依赖"
_cleanup_hooks = []


def on_shutdown(func):
    """注册一个停机清理钩子。后注册的先执行(后进先出 LIFO)。"""
    _cleanup_hooks.append(func)
    return func


def run_cleanup():
    # reversed:后注册的先关 —— 底层依赖通常最后注册、所以最后才关
    for func in reversed(_cleanup_hooks):
        try:
            func()
        except Exception as e:
            print(f"清理钩子 {func.__name__} 出错: {e}")   # 单个失败不阻断其余

为什么用"后进先出"?因为程序启动时,资源的初始化顺序通常是"先底层、后上层":先连上数据库,再启动用了数据库的业务服务。那么关闭时,自然就该"先上层、后底层"——恰好是启动顺序的逆序。把这套和前面的摘流、排空串成一个完整的停机编排:

GRACE_PERIOD = 25            # 留给"排空在途请求"的最长等待时间(秒)


def graceful_shutdown(server):
    """优雅停机的完整编排:摘流 -> 拒新 -> 排空 -> 关资源 -> 退出。"""
    # 1. _shutdown 标志此前已置位:readiness 已翻 503、新请求已被拒
    server.stop_accepting()                          # 2. 停止接收新连接
    drained = inflight.wait_until_idle(GRACE_PERIOD)  # 3. 等在途请求排空
    if not drained:
        print("超时:仍有在途请求未完成,记录告警后强制继续")
    run_cleanup()                                     # 4. 按序关闭底层资源
    print("优雅停机完成,进程即将退出")

这里的认知要点是:资源的关闭顺序,本质是依赖关系的体现。一个资源 A 被资源 B 依赖,那么关闭时,一定是先关 B、再关 A——绝不能反过来,否则 B 在自己还活着、还想用 A 的时候,发现 A 已经没了。把这个原则推到整个服务上就是:最该先停的,是"入口"(接收新请求的能力),因为它是一切工作的源头;然后是"在途"(让存量请求跑完);最后才是数据库连接池、缓存连接这些"被业务依赖的底层"。用一个后进先出的钩子链来管理,是因为它天然吻合"启动时由底向上、关闭时由上向下"这个对称关系——你只要按依赖顺序注册,关闭顺序就自动正确了。停机的主流程到这就齐了,但还差一个关键的安全垫——超时兜底,以及几个真实环境里的坑。

五、工程坑:超时兜底、preStop 与消息消费者停机

主流程之外,还有几个工程坑,不处理就会让你的优雅停机要么永远停不下来、要么停得不够"优雅"。坑 1:优雅停机必须有超时兜底,不能无限等。"等在途请求做完"听着美好,但万一有一个请求因为 bug 卡死了呢?你不能为了它一个,让整个进程永远停不下来。所以 wait_until_idle 一定要带超时(前面 GRACE_PERIOD 就是干这个的):超时一到,记录一条告警,然后强制继续后面的步骤。优雅是有时间预算的优雅,不是无限期的等待。坑 2:停机的总时长,要和编排系统的"宽限期"对齐。在 Kubernetes 里,从发 SIGTERM 到强制 SIGKILL,中间有一个 terminationGracePeriodSeconds 宽限期(默认 30 秒)。你的 GRACE_PERIOD 加上其它停机步骤的耗时,必须明显小于这个宽限期——否则你还没优雅完,K8s 的 SIGKILL 就到了,前功尽弃:

# K8s 部署:给优雅停机留足时间,并用 preStop 配合摘流
spec:
  terminationGracePeriodSeconds: 30   # 从 SIGTERM 到 SIGKILL 的宽限期
  containers:
    - name: app
      lifecycle:
        preStop:
          exec:
            # 先睡几秒:等负载均衡感知到 readiness 失败、不再发新流量
            command: ["sh", "-c", "sleep 5"]
      readinessProbe:
        httpGet:
          path: /readyz
          port: 8080

坑 3:用好 preStop,解决"摘流有延迟"的时间差。上面那个 preStop: sleep 5 不是多余的。K8s 把一个 Pod 标记为"终止中"和负载均衡真正停止给它发流量之间,存在一个时间差。preStop 钩子在 SIGTERM 发出前执行,用一个 sleep 把这个时间差"睡"过去,能让"摘流彻底生效"赶在"进程开始停机"之前,进一步减少被斩断的请求。坑 4:消息队列消费者的停机,要"处理完当前这条、再停"。消费者的优雅停机和 HTTP 服务同理:收到停机信号后,不再 poll 新消息,但手上正在处理的那条,必须处理完、ack 掉,再退出——而且 ack 一定要在处理成功之后:

# 消息消费者的优雅停机:把手上这条消息处理完、ack 掉,再停
def consume_loop(queue):
    while not _shutdown.is_set():          # 看到停机标志,就不再领新消息
        msg = queue.poll(timeout=1)        # 短超时轮询,以便及时看到停机标志
        if msg is None:
            continue
        try:
            process(msg)                   # 1. 先把整条消息处理完
            queue.ack(msg)                  # 2. 再确认 —— 这个顺序不能反
        except Exception:
            queue.nack(msg)                 # 处理失败:退回队列,留待重试
    print("消费者已停止:当前消息已处理完,不再领取新消息")

坑 5:把整个停机流程串进 main 入口。所有这些机制,最后要在程序入口处编排成一条线:启动服务、注册清理钩子、然后主线程阻塞在"等待停机信号"上,信号一到,就执行 graceful_shutdown:

def main():
    server = create_server()
    on_shutdown(db_pool.close)             # 注册:关数据库连接池
    on_shutdown(redis_client.close)        # 注册:关 Redis 连接
    server.start()
    print("服务已启动")

    _shutdown.wait()                       # 主线程在此阻塞,直到收到停机信号
    graceful_shutdown(server)              # 信号一到,执行完整的优雅停机

关键概念速查

避坑清单

1. 别直接 kill 进程,服务退出前要完成在途请求、按序关资源。
2. 进程必须捕获 SIGTERM,否则停机信号等于没发。
3. 信号处理器里只置标志位,别在里面做耗时清理工作。
4. 停机第一步先让 readiness 探针失败,把自己摘出负载均衡。
5. 摘流要先于停止接收请求,给上游负载均衡留出反应时间。
6. 停机后到达的新请求回 503,让上游去重试其它健康实例。
7. 停止收新请求后要排空在途请求,等它们处理完再退出。
8. 关闭资源讲顺序:先入口、再在途、最后底层依赖,后进先出。
9. 优雅停机要有超时兜底,不能因个别请求卡死而永不退出。
10. 消息消费者停机要先处理完当前消息并 ack,再停止领取新消息。

总结

回头看那串"发版冒 500、半截脏数据、消息丢了又重复、kill 等于白等"的问题,以及我后来在停机上接连踩的坑,最该记住的不是某一个信号的名字,而是我动手前那个想当然的判断——"停一个服务,就是把进程 kill 掉"。这句话错在它把"停止"当成了一个没有时长的瞬间。我以为进程说停就能停,干干净净。可我忽略了一件事:一个正在服务真实流量的进程,在你想停它的任何一个瞬间,身上都挂满了"没做完的事"。有正在跑的请求、有提交到一半的事务、有还没确认的消息。你瞬间杀掉进程,杀掉的只是那个执行实体;而它手上那一堆半成品,会被硬生生切断在半路——变成用户的报错、库里的脏数据、队列里的悬案。停止服务,从来不是"让进程消失"这一下,而是"让进程在消失前,把手上的事安全收尾"这一整个过程。

所以做好优雅停机,真正的工程量不在"kill 一个进程"那个命令上。那个命令,谁都会敲。真正的工程量,在于你要承认"停止服务是一个需要时间、需要顺序的过程",并据此把停机当成一条流水线来设计:进程要知道自己该停了,你就捕获 SIGTERM 信号;不能再揽新活,你就先让 readiness 失败摘流、再拒掉漏网的新请求;手上的活要干完,你就等在途请求排空;善后要有章法,你就按"先入口、后底层"的顺序关闭资源;又不能无限拖着,你就给它一个超时兜底。这篇文章的几节,其实就是顺着这条线展开的:先想清楚"kill 掉再起一个"为什么错,再讲 SIGTERM 怎么捕获、怎么摘流排空、资源怎么按序关闭,最后是超时兜底、preStop、消息消费者停机这几个把停机守扎实的工程细节。

你会发现,服务优雅停机,和现实里"一家餐厅打烊"完全相通。一家餐厅到了打烊时间,一个粗暴的老板会怎么做?他时间一到,直接拉电闸、关灯、锁门——把还在吃饭的客人撵到漆黑里,把灶上正炒着的菜直接扔掉(这就是 kill -9:不给任何收尾的时间)。而一个体面的老板怎么打烊?他第一件事,是在门口挂上"今日已停止接客"的牌子——不再放新客人进来(这就是 readiness 翻成 503、摘流);至于已经坐在店里的客人,他让大家安安心心把这顿饭吃完(这就是排空在途请求);等客人都走了,他才回到后厨,按顺序熄火、清灶、收拾、最后锁门(这就是按序关闭底层资源)。可他也不会无限期地等——要是有一桌客人聊到天亮也不走,过了打烊的宽限时间,他还是得礼貌地请他们离开(这就是超时兜底)。同样是打烊,可前者让一批客人骂骂咧咧地记恨这家店,后者让每一个客人都满意地走出门——差别不在"关不关门"这件事本身,只在老板有没有把"打烊"当成一个需要章法的过程,而不是"拉电闸"那一下。

最后想说,优雅停机做没做对,差距永远不会在"本地开发、Ctrl+C 一按服务就停"时暴露——本地你按下停止键的那一刻,根本没有真实用户的请求正在里面跑,没有事务在半路、没有消息没 ack,没有任何东西被斩断,你会觉得"kill 掉再起一个"已经够用。它只在真实的、有成百上千个请求正在飞、要在流量高峰期反复发版的线上环境里才显形。那时候它会用最准时的方式给你结账:做不好,你会每发一次版就给一批用户送去 502,会因为事务被斩断而在库里留下洗不掉的脏数据,甚至因为消息没 ack 而丢单或重复扣款;而做对了,你的服务一次次发版,监控面板上却平静得没有一丝波澜——在途的请求都体面地收了尾,资源都按顺序关得干干净净,用户根本不知道刚刚发生过一次重启。所以别等"发版告警又响成一片"那一刻找上门,在你写下服务的入口代码时就该想清楚:它该停的时候,知道怎么体面地停吗——它听得见 SIGTERM 吗、它会先摘流吗、它会等在途请求做完吗、它关资源的顺序对吗、它有超时兜底吗,这一道道工序,我是不是都替它设计过了?这些问题有了答案,你交付的才不只是一个"能跑起来"的服务,而是一个能被无数次平滑重启、发版时悄无声息、经得起线上反复部署考验的可靠服务。

—— 别看了 · 2026