1. 为什么需要离线部署Python项目在企业开发环境中经常会遇到生产服务器无法连接外网的情况。这时候就需要把开发好的Python项目完整迁移到离线环境中运行。我遇到过不少团队直接把开发机的整个虚拟环境打包复制过去结果发现要么依赖缺失要么平台不兼容最后项目根本跑不起来。离线部署的核心难点在于精准控制依赖关系。开发环境通常装了很多实验性包而生产环境只需要项目实际用到的依赖。更麻烦的是Windows/Mac开发的包可能无法直接在Linux服务器运行这就是为什么需要专门处理跨平台兼容性问题。去年我们团队就踩过这样的坑一个数据分析项目在开发机运行完美部署到客户内网服务器却报Could not find a version that satisfies the requirement。后来发现是因为客户服务器用的是CentOS 7而我们开发时用的是Python 3.8客户环境却是Python 3.6。这种版本差异导致的兼容性问题正是离线部署需要重点解决的。2. 精准导出项目依赖清单2.1 使用pipreqs提取最小依赖集大多数人的第一个误区是直接pip freeze requirements.txt。这个方法会导出环境里所有安装的包包括你根本用不到的依赖。我推荐使用pipreqs这个工具它能通过扫描项目代码中的import语句只生成项目实际需要的依赖清单。安装方法很简单pip install pipreqs使用时进入项目根目录执行pipreqs ./ --encodingutf-8 --force这里的--force参数会覆盖已有的requirements.txt--encoding参数可以避免中文路径报错。我去年给某银行做项目时就因为他们代码路径包含中文导致生成失败加上编码参数才解决。生成的requirements.txt示例scipy1.7.3 numpy1.21.2 pandas1.3.22.2 处理特殊依赖情况有些情况需要特别注意动态导入的包比如通过__import__()或importlib动态加载的模块pipreqs可能检测不到。这时需要手动补充到requirements.txt系统依赖像PyMySQL需要libmysqlclient-dev这样的系统库记得在部署文档中注明环境标记比如只在Windows需要的pywin32可以用; sys_platform win32标注3. 下载跨平台兼容的依赖包3.1 使用pip download下载离线包拿到干净的requirements.txt后接下来要下载能在目标平台运行的包文件。关键是要用pip download而不是简单的pip installpip download -d ./offline_packages -r requirements.txt \ --platform manylinux2014_x86_64 \ --python-version 3.6 \ --only-binary:all: \ -i https://pypi.tuna.tsinghua.edu.cn/simple \ --trusted-host pypi.tuna.tsinghua.edu.cn这个命令有几个关键参数-d指定包下载目录--platform设置目标平台比如manylinux2014_x86_64适用于CentOS/RHEL 7--python-version指定目标Python版本--only-binary强制下载二进制包避免编译问题3.2 解决常见下载错误错误1Could not find a version that satisfies the requirement这个报错通常有三大原因拼写错误检查requirements.txt里的包名是否正确比如经常有人把PyMySQL写成pymysql版本不存在有些包的版本可能已被作者删除可以去pypi.org确认平台不兼容比如在Mac上下载windows-only的包错误2No matching distribution found我遇到最棘手的情况是某安全项目需要旧版cryptography1.9但PyPI上已经找不到。最后是通过公司内网镜像站找到历史版本解决的。如果你们也有类似需求建议搭建本地PyPI镜像。4. 离线环境安装实战4.1 准备离线安装环境把下载好的包目录示例中的offline_packages和requirements.txt打包通过U盘或内网传输到目标服务器。这里有个细节最好保持目录结构不变因为有些包的安装依赖相对路径。在目标服务器上建议先创建干净的虚拟环境python -m venv /opt/myproject source /opt/myproject/bin/activate4.2 执行离线安装进入包目录后运行pip install --no-index --find-links./offline_packages -r requirements.txt参数说明--no-index禁止从PyPI下载--find-links指定本地包目录4.3 验证安装结果安装完成后别急着收工建议做以下检查运行pip list对比与requirements.txt的差异执行项目的单元测试检查是否有运行时缺失的.so文件常见于NumPy等科学计算包5. 高级技巧与避坑指南5.1 处理C扩展包编译问题有些包像psycopg2需要编译C扩展如果目标环境缺少gcc等工具链会安装失败。对此有两种解决方案下载预编译的wheel文件文件名带平台标识如manylinux在相同环境的联网机器上编译好后打包5.2 构建自包含的部署包对于需要频繁部署的场景我习惯用下面这个脚本打包所有依赖#!/bin/bash # 打包Python解释器、虚拟环境和项目代码 PYTHON_VERSION3.8.12 TARGET_PLATFORMlinux_x86_64 # 下载指定版本的Python源码 wget https://www.python.org/ftp/python/${PYTHON_VERSION}/Python-${PYTHON_VERSION}.tar.xz tar xf Python-${PYTHON_VERSION}.tar.xz cd Python-${PYTHON_VERSION} # 编译安装到独立目录 ./configure --prefix/tmp/pybuild/python-${PYTHON_VERSION} make make install # 创建虚拟环境 /tmp/pybuild/python-${PYTHON_VERSION}/bin/python3 -m venv /tmp/pybuild/venv5.3 版本冲突的终极解决方案当遇到Package A requires B1.0 but you have B2.0这类问题时可以尝试使用pip download --no-deps单独下载问题包用--ignore-installed强制安装指定版本考虑用docker容器隔离不同版本的依赖某次金融项目部署时我们遇到tensorflow与h5py的版本冲突最后是通过构建不同的conda环境才解决。这种复杂依赖场景下容器化确实是最佳实践。
Python离线部署实战：精准导出项目依赖与跨平台离线安装避坑指南
1. 为什么需要离线部署Python项目在企业开发环境中经常会遇到生产服务器无法连接外网的情况。这时候就需要把开发好的Python项目完整迁移到离线环境中运行。我遇到过不少团队直接把开发机的整个虚拟环境打包复制过去结果发现要么依赖缺失要么平台不兼容最后项目根本跑不起来。离线部署的核心难点在于精准控制依赖关系。开发环境通常装了很多实验性包而生产环境只需要项目实际用到的依赖。更麻烦的是Windows/Mac开发的包可能无法直接在Linux服务器运行这就是为什么需要专门处理跨平台兼容性问题。去年我们团队就踩过这样的坑一个数据分析项目在开发机运行完美部署到客户内网服务器却报Could not find a version that satisfies the requirement。后来发现是因为客户服务器用的是CentOS 7而我们开发时用的是Python 3.8客户环境却是Python 3.6。这种版本差异导致的兼容性问题正是离线部署需要重点解决的。2. 精准导出项目依赖清单2.1 使用pipreqs提取最小依赖集大多数人的第一个误区是直接pip freeze requirements.txt。这个方法会导出环境里所有安装的包包括你根本用不到的依赖。我推荐使用pipreqs这个工具它能通过扫描项目代码中的import语句只生成项目实际需要的依赖清单。安装方法很简单pip install pipreqs使用时进入项目根目录执行pipreqs ./ --encodingutf-8 --force这里的--force参数会覆盖已有的requirements.txt--encoding参数可以避免中文路径报错。我去年给某银行做项目时就因为他们代码路径包含中文导致生成失败加上编码参数才解决。生成的requirements.txt示例scipy1.7.3 numpy1.21.2 pandas1.3.22.2 处理特殊依赖情况有些情况需要特别注意动态导入的包比如通过__import__()或importlib动态加载的模块pipreqs可能检测不到。这时需要手动补充到requirements.txt系统依赖像PyMySQL需要libmysqlclient-dev这样的系统库记得在部署文档中注明环境标记比如只在Windows需要的pywin32可以用; sys_platform win32标注3. 下载跨平台兼容的依赖包3.1 使用pip download下载离线包拿到干净的requirements.txt后接下来要下载能在目标平台运行的包文件。关键是要用pip download而不是简单的pip installpip download -d ./offline_packages -r requirements.txt \ --platform manylinux2014_x86_64 \ --python-version 3.6 \ --only-binary:all: \ -i https://pypi.tuna.tsinghua.edu.cn/simple \ --trusted-host pypi.tuna.tsinghua.edu.cn这个命令有几个关键参数-d指定包下载目录--platform设置目标平台比如manylinux2014_x86_64适用于CentOS/RHEL 7--python-version指定目标Python版本--only-binary强制下载二进制包避免编译问题3.2 解决常见下载错误错误1Could not find a version that satisfies the requirement这个报错通常有三大原因拼写错误检查requirements.txt里的包名是否正确比如经常有人把PyMySQL写成pymysql版本不存在有些包的版本可能已被作者删除可以去pypi.org确认平台不兼容比如在Mac上下载windows-only的包错误2No matching distribution found我遇到最棘手的情况是某安全项目需要旧版cryptography1.9但PyPI上已经找不到。最后是通过公司内网镜像站找到历史版本解决的。如果你们也有类似需求建议搭建本地PyPI镜像。4. 离线环境安装实战4.1 准备离线安装环境把下载好的包目录示例中的offline_packages和requirements.txt打包通过U盘或内网传输到目标服务器。这里有个细节最好保持目录结构不变因为有些包的安装依赖相对路径。在目标服务器上建议先创建干净的虚拟环境python -m venv /opt/myproject source /opt/myproject/bin/activate4.2 执行离线安装进入包目录后运行pip install --no-index --find-links./offline_packages -r requirements.txt参数说明--no-index禁止从PyPI下载--find-links指定本地包目录4.3 验证安装结果安装完成后别急着收工建议做以下检查运行pip list对比与requirements.txt的差异执行项目的单元测试检查是否有运行时缺失的.so文件常见于NumPy等科学计算包5. 高级技巧与避坑指南5.1 处理C扩展包编译问题有些包像psycopg2需要编译C扩展如果目标环境缺少gcc等工具链会安装失败。对此有两种解决方案下载预编译的wheel文件文件名带平台标识如manylinux在相同环境的联网机器上编译好后打包5.2 构建自包含的部署包对于需要频繁部署的场景我习惯用下面这个脚本打包所有依赖#!/bin/bash # 打包Python解释器、虚拟环境和项目代码 PYTHON_VERSION3.8.12 TARGET_PLATFORMlinux_x86_64 # 下载指定版本的Python源码 wget https://www.python.org/ftp/python/${PYTHON_VERSION}/Python-${PYTHON_VERSION}.tar.xz tar xf Python-${PYTHON_VERSION}.tar.xz cd Python-${PYTHON_VERSION} # 编译安装到独立目录 ./configure --prefix/tmp/pybuild/python-${PYTHON_VERSION} make make install # 创建虚拟环境 /tmp/pybuild/python-${PYTHON_VERSION}/bin/python3 -m venv /tmp/pybuild/venv5.3 版本冲突的终极解决方案当遇到Package A requires B1.0 but you have B2.0这类问题时可以尝试使用pip download --no-deps单独下载问题包用--ignore-installed强制安装指定版本考虑用docker容器隔离不同版本的依赖某次金融项目部署时我们遇到tensorflow与h5py的版本冲突最后是通过构建不同的conda环境才解决。这种复杂依赖场景下容器化确实是最佳实践。
