Python / 系统课时
给服务加超时与优雅停机
给服务加超时与优雅停机
异步服务稳定运行的关键,不是“能接连接”,而是能在请求卡住、任务被取消或进程收到退出信号时,按可预测顺序停止接流量、等待在途请求、取消剩余任务并关闭连接。本节用一个完整 TCP 服务把这些环节串起来。
学习目标
- 为单次读取设置超时,避免连接长期占用协程与文件描述符
- 正确处理
CancelledError、writer.close()与wait_closed() - 在
SIGINT、SIGTERM到来时完成有宽限期的优雅停机
生命周期里真正要控制的四件事
一个可控的异步服务通常同时面对四类事件:请求超时、客户端断开、协程取消和进程退出。它们不能混成一个“异常处理”分支,因为动作不同:超时应结束当前连接;断开只需回收资源;取消必须向上传播;退出信号则先停止接受新连接,再处理已有任务。

优雅停机的顺序很重要。先关闭监听套接字可以阻止新连接继续进入;随后给现有任务一个短暂宽限期;宽限期结束后才取消剩余任务。若一收到信号就直接取消所有任务,正在写响应的客户端会更容易看到连接重置或半截数据。
一个可运行的优雅停机服务
下面示例使用“一行请求、一行响应”的 TCP 协议。单个连接超过 5 秒没有读到完整一行就返回超时;进程收到退出信号后停止接收新连接,并最多等待 10 秒让已有连接自然结束。
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())预期输出
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(),服务的退出就从“碰运气结束进程”变成了可验证的生命周期控制。