Python 网络服务稳定性设计思路

python网络服务需显式处理sigterm：注册信号处理器设退出标志，主循环检查并优雅关闭连接；优先选uvicorn而非手写socket；需兜底捕获i/o异常；健康检查须探测关键依赖并设超时。

服务启动时就该处理的 SIGTERM 信号

Python 网络服务（比如用 flask、fastapi 或原生 socket 启的）在容器或 systemd 下被优雅关闭时，系统会发 SIGTERM，但默认 Python 进程不响应——它直接退出，正在处理的请求被硬中断，连接重置，客户端看到 Connection reset by peer。

必须显式注册信号处理器，在收到 SIGTERM 后停止接收新连接，并等待已有请求完成（带超时）。

• 用 signal.signal(signal.SIGTERM, handler) 注册，handler 里设个全局 flag（如 should_exit = True）
• 主循环（比如 while not should_exit:）要检查这个 flag，且每次 accept 前都判断一次
• 对长连接或流式响应，得配合 socket.settimeout() 或 asyncio.wait_for() 控制单请求最大耗时，否则可能永远等不到结束
• 别在 handler 里直接调 sys.exit()——这会跳过清理逻辑；应该让主循环自然退出后执行 cleanup()

http 服务器选 uvicorn 还是自己写 socket 循环

除非你在做协议网关或极低延迟透传，否则别手写阻塞式 socket 循环。它扛不住并发，也处理不了半包、粘包、keep-alive 复用这些细节，出问题全是“连接突然断开”“响应乱码”这类模糊错误。

uvicorn（搭配 FastAPI 或纯 ASGI）是当前最稳的选择：它用 asyncio + uvloop，单进程轻松撑住几千并发，自带 request timeout、client disconnect 检测、HTTP/1.1 pipelining 支持。

立即学习“Python免费学习笔记（深入）”；

• 启动时加 --timeout-keep-alive 5，避免空闲连接长期占着 worker
• 用 --limit-concurrency 100 防止单个慢请求拖垮整个服务
• 别把数据库同步操作（如 requests.get()、sqlite3.connect()）扔进 async 路由——会阻塞 Event loop，改用 asyncpg 或 httpx.AsyncClient
• 如果非要用 Flask，至少套一层 gevent 或换 gunicorn --worker-class gevent，纯 threading 模式在高并发下锁竞争严重

try/except 不能只包 HTTPException

线上服务崩溃往往不是因为业务逻辑错，而是网络层抖动：DNS 解析失败、上游服务返回空响应、ssl 握手超时、ConnectionResetError 突然冒出来。只捕获 HTTPException 或自定义异常，等于对真实故障视而不见。

必须在请求入口处兜底捕获底层 I/O 异常，并统一转成可读错误码和日志上下文。

• 重点捕获：ConnectionError、TimeoutError、OSError（含 errno.ECONNREFUSED）、ssl.SSLError
• 对 ConnectionResetError 和 BrokenPipeError，直接 return 空响应（HTTP 204）并 log，别抛出——客户端已经收不到了
• 所有异常日志必须带 request_id 和 upstream_host（如果有），否则排查时根本串不起链路
• 别在 except 里再发起 HTTP 请求（比如打个告警接口）——这会让故障雪崩；写本地日志或发到 syslog 更可靠

健康检查端点为什么总返回 200 却实际不可用

/health 返回 200 只说明进程活着，不代表数据库连得上、缓存没满、磁盘还有空间。很多服务的健康检查只做 return {"status": "ok"}，结果流量切过去后大量 500 报错。

真正的健康检查得探测关键依赖，且必须设超时、失败容忍和降级策略。

• 数据库检查用 engine.execute("select 1")（SQLAlchemy）或 conn.ping(reconnect=True)（PyMySQL），超时设为 1s，失败最多重试 1 次
• redis 检查用 redis_client.ping()，别用 INFO——太重；内存水位超过 90% 时主动返回 503
• 磁盘空间检查读 /proc/mounts 或用 shutil.disk_usage("/tmp")，剩余
• 不要让健康检查调用完整业务逻辑链路——它不该成为压测入口；更别让它依赖另一个微服务的健康端点

最常被忽略的是：健康检查路径本身不能走鉴权中间件，也不能触发任何副作用（比如写日志到同一块快满的磁盘）。它得是纯粹、轻量、无状态的探测点。