Ubuntu 22.04下Uvicorn未实际监听8000端口问题求助

环境与现象 #

• 系统：Ubuntu 22.04
• AWS安全组及ufw均已开放8000端口
• 启动脚本execWxApi.sh内容：

#!/bin/sh

uvicorn app.wxapi:app --host 0.0.0.0 --reload

• 启动日志：

ubuntu@ip-172-1-1-1:~$ ./execWxApi.sh
INFO:     Will watch for changes in these directories: ['/home/ubuntu']
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [5216] using StatReload
^CINFO:     Stopping reloader process [5216]

• sudo netstat -tlnp无8000端口监听记录：

ubuntu@ip-172-1-1-1:~/app$ sudo netstat -tlnp
Active Internet connections (only servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name    
tcp        0      0 0.0.0.0:22              0.0.0.0:*               LISTEN      654/sshd: /usr/sbin 
tcp        0      0 127.0.0.53:53           0.0.0.0:*               LISTEN      403/systemd-resolve 
tcp6       0      0 :::22                   :::*                    LISTEN      654/sshd: /usr/sbin 

• 测试脚本test_server.py可正常监听8000端口并对外响应：

import http.server
import socketserver

PORT = 8000

Handler = http.server.SimpleHTTPRequestHandler

with socketserver.TCPServer(("", PORT), Handler) as httpd:
    print("serving at port", PORT)
    httpd.serve_forever()

解决思路 #

• 检查Uvicorn主进程状态：

  • 执行ps aux | grep uvicorn，查看是否存在除reloader进程（日志中PID为5216）之外的Uvicorn工作进程。若只有reloader进程，说明主进程未启动，大概率是app.wxapi:app加载失败。
  • 临时移除--reload参数启动脚本，直接运行uvicorn app.wxapi:app --host 0.0.0.0，此时终端会直接输出模块加载错误信息，便于定位问题。

• 验证app模块有效性：

  • 在终端执行python3 -c "from app.wxapi import app"，手动导入目标模块，检查是否有语法错误、依赖缺失或路径问题。
  • 确认app对象是有效的FastAPI/Starlette实例，而非None或其他无效对象。

• 使用更准确的端口检查工具：

  • 执行ss -tulnp | grep 8000再次确认端口状态，ss工具比netstat更准确，可排除显示遗漏问题。（注：测试脚本可正常监听，说明端口本身无占用）

• 核对Python环境与Uvicorn版本：

  • 在启动脚本中添加which uvicorn和which python3，确认Uvicorn与测试脚本使用的是同一Python环境（比如是否激活了虚拟环境）。
  • 执行pip install --upgrade uvicorn更新Uvicorn到最新稳定版，排除旧版本兼容性问题。

• 获取详细日志：

  • 启动时添加--log-level debug参数：uvicorn app.wxapi:app --host 0.0.0.0 --reload --log-level debug，查看是否有隐藏的错误日志被忽略。

内容的提问来源于stack exchange，提问作者anakaine