Python / 系统课时

给服务加超时与优雅停机

给服务加超时与优雅停机

异步服务稳定运行的关键,不是“能接连接”,而是能在请求卡住、任务被取消或进程收到退出信号时,按可预测顺序停止接流量、等待在途请求、取消剩余任务并关闭连接。本节用一个完整 TCP 服务把这些环节串起来。

学习目标

  • 为单次读取设置超时,避免连接长期占用协程与文件描述符
  • 正确处理 CancelledError、writer.close() 与 wait_closed()
  • 在 SIGINT、SIGTERM 到来时完成有宽限期的优雅停机

生命周期里真正要控制的四件事

一个可控的异步服务通常同时面对四类事件:请求超时、客户端断开、协程取消和进程退出。它们不能混成一个“异常处理”分支,因为动作不同:超时应结束当前连接;断开只需回收资源;取消必须向上传播;退出信号则先停止接受新连接,再处理已有任务。

异步服务从运行到优雅停机的生命周期

优雅停机的顺序很重要。先关闭监听套接字可以阻止新连接继续进入;随后给现有任务一个短暂宽限期;宽限期结束后才取消剩余任务。若一收到信号就直接取消所有任务,正在写响应的客户端会更容易看到连接重置或半截数据。

一个可运行的优雅停机服务

下面示例使用“一行请求、一行响应”的 TCP 协议。单个连接超过 5 秒没有读到完整一行就返回超时;进程收到退出信号后停止接收新连接,并最多等待 10 秒让已有连接自然结束。

python
import asyncio
import os
import signal

HOST = "127.0.0.1"
PORT = int(os.getenv("PORT", "8888"))
REQUEST_TIMEOUT = 5.0
SHUTDOWN_GRACE = 10.0

connection_tasks = set()

async def handle_client(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
    try:
        while True:
            try:
                data = await asyncio.wait_for(
                    reader.readline(),
                    timeout=REQUEST_TIMEOUT,
                )
            except TimeoutError:
                writer.write(b"ERR timeout\n")
                await writer.drain()
                return

            if not data:
                return

            writer.write(b"OK " + data)
            await writer.drain()
    except ConnectionError:
        return
    except asyncio.CancelledError:
        # 取消是服务停机协议的一部分,清理后必须继续向上传播。
        raise
    finally:
        writer.close()
        try:
            await writer.wait_closed()
        except ConnectionError:
            pass

def on_client(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
    task = asyncio.create_task(handle_client(reader, writer))
    connection_tasks.add(task)
    task.add_done_callback(connection_tasks.discard)

async def main() -> None:
    stop_event = asyncio.Event()
    loop = asyncio.get_running_loop()

    for sig in (signal.SIGINT, signal.SIGTERM):
        try:
            loop.add_signal_handler(sig, stop_event.set)
        except NotImplementedError:
            # Windows 默认事件循环不支持 add_signal_handler。
            signal.signal(
                sig,
                lambda *_: loop.call_soon_threadsafe(stop_event.set),
            )

    server = await asyncio.start_server(on_client, HOST, PORT)
    bound_port = server.sockets[0].getsockname()[1]
    await server.start_serving()
    print(f"listening on {HOST}:{bound_port}")

    await stop_event.wait()
    print("shutdown requested")

    server.close()
    await server.wait_closed()

    if connection_tasks:
        _, pending = await asyncio.wait(
            set(connection_tasks),
            timeout=SHUTDOWN_GRACE,
        )
    else:
        pending = set()

    for task in pending:
        task.cancel()

    if pending:
        await asyncio.gather(*pending, return_exceptions=True)

    print("shutdown complete")

if __name__ == "__main__":
    asyncio.run(main())

预期输出

text
listening on 127.0.0.1:<PORT>
shutdown requested
shutdown complete

<PORT> 的实际值由 PORT 环境变量决定,未设置时为 8888。运行后按 Ctrl+C 会触发 SIGINT;在支持的系统上发送 SIGTERM 也会走同一套停机路径。

超时、取消和关闭为什么要分层

asyncio.wait_for() 负责限制一次等待的最长时间。这里超时意味着客户端在规定时间内没有发来完整一行,所以服务主动结束该连接,而不是继续占着一个任务等待。

CancelledError 则不同。它表示外部调度逻辑要求任务停止,例如优雅停机宽限期已经耗尽。代码可以在 finally 中释放连接,但不应吞掉取消异常,否则上层会误以为任务正常完成,停机逻辑也可能一直等不到真实状态。

writer.close() 只发起关闭,await writer.wait_closed() 才等待底层传输真正结束。把两者放在 finally 中,可以覆盖正常返回、超时、连接错误和任务取消四种路径。

验证停机是否真的优雅

验证时应分别覆盖空闲连接、正常请求和停机中的在途请求。空闲连接保持 5 秒以上,应收到 ERR timeout 后被关闭;正常请求应收到以 OK 开头的响应;收到退出信号后,监听端口应立即停止接受新连接,而已建立连接仍有最多 10 秒完成工作。

观察日志时,shutdown requested 与 shutdown complete 之间的间隔就是等待在途任务的窗口。如果总是立刻结束,说明没有真实在途任务;如果经常接近 10 秒,则应继续检查是否存在长耗时操作、未设置超时的下游调用或无法取消的阻塞代码。

生产环境的边界

优雅停机只能管理“可取消、可等待”的异步工作。若协程内部调用了阻塞文件操作、CPU 密集计算或不响应取消的第三方代码,事件循环仍可能卡住。生产服务应同时为数据库、HTTP、队列等下游调用设置各自超时,并让容器或进程管理器给应用留出比 SHUTDOWN_GRACE 更长的终止宽限期。

当所有连接都有超时、取消能向上传播、监听端先关闭且连接最终进入 wait_closed(),服务的退出就从“碰运气结束进程”变成了可验证的生命周期控制。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

给服务加超时与优雅停机

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通