Python依赖包离线部署完整指南

背景介绍

在企业级生产环境中，由于安全、合规或网络限制等因素，服务器往往无法直接访问互联网。这种”离线环境”或”内网环境”给Python应用的部署带来了挑战，特别是依赖包的安装问题。本文将详细介绍如何将Python项目及其依赖包从有网络的开发环境迁移到无网络的生产环境。

核心思路

离线部署的核心思路是：

  1. 在有网络的环境中收集所有依赖包
  2. 将依赖包文件打包传输到离线环境
  3. 在离线环境中使用本地依赖包进行安装

详细步骤

第一步：生成依赖清单

在开发环境中，使用以下命令生成当前环境的依赖清单：

1
pip freeze > requirements.txt

命令详解：

  • pip：Python包管理工具
  • freeze：显示当前环境中已安装包的列表及其确切版本号
  • >：重定向符号，将命令输出保存到文件中
  • requirements.txt：输出的文件名，这是Python项目中约定俗成的依赖文件名

命令作用：
将当前Python环境中安装的所有包及其版本号以”包名==版本号”的格式保存到requirements.txt文件中。例如：

1
2
3
numpy==1.21.0
pandas==1.3.0
requests==2.25.1

注意事项：

  • 建议在虚拟环境中执行此命令，避免包含系统级包
  • 检查生成的requirements.txt，确保版本号正确
  • 可以手动编辑requirements.txt，移除不必要的依赖

第二步：下载依赖包

在有网络的机器上执行以下命令之一来下载所有依赖包：

方法一：使用pip download（推荐）

1
pip download -d python_packages -r requirements.txt

命令详解：

  • pip：Python包管理工具
  • download：下载包但不安装的子命令
  • -d python_packages：指定下载目录为python_packages文件夹
    • -d是--dest的简写，表示destination（目标目录）
  • -r requirements.txt：从requirements.txt文件读取要下载的包列表
    • -r是--requirement的简写

命令作用：
从PyPI（Python包索引）下载requirements.txt中列出的所有包及其依赖，保存到python_packages目录中。下载的是源码包（.tar.gz）或预编译包（.whl）。

方法二：使用pip wheel

1
pip wheel -w python_packages -r requirements.txt

命令详解：

  • pip：Python包管理工具
  • wheel：构建wheel格式包的子命令
  • -w python_packages：指定wheel文件输出目录
    • -w是--wheel-dir的简写
  • -r requirements.txt：从requirements.txt文件读取包列表

命令作用：
下载并构建requirements.txt中的包为wheel格式（.whl文件）。Wheel是Python的标准分发格式，安装速度更快。

方法三：使用python -m pip wheel

1
python -m pip wheel -w python_packages -r requirements.txt

命令详解：

  • python：Python解释器
  • -m：以模块方式运行，表示”module”
  • pip：要运行的模块名称
  • 其余参数同方法二

命令作用：
功能与方法二相同，但通过Python解释器直接调用pip模块，确保使用正确的pip版本。

三种方法的区别：

  • pip download：下载原始格式的包（可能是源码包或wheel包）
  • pip wheel：下载并构建为wheel格式
  • python -m pip：更明确指定使用哪个Python环境的pip

参数说明总结：

  • -d 或 --dest：指定下载目录
  • -w 或 --wheel-dir：指定wheel文件输出目录
  • -r 或 --requirement：从文件读取依赖列表
  • -m：以模块方式运行程序

第三步：处理平台兼容性

如果开发环境和生产环境的架构不同（如开发环境是Windows/macOS，生产环境是Linux），需要指定目标平台：

1
2
# 下载Linux x86_64平台的包
pip download -d python_packages -r requirements.txt --platform linux_x86_64 --only-binary=:all:

命令详解：

  • --platform linux_x86_64：指定目标平台架构
    • linux_x86_64表示Linux操作系统的64位x86架构
    • 其他常见平台：win_amd64（Windows 64位）、macosx_10_9_x86_64（macOS）
  • --only-binary=:all:：只下载预编译的二进制包
    • :all:表示对所有包都应用此规则
    • 避免下载需要编译的源码包

命令作用：
专门下载适用于指定平台的包版本，确保在目标环境中能正确安装和运行。

1
2
# 或者下载所有平台的包
pip download -d python_packages -r requirements.txt --platform any

命令详解：

  • --platform any：下载平台无关的包
    • any表示不限定特定平台
    • 适用于纯Python包（不包含C扩展的包）

为什么需要指定平台：

  • Python包可能包含C扩展模块，这些模块需要针对特定操作系统和架构编译
  • 在Windows上下载的包可能无法在Linux上运行
  • 通过指定平台，确保下载的包与目标环境兼容

第四步：传输到离线环境

将下载的python_packages目录和requirements.txt文件传输到离线的生产服务器上。

传输方式说明：

  1. SCP（Secure Copy Protocol）命令示例：
1
2
# 将文件从本地传输到远程服务器
scp -r python_packages/ requirements.txt user@server_ip:/path/to/destination/

命令详解：

  • scp：安全拷贝命令，通过SSH协议传输文件
  • -r：递归传输，用于传输整个目录
  • python_packages/：源目录
  • requirements.txt：要传输的文件
  • user@server_ip：目标服务器的用户名和IP地址
  • :/path/to/destination/：目标服务器上的路径
  1. 创建压缩包传输：
1
2
# 创建压缩包（在有网络的机器上）
tar -czf python_offline_packages.tar.gz python_packages/ requirements.txt

命令详解：

  • tar：打包和压缩工具
  • -c：创建新的归档文件（create）
  • -z：使用gzip压缩（compress with gzip）
  • -f：指定归档文件名（file）
  • python_offline_packages.tar.gz：输出的压缩包文件名
  • python_packages/ requirements.txt：要打包的文件和目录
1
2
# 在目标服务器上解压
tar -xzf python_offline_packages.tar.gz

命令详解：

  • -x：解压归档文件（extract）
  • -z：使用gzip解压
  • -f：指定要解压的文件名
  1. 其他传输方式：
  • SFTP：图形化文件传输工具
  • USB存储设备：物理媒介传输
  • 内网文件服务器：通过共享文件夹

第五步：离线安装

在离线环境中执行以下命令安装依赖：

1
pip install --no-index --find-links=python_packages -r requirements.txt

命令详解：

  • pip：Python包管理工具
  • install：安装包的子命令
  • --no-index：不使用PyPI等在线包索引
    • 告诉pip不要尝试从互联网下载包
    • 只使用本地指定的包源
  • --find-links=python_packages：指定本地包目录
    • --find-links告诉pip在哪里查找包文件
    • python_packages是我们之前下载包的目录
  • -r requirements.txt：从requirements.txt文件读取要安装的包列表

命令作用：
从本地python_packages目录中查找并安装requirements.txt中指定的所有包，完全不依赖网络连接。

或者使用：

1
python -m pip install --no-index --find-links=python_packages -r requirements.txt

命令详解：

  • python：Python解释器
  • -m pip：以模块方式运行pip
    • 确保使用当前Python环境对应的pip版本
    • 在有多个Python版本的系统中特别有用
  • 其余参数功能相同

两种命令的选择：

  • 直接使用pip：简单快捷，适合大多数情况
  • 使用python -m pip：更精确，确保版本匹配，推荐在复杂环境中使用

安装过程说明：

  1. pip读取requirements.txt文件
  2. 对每个包，在python_packages目录中查找匹配的文件
  3. 按照依赖关系顺序安装包
  4. 完成后，所有包都安装到当前Python环境中

python -m pip 的作用和优势

python -m pip 通过模块执行方式调用pip，相比直接使用pip命令有以下优势：

命令详解：

  • python：Python解释器程序
  • -m：”module”的缩写，表示以模块方式运行
  • pip：要运行的模块名称

详细作用说明：

  1. 版本一致性：确保使用当前Python解释器对应的pip版本
    • 当系统有多个Python版本时（如Python 2.7、Python 3.8、Python 3.9）
    • 直接使用pip可能调用错误版本的pip
    • python -m pip明确使用当前python命令对应的pip

举例说明：

1
2
3
4
# 假设系统有多个Python版本
/usr/bin/python2.7 -m pip install package  # 使用Python 2.7的pip
/usr/bin/python3.8 -m pip install package  # 使用Python 3.8的pip
/usr/bin/python3.9 -m pip install package  # 使用Python 3.9的pip
  1. 路径问题避免：在某些系统中，pip可能不在PATH环境变量中
    • PATH是系统查找可执行文件的路径列表
    • 如果pip不在PATH中，直接运行pip会提示”命令未找到”
    • python -m pip通过Python解释器查找pip模块，绕过PATH问题
  2. 权限问题：在某些受限环境中更容易执行
    • 有些企业环境限制直接执行外部命令
    • 但允许通过Python解释器运行模块
    • python -m pip被视为Python脚本的一部分，更容易获得执行权限
  3. 虚拟环境明确性：在虚拟环境中确保使用正确的pip
1
2
3
# 激活虚拟环境后
source venv/bin/activate
python -m pip install package  # 明确使用虚拟环境的pip

实际应用场景：

  • Docker容器中：确保使用容器内Python环境的pip
  • CI/CD流水线：在自动化脚本中确保版本一致性
  • 企业内网环境：绕过命令行工具的权限限制
  • 开发环境切换：在不同项目的虚拟环境间切换时保证正确性

常见踩坑点及解决方案

1. 架构不匹配问题

问题：在Windows上下载的包无法在Linux上安装
解决方案：

1
2
# 明确指定目标平台
pip download -d python_packages -r requirements.txt --platform linux_x86_64 --only-binary=:all:

2. 编译依赖问题

问题：某些包需要编译，离线环境缺少编译工具
解决方案：

  • 优先下载预编译的wheel包
  • 在相同环境的有网络机器上进行编译打包
1
2
# 强制使用预编译包
pip download -d python_packages -r requirements.txt --only-binary=:all:

命令详解：

  • --only-binary=:all:：对所有包都只下载预编译版本
  • 预编译包（wheel格式）无需编译，可以直接安装
  • 避免在离线环境中因缺少编译工具而安装失败

3. 依赖版本冲突

问题：requirements.txt中的版本在离线环境中冲突
解决方案：

  • 使用pip-tools生成精确的依赖树
  • 在有网络环境中先测试安装
1
2
3
4
5
# 安装pip-tools
pip install pip-tools

# 生成精确的依赖版本
pip-compile requirements.in

命令详解：

  • pip-tools：Python依赖管理工具，可以锁定依赖版本
  • pip-compile：pip-tools的命令，用于生成精确的依赖文件
  • requirements.in：输入文件，包含顶层依赖（不指定具体版本）
  • 输出requirements.txt：包含所有依赖及其精确版本号

工作原理：

  1. requirements.in文件写入主要依赖：
    1
    2
    3
    django
    requests
    pandas
  2. pip-compile会解析所有子依赖，生成带版本号的requirements.txt：
    1
    2
    3
    4
    django==3.2.9
    requests==2.25.1
    pandas==1.3.4
    numpy==1.21.2  # pandas的依赖

4. 系统包依赖

问题：某些Python包依赖系统级库
解决方案：

  • 提前在离线环境安装系统依赖
  • 使用Docker容器统一环境

5. 大文件传输问题

问题：依赖包总大小过大，传输困难
解决方案：

1
2
3
4
5
# 创建压缩包
tar -czf python_packages.tar.gz python_packages/ requirements.txt

# 在目标机器解压
tar -xzf python_packages.tar.gz

命令详解：

  • tar -czf：创建压缩包
    • -c：创建（create）
    • -z：使用gzip压缩（compress）
    • -f：指定文件名（file）
  • python_packages.tar.gz：压缩包文件名
  • tar -xzf：解压缩包
    • -x：解压（extract）
    • -z：解压gzip格式
    • -f：指定要解压的文件

压缩效果：
通常可以将几百MB的依赖包压缩到几十MB，大大减少传输时间。

高级技巧

1. 使用虚拟环境

1
2
3
4
5
6
7
# 在离线环境创建虚拟环境
python -m venv offline_env
source offline_env/bin/activate  # Linux/macOS
# offline_env\Scripts\activate  # Windows

# 在虚拟环境中安装
pip install --no-index --find-links=python_packages -r requirements.txt

命令详解：

  • python -m venv offline_env：创建名为offline_env的虚拟环境
    • venv：Python内置的虚拟环境模块
    • offline_env：虚拟环境目录名称
  • source offline_env/bin/activate：激活虚拟环境（Linux/macOS）
    • source：执行脚本并在当前shell中生效
    • 激活后，命令行提示符会显示虚拟环境名称
  • offline_env\Scripts\activate：Windows下的激活命令
  • 在虚拟环境中安装的包不会影响系统Python环境

2. 创建本地PyPI镜像

对于大型项目，可以创建本地PyPI镜像：

1
2
3
# 使用bandersnatch创建本地镜像
pip install bandersnatch
bandersnatch mirror

命令详解：

  • bandersnatch：PyPI镜像同步工具
  • bandersnatch mirror：创建完整的PyPI镜像副本
  • 需要大量磁盘空间（TB级别）和时间
  • 适合需要频繁部署多个项目的大型企业

3. Docker化部署

1
2
3
4
5
6
7
8
9
FROM python:3.9-slim

COPY python_packages/ /tmp/python_packages/
COPY requirements.txt /tmp/

RUN pip install --no-index --find-links=/tmp/python_packages -r /tmp/requirements.txt

# 清理临时文件
RUN rm -rf /tmp/python_packages /tmp/requirements.txt

验证部署

安装完成后，验证依赖是否正确安装：

1
2
3
4
5
6
7
8
# 检查已安装的包
pip list

# 验证关键包是否可用
python -c "import your_main_package; print('Import successful')"

# 运行简单测试
python your_main_script.py

命令详解：

  • pip list：显示当前环境中已安装的所有包及版本
  • python -c "..."：执行单行Python代码
    • -c表示”command”，后面跟Python代码字符串
    • import your_main_package：尝试导入主要的包
    • 如果导入成功，说明包已正确安装
  • python your_main_script.py：运行实际的应用程序进行测试

最佳实践总结

  1. 使用虚拟环境：避免污染系统Python环境
  2. 版本锁定：在requirements.txt中明确指定版本号
  3. 平台一致性：确保开发、打包、部署环境的一致性
  4. 测试先行：在模拟离线环境中先测试部署流程
  5. 文档记录：记录部署步骤和遇到的问题
  6. 定期更新：建立依赖包更新的流程和机制

自动化脚本示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
#!/bin/bash
# offline_deploy.sh - 自动化离线部署脚本

set -e

PROJECT_NAME="your_project"
PACKAGES_DIR="python_packages"

echo "开始准备离线部署包..."

# 清理旧文件
rm -rf $PACKAGES_DIR
mkdir -p $PACKAGES_DIR

# 生成requirements.txt
pip freeze > requirements.txt

# 下载依赖包
pip download -d $PACKAGES_DIR -r requirements.txt

# 创建部署包
tar -czf ${PROJECT_NAME}_offline_deploy.tar.gz $PACKAGES_DIR requirements.txt

echo "离线部署包准备完成: ${PROJECT_NAME}_offline_deploy.tar.gz"
echo "传输到目标服务器后，执行以下命令进行安装："
echo "tar -xzf ${PROJECT_NAME}_offline_deploy.tar.gz"
echo "pip install --no-index --find-links=$PACKAGES_DIR -r requirements.txt"

脚本详解：

  • #!/bin/bash：指定使用bash解释器执行脚本
  • set -e：遇到任何错误立即退出脚本
  • PROJECT_NAME和PACKAGES_DIR：定义变量，便于修改和重用
  • rm -rf $PACKAGES_DIR：删除旧的包目录（如果存在）
    • -r：递归删除
    • -f：强制删除，不询问
  • mkdir -p $PACKAGES_DIR：创建包目录
    • -p：如果父目录不存在则创建
  • echo：输出提示信息
  • ${PROJECT_NAME}：变量引用语法，获取变量值

使用方法：

  1. 保存为文件：offline_deploy.sh
  2. 添加执行权限：chmod +x offline_deploy.sh
  3. 运行脚本：./offline_deploy.sh

通过遵循以上步骤和最佳实践，你可以顺利地将Python应用部署到无网络的生产环境中。记住，每个环境都可能有其特殊性，需要根据实际情况进行调整和优化。