Python3.11 离线安装第三方依赖完整教程（Linux x86_64 内网无网络环境）

一、问题背景与报错分析

1.1 业务场景

在内网隔离、无外网访问的Linux服务器环境中，部署Python项目时，项目启动脚本、Makefile编译脚本会自动调用pip联网拉取第三方依赖包。由于服务器无法访问外网PyPI镜像源，导致依赖安装失败，项目无法正常启动。

此类场景常见于服务器内网隔离、生产环境禁外网、DNS解析故障、代理配置失效、镜像源访问受限等工况，是线下服务器部署Python项目的高频问题。

1.2 核心报错信息

项目启动时控制台输出如下联网重试、连接失败日志（镜像源访问失败核心报错）：

text 复制代码

Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple/
WARNING: Retrying ...
Failed to establish a new connection: [Errno -2] Name or service not known

1.3 报错根因

1、目标内网服务器无法解析、访问清华PyPI镜像源，网络层面无法连通外网包管理器；

2、项目自动化部署脚本默认强制联网安装依赖，未适配离线部署场景；

3、前置内核模块编译、加载流程均执行成功，项目失败的核心卡点仅为Python依赖联网安装阶段。

二、项目依赖环境与包清单梳理

2.1 运行环境硬性要求

Python版本：3.11（核心！所有离线包必须适配该版本）
系统架构：Linux x86_64
运行路径佐证 ：日志默认安装路径 /usr/lib64/python3.11/site-packages

重点避坑：绝对不能使用Python3.6、3.8等低版本wheel包，也不能使用Windows平台的依赖包，会直接出现安装失败、版本不兼容、模块导入异常等问题。

2.2 项目核心直接依赖包

项目requirements.txt文件定义的固定版本依赖：

text 复制代码

service-concurrency==4.5.1
system-monitor==7.0.0

同时项目编译脚本会单独强制安装PyYAML，因此核心必装依赖包含：

text 复制代码

yaml-tool
service-concurrency==4.5.1
system-monitor==7.0.0

2.3 间接依赖完整清单

oslo.concurrency 为开源工具集，存在大量嵌套间接依赖，离线部署需完整准备，否则会出现模块缺失报错，完整依赖如下：

text 复制代码

pkg-build、config-core、i18n-tool、utils-kit、lock-tool、network-addr
network-interface、time-format、plugin-manage、url-parse、http-request、pkg-manage、grammar-parse

三、离线依赖包下载（有网环境实操）

离线部署的核心是：在和目标服务器环境一致的有网设备上，下载适配版本的依赖包，推荐使用Python3.11 + Linux x86_64环境下载，最大程度规避兼容问题。

3.1 搭建专属下载环境

若无多余Linux服务器，可通过Miniconda快速创建隔离的Python3.11下载环境，不污染本地全局环境：

bash 复制代码

# 创建Python3.11专属环境
conda create -n py311-download python=3.11 pip -y
# 激活环境
conda activate py311-download
# 创建包存储目录
mkdir -p wheels

3.2 Linux有网环境下载命令

bash 复制代码

# 批量下载核心依赖及所有间接依赖
pip download yaml-tool service-concurrency==4.5.1 system-monitor==7.0.0 -d wheels

3.3 Windows有网环境适配下载命令

若仅能通过Windows设备下载，必须手动指定Linux系统、x86_64架构、Python3.11版本，否则会默认下载Windows适配包：

powershell 复制代码

pip download yaml-tool service-concurrency==4.5.1 system-monitor==7.0.0 --platform manylinux2014_x86_64 --python-version 311 --implementation cp --abi cp311 --only-binary=:all: -d wheels

3.4 缺失包单独补全

网络接口工具包偶尔无法自动下载适配wheel包，可单独手动下载、编译：

bash 复制代码

# 下载指定版本源码/包文件
pip download network-interface==0.11.0 -d wheels
# 手动编译生成适配Python3.11的wheel包
pip wheel network-interface==0.11.0 -w wheels

3.5 合格包文件校验标准

正常适配包命名格式（可直接用于离线安装）：

network_interface-0.11.0-cp311-cp311-linux_x86_64.whl
yaml_tool-6.0.3-cp311-cp311-manylinux2014_x86_64.whl

特殊兼容包：abi3后缀包（如system-monitor）可兼容多版本Python3，可正常使用

废弃无效包（禁止使用）：cp36、cp38等低版本、Windows架构后缀的wheel包

备注：若仅下载到.tar.gz源码包，也可传输至离线服务器，但服务器需提前安装gcc、python3-devel编译依赖，否则无法安装。

四、离线包传输与目录部署

4.1 打包传输（避免文件损坏）

单文件拷贝易出现损坏、丢失，推荐整体打包压缩后传输至内网服务器：

bash 复制代码

# 压缩整个依赖包目录
tar czf wheels.tar.gz wheels/

4.2 服务器目录部署

将压缩包上传至项目根目录，解压后目录结构如下（标准规范）：

text 复制代码

项目根目录/
  requirements.txt
  run.py
  wheels/  # 离线依赖包目录
    service-concurrency-4.5.1-py3-none-any.whl
    system-monitor-7.0.0-xxx.whl
    network-interface-0.11.0-cp311-cp311-linux_x86_64.whl
    其余所有间接依赖wheel包

五、内网服务器离线安装实操

所有操作均在项目根目录 下执行，采用--no-index禁用联网检索，--find-links指定本地包目录。

5.1 分步离线安装命令

bash 复制代码

# 1. 安装核心依赖yaml-tool
pip3 install --no-index --find-links=./wheels yaml-tool

# 2. 安装专项适配包network-interface
pip3 install --no-index --find-links=./wheels network-interface==0.11.0

# 3. 批量安装requirements.txt所有依赖
pip3 install --no-index --find-links=./wheels -r requirements.txt

5.2 安装成功标准日志

出现如下批量安装成功日志，代表依赖全部部署完成：

text 复制代码

Successfully installed lock-tool-0.20 time-format-2.1.0 network-addr-0.10.1 service-concurrency-4.5.1 config-core-10.6.0 i18n-tool-6.9.0 utils-kit-10.1.1 pkg-build-7.0.3 system-monitor-7.0.0 url-parse-2.0.0 plugin-manage-5.9.0

5.3 常见ROOT警告说明

安装过程中出现以下警告非报错，可直接忽略：

text 复制代码

WARNING: Running pip as the 'root' user can result in broken permissions...

该警告仅提示root用户安装包可能与系统包管理器权限冲突，不影响依赖正常使用和项目运行。

六、依赖完整性校验

安装完成后，必须通过模块导入校验依赖是否可用，避免后续项目启动报错。执行以下命令无报错、输出ok即为正常：

bash 复制代码

python3 -c "import system_monitor; import service_concurrency; import network_addr; print('依赖安装校验成功：ok')"

校验通过后，即可正常启动项目：

bash 复制代码

python3 run.py

七、高频问题排查与解决方案

7.1 问题一：No matching distribution found for network-interface

报错日志

text 复制代码

ERROR: Could not find a version that satisfies the requirement network-interface>=0.10.4
ERROR: No matching distribution found for network-interface>=0.10.4

根因

离线包版本与服务器Python3.11不匹配，大概率下载了Python3.6/3.8低版本network-interface工具包。

解决方案

在有网环境重新编译生成适配3.11的包，替换原有错误包后重新安装：

bash 复制代码

pip wheel network-interface==0.11.0 -w wheels

7.2 问题二：Wheel is invalid 包无效报错

报错日志

text 复制代码

ERROR: Wheel 'network-addr' located at .../network_addr-1.3.0-py3-none-any.whl is invalid.

根因

离线包传输损坏、新版本包存在兼容bug，导致wheel包无法解析安装。

解决方案

删除服务器中损坏的高版本无效包；

有网环境下载稳定兼容低版本包：network-addr==0.10.1；

重新执行离线安装命令完成部署。

bash 复制代码

pip download network-addr==0.10.1 -d wheels
pip3 install --no-index --find-links=./wheels -r requirements.txt

7.3 问题三：make install 仍然强制联网

问题现象

手动离线安装所有依赖后，执行make编译命令仍会尝试联网下载yaml-tool工具包，导致部署失败。

根因

项目Makefile中存在强制安装命令，会忽略本地已安装依赖，强制联网拉取镜像源包：

bash 复制代码

pip3 install --ignore-installed yaml-tool -i https://pypi.tuna.tsinghua.edu.cn/simple/ --trusted-host pypi.tuna.tsinghua.edu.cn

解决方案

依赖离线安装校验成功后，跳过make install联网安装流程，直接启动项目即可：

bash 复制代码

python3 run.py

八、实操总结与避坑贴士

版本绝对匹配：离线包Python版本、系统架构必须与目标服务器完全一致，是部署成功的核心；
优先使用wheel包：相比tar源码包，wheel包无需本地编译，规避服务器缺少gcc编译依赖的问题；
整包传输不单独拷贝：打包压缩传输可杜绝文件损坏、丢失问题；
适配离线脚本：内网环境务必跳过项目自带的联网安装脚本，避免重复联网报错；
安装后必校验：通过模块导入命令校验依赖完整性，提前规避项目启动异常。