IIASK插件库

如何解决uvicorn中get_reuse_port方法的Address already in use错误？

更新时间

问题现象与背景

在使用Python的uvicorn库部署ASGI应用时，get_reuse_port()方法经常会出现"Address already in use"的错误提示。这种情况通常发生在以下几种场景：

  • 快速重启服务时前一个进程尚未完全释放端口
  • 多个服务实例尝试绑定相同端口
  • 操作系统未及时清理TIME_WAIT状态的连接

错误原因深度分析

从网络协议栈层面来看，这个错误涉及TCP/IP协议的四次挥手过程。当服务关闭时，连接会进入TIME_WAIT状态（默认2分钟），此时操作系统仍然认为端口被占用。使用get_reuse_port()时，uvicorn会尝试设置SO_REUSEPORT套接字选项，但可能遇到以下情况：

  1. 前一个进程未正确关闭套接字
  2. 操作系统限制（特别是Windows系统）
  3. 防火墙或安全软件拦截

TCP状态转换示意图

+---------+       +----------+       +---------+
| CLOSED  |<------| TIME_WAIT|<------| CLOSING |
+---------+       +----------+       +---------+

六种解决方案

1. 设置SO_REUSEADDR选项

在uvicorn配置中显式设置套接字参数：

import socket
from uvicorn.config import Config

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
config = Config(app, sockets=[sock])

2. 增加端口释放延迟

在关闭服务时添加短暂延迟：

import time
from uvicorn import Server

server = Server(config)
try:
    server.run()
finally:
    time.sleep(5)  # 等待5秒确保端口释放
    server.shutdown()

3. 使用端口扫描确认可用性

在绑定前检查端口状态：

def is_port_available(port):
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
        return s.connect_ex(('localhost', port)) != 0

4. 修改操作系统参数（Linux）

调整TCP参数缩短TIME_WAIT时间：

echo 1 > /proc/sys/net/ipv4/tcp_tw_reuse
echo 1 > /proc/sys/net/ipv4/tcp_tw_recycle

5. 使用不同的网络接口

绑定到特定网络接口避免冲突：

config = Config(app, host="192.168.1.100", port=8000)

6. 容器化部署方案

在Docker中使用--network host模式：

docker run --network host my-uvicorn-app

性能优化建议

方案 适用场景 性能影响
SO_REUSEADDR 开发环境 低
修改TIME_WAIT 生产环境 中
容器化方案 云部署 高

底层原理扩展

现代操作系统通过epoll或kqueue机制管理套接字。当设置SO_REUSEPORT时，内核会：

  • 创建独立的接收队列
  • 使用哈希算法分配连接
  • 允许负载均衡到多个进程

这在Kubernetes等容器编排系统中尤为重要，可以实现零停机部署。