IIASK插件库

使用uvicorn库的get_local_addr方法时遇到"Address already in use"错误如何解决？

更新时间

问题现象与错误解析

当开发者使用uvicorn.get_local_addr()方法绑定服务端口时，常见的OSError: [Errno 98] Address already in use错误表明存在端口冲突。系统级错误代码98（EADDRINUSE）表示该TCP端口已被其他进程占用或处于TIME_WAIT状态。

根本原因深度分析

端口占用的典型场景包括：

  • 同一应用的多个实例意外并行运行
  • 前次服务终止后未释放端口（TIME_WAIT状态持续2MSL时间）
  • 其他服务（如Nginx、数据库）占用了目标端口
  • Docker容器未完全清理导致的残留绑定

6种解决方案及实现

1. 端口重用技术（推荐）

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, bind="0.0.0.0:8000", sock=sock)

2. 自动端口选择

修改get_local_addr调用方式：

def get_available_port():
    with socket.socket() as s:
        s.bind(('',0))
        return s.getsockname()[1]

uvicorn.run(app, host="0.0.0.0", port=get_available_port())

3. 强制终止占用进程

Linux/MacOS系统命令：

sudo lsof -i :8000
kill -9 [PID]

进阶调试技巧

工具 命令 用途
netstat netstat -tulnp 查看所有TCP/UDP端口状态
ss ss -tlnp 更现代的socket统计工具

预防性编程策略

  1. 实现端口健康检查机制
  2. 添加应用启动时的端口验证逻辑
  3. 容器化部署时配置端口映射策略

底层原理延伸

TCP协议的四次挥手过程中，主动关闭方会保持TIME_WAIT状态2MSL（Maximum Segment Lifetime）时间，通常为60秒。这是造成"Address in use"的常见原因之一。