探索 Python 应用的分层依赖：解决 Linux 环境中的 libvirt-python 安装问题

探索 Python 应用的分层依赖：解决 Linux 环境中的 libvirt-python 安装问题
- 背景
- Python 版本升级
  - 问题描述
  - 原因分析与解决方案
- Python 应用的分层依赖：安装与部署的视角
- libvirt-python的分层依赖
- 尝试的解决方案
  - 使用编译好的 .whl 文件
  - "嫁接"整个package
- 小结
- 参考
- 附录
  - Python 应用分层依赖的完整结构

探索 Python 应用的分层依赖：解决 Linux 环境中的 libvirt-python 安装问题

背景

在 Ubuntu-22.0 和国内某常用Linux发行版1070 上用 Python 开发基于 libvrt-python 的应用，在 Ubuntu 平台的开发过程中一切顺利，但在国内某常用Linux发行版上开发时，遇到了两个关键问题：

Python 版本限制：应用需要 Python 3.10 及以上版本，而国内某常用Linux发行版自带的 Python 版本为 3.7.3，因此需要升级 Python 版本。
libvirt-python 包不可用：在 Ubuntu 平台，libvirt-python 包能够正常安装和使用，但在国内某常用Linux发行版上，即使升级了 Python 版本，依然无法成功安装和使用此包，成为开发的主要障碍。

本文将重点分析和解决 libvirt-python 包不可用的问题。在此之前，简单回顾 Python 版本升级的过程。

Python 版本升级

问题描述

国内某常用Linux发行版 1070 自带的 Python 版本为 3.7.3，但应用需要 Python 3.10 及以上版本。尝试升级 Python 到 3.10.15 版本时，遇到了以下问题：

系统权限限制：国内某常用Linux发行版系统默认需要开启“开发者模式”才能使用 sudo 命令安装软件包。
安装失败：即使开启了“开发者模式”，在源码安装 Python 3.10.15 的过程中仍然出现 “Segment Fault” 错误，导致安装失败。

原因分析与解决方案

煎熬了两天，各种搜索未果后，我已经准备上gdb来调试了，偶然获得"高人"指点，发现问题的根源在于 国内某常用Linux发行版的应用安全机制¹。国内某常用Linux发行版默认启用了应用签名限制，只允许运行经过签名的应用程序，即使是编译过程中生成的工具也不允许运行，从而引发了异常。

为了完成 Python 的安装，需要调整安全设置：

开始 —> 安全中心 —> 安全工具 —> 应用安全

将默认选项 “仅允许签名应用” 修改为 “允许任意应用”。

完成上述步骤后，重新尝试从源码安装 Python 3.10.15 即可成功。

虽然 Python 升级问题解决起来有些“曲折”，但相较于接下来的 libvirt-python 包问题，这只是一个小插曲。接下来将继续复盘如何处理 libvirt-python 包的不可用问题。

Python 应用的分层依赖：安装与部署的视角

在安装和部署 Python 应用时，依赖关系往往分为多个层次。从 Python 包的直接依赖，到系统级的共享库，最终到硬件支持，每一层的正确配置对于成功安装并运行 Python 应用至关重要。特别是在像国内某常用Linux发行版这样的操作系统环境中，理解这些层次关系对于顺利解决诸如 libvirt-python 这样的包安装问题具有重要意义。以下是 Python 应用安装和部署过程中的分层依赖结构：

这种依赖关系可以简单归纳如下：

应用层依赖：Python 包及其嵌套依赖（如 scikit-learn 的 numpy 依赖）。

环境层依赖：Python 解释器、包管理工具（pip）及虚拟环境（如 venv）。

二进制层依赖：Python 包中的 C 扩展模块和相关共享库，它们通常以 .so 文件形式存在，运行时候需要正确链接系统共享库。

系统层依赖：系统级共享库（如 glibc）、平台特定库（如 GPU 驱动），它们是二进制模块运行的基础。

硬件与内核层依赖：Linux 内核调用及硬件驱动支持。

接下来，我将基于这一分层模型，详细分析和解决 libvirt-python 的不可用问题。

libvirt-python的分层依赖

libvirt-python² 是一个通过 C 扩展形式实现的 Python 包，用于调用底层 libvirt 库函数，提供对虚拟化管理的接口支持。它的依赖关系横跨 Python 包层、二进制层、系统层，因此使用过程中容易出现多层依赖之间的兼容性问题。以下对具体报错情况进行分层分析。

libvirt-python 在官方文档中声明了以下编译限制条件：

Python 版本：Python >= 3.6
libvirt 版本：libvirt >= 0.9.11

虽然这些要求表面上看起来较为宽松，但在国内某常用Linux发行版环境下，安装 libvirt-python 10.8.0(默认就是这个版本)时却出现了以下报错：

$ /usr/local/python3.10/bin/python3 -m pip install libvirt-python
...
Building wheel for libvirt-python (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [55 lines of output]
      running bdist_wheel
      running build
      running build_py
      Missing type converters:
      virTypedParameterPtr *:1
      int *:1
      ERROR: failed virDomainGetLaunchDigest
...

从错误信息中可以看出，问题出现在构建 C 扩展的过程中。libvirt 库的接口通过 /usr/share/libvirt/api/libvirt-api.xml 文件进行定义和描述。而在构建 C 扩展时，libvirt-python 的 generator.py 脚本会检查每个绑定函数的签名是否与 libvirt 库提供的接口匹配。具体问题出在 virDomainGetLaunchDigest 函数，其签名中存在类型不匹配的情况，导致构建失败。

尝试的解决方案

使用编译好的 .whl 文件

针对接口类型检查失败的问题，最直接的解决方案是使用预编译的 .whl 文件安装 libvirt-python。由于实际使用的 API 接口较少，抱着侥幸心理，我尝试将 Ubuntu 22.04 上编译好的 libvirt-python-10.7.0-cp310-cp310-linux_x86_64.whl 文件安装到国内某常用Linux发行版 1070 环境中。

安装过程顺利完成，但在 import libvirt 时却报如下错误：

>>> import libvirt
Traceback (most recent call last):
  File "/home/test/.local/lib/python3.10/site-packages/libvirt.py", line 16, in <module>
    import cygvirtmod as libvirtmod  # type: ignore
ModuleNotFoundError: No module named 'cygvirtmod'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/test/.local/lib/python3.10/site-packages/libvirt.py", line 19, in <module>
    raise lib_e
  File "/home/test/.local/lib/python3.10/site-packages/libvirt.py", line 13, in <module>
    import libvirtmod  # type: ignore
ImportError: /lib/x86_64-linux-gnu/libvirt.so.0: version `LIBVIRT_7.7.0' not found

翻看代码，这里的逻辑是为了兼容cygwin的环境，先尝试导入cygvirtmod，如果导入失败，则尝试导入libvirtmod。在导入 libvirtmod 的时候，就出现了后续的错误。

进一步定位到 libvirtmod.cpython-310-x86_64-linux-gnu.so 文件，它是 libvirt-python 的C扩展模块，在运行时侯通过 ctypes 或直接绑定的方式与系统的 libvirt.so 动态库交互。如果 libvirt.so 的版本低于 C 扩展模块编译时的要求，缺少必要符号或函数，就会引发上述运行错误。

可以通过以下命令查看 libvirtmod.cpython-310-x86_64-linux-gnu.so 文件中依赖的符号表：

$ strings /home/test/.local/lib/python3.10/site-packages/libvirtmod.cpython-310-x86_64-linux-gnu.so

结果显示，该模块依赖多处 LIBVIRT_7.x.0 和 LIBVIRT_8.0.0 的符号。进一步确认系统环境差异：

Ubuntu 22.04 中的 libvirt 的版本：

test@M920t-N000:~$ virsh --version
8.0.0
test@M920t-N000:~$ ls -lr /usr/lib/x86_64-linux-gnu/libvirt.so
lrwxrwxrwx 1 root root 12  4月 13  2024 /usr/lib/x86_64-linux-gnu/libvirt.so -> libvirt.so.0
test@M920t-N000:~$ ls -lr /usr/lib/x86_64-linux-gnu/libvirt.so.0
lrwxrwxrwx 1 root root 19  4月 13  2024 /usr/lib/x86_64-linux-gnu/libvirt.so.0 -> libvirt.so.0.8000.0 
test@M920t-N000:~$ ls -lr /usr/lib/x86_64-linux-gnu/libvirt.so.0.8000.0
-rw-r--r-- 1 root root 4731576  4月 13  2024 /usr/lib/x86_64-linux-gnu/libvirt.so.0.8000.0

国内某常用Linux发行版 1070 中的 libvirt 版本：

$ virsh --version
5.0.0

显然，国内某常用Linux发行版上的 libvirt.so 版本无法满足 libvirt-python 对 LIBVIRT_7.x.0 或 LIBVIRT_8.0.0 的要求。

升级libvirt的可能

理论上，可以尝试将国内某常用Linux发行版的 libvirt 动态库升级到与 Ubuntu 一致的版本，但升级的工作量和风险极高。以 libvirt-python 的 C 扩展模块为例，其依赖的动态库数量多达 57 个：

test@M920t-N000:~/.pyenv/versions/3.10.14/lib/python3.10/site-packages$ ls -lr
...
-rw-rw-r--  1 test test    6759  9月 13 11:20 libvirt_qemu.py
drwxrwxr-x  2 test test    4096  9月 13 11:20 libvirt_python-10.7.0.dist-info
-rw-rw-r--  1 test test  373128  9月 13 11:20 libvirt.py
-rwxrwxr-x  1 test test   93352  9月 13 11:20 libvirtmod_qemu.cpython-310-x86_64-linux-gnu.so
-rwxrwxr-x  1 test test   81360  9月 13 11:20 libvirtmod_lxc.cpython-310-x86_64-linux-gnu.so
-rwxrwxr-x  1 test test 1041224  9月 13 11:20 libvirtmod.cpython-310-x86_64-linux-gnu.so
-rw-rw-r--  1 test test    1729  9月 13 11:20 libvirt_lxc.py
-rw-rw-r--  1 test test   16957  9月 13 11:20 libvirtaio.py
...
test@M920t-N000:~/.pyenv/versions/3.10.14/lib/python3.10/site-packages$ ldd libvirtmod.cpython-310-x86_64-linux-gnu.so | wc -l
57

动态库的依赖链复杂且紧密，任何库的版本不匹配都会导致问题。例如，以前尝试为某个功能升级库时，不得不更新 glibc 小版本，结果导致系统无法启动。考虑到潜在的工作量和风险，放弃升级国内某常用Linux发行版的 libvirt 动态库，转而寻找其他解决方案。

"嫁接"整个package

从系统本身出发，当前使用的国内某常用Linux发行版 1070 系统基于 Debian 10（Buster），系统版本信息如下：

$ cat /etc/debian_version
10.10

在 Debian Buster 的官网³中，发现了它有自己维护的 python3-libvirt 包。通过以下命令可以轻松安装

sudo apt install python3-libvirt

使用 apt install 方式来安装具有以下优势：安装的版本与系统中的 libvirt 保持一致，系统自动处理依赖关系，例如安装 libvirt 动态库 (libvirt.so) 和头文件 (libvirt-dev)；通过 apt 安装的包默认与系统中其他依赖保持一致，减少版本冲突的可能性；安装过程非常简单，不需要编译，二进制包直接可用，无需额外配置。

安装完成后，libvirt-python 被默认安装到系统自带的 Python 3.7.3 环境中。

问题转移

虽然 libvirt-python 在 Python 3.7.3 环境中可以被导入和调用，但我们实际需要在 Python 3.10 环境中调用 libvirt-python。此时，我尝试将系统中 Python 3.7.3 的 libvirt-python 包整体“嫁接”到 Python 3.10 的环境中，以解决此问题。

定位并复制系统中的 libvirt-python 包
首先列出系统中 libvirt-python 的文件内容：

$ ls -lr /usr/lib/python3/dist-packages/libvirt*
-rw-r--r-- 1 root root   3213 1月  24  2019 /usr/lib/python3/dist-packages/libvirt_qemu.py
-rw-r--r-- 1 root root    875 1月  24  2019 /usr/lib/python3/dist-packages/libvirt_python-5.0.0.egg-info
-rw-r--r-- 1 root root 331921 1月  24  2019 /usr/lib/python3/dist-packages/libvirt.py
-rw-r--r-- 1 root root  35000 1月  24  2019 /usr/lib/python3/dist-packages/libvirtmod_qemu.cpython-37m-x86_64-linux-gnu.so
-rw-r--r-- 1 root root  30808 1月  24  2019 /usr/lib/python3/dist-packages/libvirtmod_lxc.cpython-37m-x86_64-linux-gnu.so
-rw-r--r-- 1 root root 306936 1月  24  2019 /usr/lib/python3/dist-packages/libvirtmod.cpython-37m-x86_64-linux-gnu.so
-rw-r--r-- 1 root root   1738 1月  24  2019 /usr/lib/python3/dist-packages/libvirt_lxc.py
-rw-r--r-- 1 root root  15416 1月  24  2019 /usr/lib/python3/dist-packages/libvirtaio.py

然后将上述文件拷贝到 Python 3.10 的 site-packages 目录：

$ cp -r /usr/lib/python3/dist-packages/libvirt* /home/test/.local/lib/python3.10/site-packages/

重命名 .so 文件以匹配 Python 3.10
因为 .so 文件是为 Python 3.7 编译的，必须根据 Python 3.10 的命名规则进行重命名：

libvirtmod_qemu.cpython-310-x86_64-linux-gnu.so
libvirtmod_lxc.cpython-310-x86_64-linux-gnu.so
libvirtmod.cpython-310-x86_64-linux-gnu.so

测试 Python 3.10 环境
上述调整后，在 Python 3.10 环境中成功加载了 libvirt-python。

这种方法将 Python 3.7 的 libvirt-python 包嫁接到 Python 3.10 环境中，从而绕开了重编译和系统版本冲突的问题。

从调用分层的角度来看，新的方案是在更高一层来解决问题，反倒成为了最简单的解决方案。

小结

通过逐层分析 Python 应用运行环境中的问题，找到了一种简洁且实用的解决方案。libvirt-python 作为一个依赖多层环境的 C 扩展包，其可用性受限于 Python 包管理层、二进制动态库层以及系统底层的协调性。正是这种多层次的依赖关系，导致版本迁移过程中容易出现不匹配问题。

在本次实践中，“嫁接”方案展现了灵活性与高效性，通过直接迁移包的方式，成功让 Python 3.10 环境加载并正常使用 Python 3.7.3 环境中的 libvirt-python。

然而，仍需注意以下几点：

长期可行性：由于“嫁接”方法依赖特定的环境兼容性，可能无法适应未来系统更新或环境变更。
可扩展性与维护成本：如需进一步升级 Python 环境或 libvirt 版本，可能需要重新调整迁移过程。
备选方案评估：若“嫁接”方法失效，可以考虑直接调用 libvirt API，通过绕过 Python 扩展层来解决可用性问题，但这将带来更高的开发成本与复杂性。

所以，当前的“嫁接”方案仅作为快速实现 MVP 的过渡性解决方案。长期来看，为保证系统的稳定性和可维护性，还需要探索新的解决方案。

参考

libvirt-python

python3-libvirt

附录

Python 应用分层依赖的完整结构

如果读者需要了解更详细的分层依赖结构，可参考以下说明：

应用代码层的依赖

Python 包依赖：在应用代码中，通过 import 语句引入所需的 Python 包(例如 import os)，这是应用最直接的依赖。Python 包的依赖关系在应用的层次上定义，通常列在 requirements.txt 或 pyproject.toml 文件中。
包的嵌套依赖：应用直接依赖的包，通常会进一步依赖其他包。例如，scikit-learn 依赖于 numpy 和 scipy 等。这些嵌套依赖必须全部满足，应用才能正常运行。

Python环境的依赖

Python解释器：所有Python代码都依赖于Python解释器，解释器的版本和实现（如CPython、PyPy）影响应用兼容性。一些包（尤其是C扩展包）可能要求特定版本的Python才能正常运行。
pip和虚拟环境：pip作为Python包管理器，用于安装、管理Python包。Python虚拟环境（如venv或conda环境）帮助隔离项目之间的依赖，防止包版本冲突。在虚拟环境中安装依赖可以确保应用只使用当前环境中的包。

Python 包的二进制依赖

C扩展库：许多Python包（如numpy、PySide6）包含用C/C++编写的底层模块，这些模块在编译后生成二进制共享库（.so文件）。应用依赖的包会加载这些.so文件，比如PySide6.QtWidgets.so。
包的共享库依赖：如果某个Python包的.so文件依赖于其他共享库（例如Qt库libQt5Core.so），那么这些共享库也需要在系统上可用。共享库的路径和版本必须与Python包兼容，否则会出现链接错误（如Symbol not found）。

系统级库的依赖

共享库（.so）依赖关系：共享库的依赖链可以层层递进。例如，一个Python包的.so文件可能依赖于Qt库，而Qt库又依赖于低层次的库（如X11或OpenGL）。
GNU C Library (glibc)：几乎所有的Linux共享库最终都会依赖于glibc，这是Linux系统的标准C库，为应用提供底层系统调用和基本功能支持（如内存管理、线程、I/O操作等）。不同版本的glibc存在向后不兼容的情况，因此一些依赖特定版本glibc的.so文件在不同Linux发行版上可能无法兼容。

内核及硬件依赖

Linux内核：应用的最底层依赖是Linux内核，因为所有系统调用（例如内存分配、进程管理等）最终会通过内核执行。现代应用很少直接依赖特定的内核版本，但对于一些底层库（如驱动程序），需要确保内核与应用或库的依赖相符。
硬件支持：在需要硬件加速的场景（如GPU加速）中，系统还依赖于特定的硬件设备和相关驱动程序。这通常是通过内核模块或厂商提供的.so文件（如NVIDIA驱动）实现。