如何解决uvicorn set_port方法端口被占用的问题

问题现象与成因分析

在使用uvicorn的set_port方法配置服务端口时，开发者常会遇到"Address already in use"错误。这种情况通常表明：

• 目标端口已被其他进程占用（常见于80/443等标准端口）
• 前次服务未正常终止导致端口未释放
• 操作系统端口回收存在延迟（TIME_WAIT状态）
• 容器环境中端口映射冲突

解决方案与最佳实践

1. 端口可用性检测

import socket
from contextlib import closing

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

2. 强制释放被占用端口

在Linux/MacOS系统中可通过终端命令：

sudo lsof -i :8000 | awk 'NR!=1 {print $2}' | xargs kill -9

3. 配置端口复用选项

import uvicorn
from uvicorn.config import Config

config = Config(
    app="main:app",
    port=8000,
    reuse_port=True  # 启用SO_REUSEPORT选项
)
server = uvicorn.Server(config)

高级处理方案

容器环境特殊处理

在Docker/Kubernetes环境中需注意：

1. 检查EXPOSE指令与实际映射是否匹配
2. 避免使用host网络模式时的冲突
3. 配置livenessProbe时设置合理的初始延迟

监控与日志分析

建议添加端口监控逻辑：

import logging
logger = logging.getLogger("uvicorn.error")

try:
    uvicorn.run(app, port=8000)
except OSError as e:
    logger.error(f"Port conflict detected: {e}")
    # 自动切换备用端口逻辑...