python的fastapi+uvicorn的linux离线部署
一.导出依赖清单，将所有的包打到requirement.txt文件中
两种方式
1.整个环境的包都写进去，可能包含很多与项目无关的依赖
pip freeze > requirements.txt只想记录项目真正用到的包，可以配合虚拟环境或使用pipreqs等工具
pip install pipreqs # 默认生成 requirements.txt pipreqs . # 如文件已存在，强制覆盖 pipreqs . --force二、为 Python 3.11 下载兼容的离线包（关键步骤！）
下载离线包注意你生产环境的系统和python的版本号
pip download -r requirements.txt -d ./packages --only-binary=:all: --platform manylinux_2_17_x86_64 --python-version 311 --abi cp311这条命令会把requirements.txt 里所有包的「manylinux_2_17_x86_64 + CPython-3.11 ABI」二进制 wheel预先下载到
./packages目录，不做安装，留给后续离线/容器化部署使用
| 命令 | 含义 | |
| pip download | 仅拉包，不装包 | |
| -r requirements.txt | 按文件批量下载 | |
| -d ./packages | 保存目录（自动生成） | |
| --only-binary=:all: |
| |
| --platform manylinux_2_17_x86_64 | wheel 标签：glibc≥2.17 的 64-bit Linux；不会下 win32/macOS 版本 | |
| --python-version 311 | 3.11.x | |
| --abi cp311 | CPython 3.11 ABI（与 PyPy/abi3 区分） |
执行后./packages里会出现类似文件
numpy-1.26.4-cp311-cp311-manylinux_2_17_x86_64.whl
uvloop-0.21.0-cp311-cp311-manylinux_2_17_x86_64.whl
...
没有.tar.gz，因此后续离线安装时无需编译，直接：
三、文件打包，上传服务器
将源代码+package目录打包上传到服务器，注意不要打包本地的环境目录/venv 目录
your_project/ ├── main.py # 你的应用主文件 ├── requirements.txt # 依赖清单 ├── packages/ # 存放所有.whl离线包的目录 └── ... # 其他项目文件
四、在服务器离线安装：
4.1 安装python环境，可以直接安装python3.11，也可以安装虚拟环境
4.2 使用本地包安装依赖
pip install --no-index --find-links=./packages -r requirements.txt注意如果某个包没有打包到packages目录，类似以下出错：
出错ERROR: Could not find a version that satisfies the requirement uvloop>=0.15.1; (sys_platform != "win32" and (sys_platform != "cygwin" and platform_python_implementation != "PyPy")) and extra == "standard" (from uvicorn[standard]) (from versions: none)
ERROR: No matching distribution found for uvloop>=0.15.1; (sys_platform != "win32" and (sys_platform != "cygwin" and platform_python_implementation != "PyPy")) and extra == "standard"
如果服务器可以联网，可以直接下到packages目录中
pip3.11 download uvloop==0.21.0 -d ./packages然后重新运行安装命令：
sudo pip3.11 install --no-index --find-links=./packages -r requirements.txt4.3 运行程序
python3.11 -m uvicorn main:app --host 0.0.0.0 --port 8000五、加一个系统启动脚本
#!/bin/bash # ------------------------------------------------------------ # Uvicorn 一键启停脚本（CentOS + Python3.11） # 放到项目根目录（/www/service）即可 # ------------------------------------------------------------ set -e APP_DIR="/www/service" PID_FILE="$APP_DIR/tool-service-uvicorn.pid" LOG_FILE="$APP_DIR/run.log" PYTHON="/usr/bin/python" # 改成你的 3.11 路径 HOST="0.0.0.0" PORT="9099" # 确保在项目根下 cd "$APP_DIR" # 获取 pid（若文件存在且进程存活） get_pid(){ [ -s "$PID_FILE" ] && echo $(cat "$PID_FILE") && return 0 return 1 } # 启动 start(){ if get_pid >/dev/null; then echo "uvicorn is already running ($(get_pid))" return 0 fi echo "Starting uvicorn ..." nohup $PYTHON -m uvicorn app:app --host $HOST --port $PORT \ --access-log --use-colors >> "$LOG_FILE" 2>&1 & echo $! > "$PID_FILE" echo "started, pid=$(get_pid)" } # 停止 stop(){ PID=$(get_pid) || { echo "uvicorn not running"; return 0; } echo "Stopping uvicorn ($PID) ..." kill -TERM "$PID" for i in {1..10}; do kill -0 "$PID" >/dev/null 2>&1 || { rm -f "$PID_FILE"; echo "stopped"; return 0; } sleep 1 done echo "force kill ..." kill -9 "$PID" && rm -f "$PID_FILE" } # 重启 restart(){ stop sleep 1 start } # 状态 status(){ PID=$(get_pid) && echo "uvicorn is running, pid=$PID" || echo "uvicorn is stopped" } # 路由 case "$1" in start) start ;; stop) stop ;; restart) restart ;; status) status ;; *) echo "Usage: $0 {start|stop|restart|status}"; exit 1 ;; esac操作命令
./uvicorn.sh start # 后台启动 ./uvicorn.sh stop # 优雅停止 ./uvicorn.sh restart # 先停后启 ./uvicorn.sh status # 查看运行状态 tail -f run.log # 实时日志