JumpServer 本地源码部署依赖编译排障实战macOS 下 cryptography、Pillow 与 xmlsec 的安装修复【免费下载链接】jumpserverJumpServer is an open-source Privileged Access Management (PAM) platform that provides DevOps and IT teams with on-demand and secure access to SSH, RDP, Kubernetes, Database and RemoteApp endpoints through a web browser.项目地址: https://gitcode.com/GitHub_Trending/ju/jumpserver在 macOS 上从源码方式安装 JumpServer 时pip install阶段最容易卡在三个强依赖上cryptographyOpenSSL 头文件缺失、Pillowlibjpeg/tiff 等图像库未安装与xmlseclibxmlsec1 公式不可用。本文以仓库中 requirements/issue.md 记录的排障笔记为主线结合pyproject.toml的依赖声明与 requirements/mac_pkg.sh 等配套安装脚本给出每一步可复现的修复命令并说明这些库在 JumpServer 代码中承担的实际职责帮你把环境问题一次排干净。背景为什么 macOS 上会踩到这些坑JumpServer 的依赖清单集中在项目根目录的 pyproject.toml其中三个包在 macOS 上属于需要本地编译的类型依赖锁定的版本当前仓库失败时的典型报错根本原因cryptography46.0.7fatal error: openssl/opensslv.h file not found编译期需要 OpenSSL 头文件macOS 系统不自带pillow12.3.0Pillow zlib failed依赖 zlib、libjpeg 等系统图像库xmlsec1.3.17libxmlsec 相关错误依赖 libxml2/libxmlsec1 及其 OpenSSL 绑定需要特别说明的是这些错误主要出现在使用系统自带 PythonApple 提供的 Python 2.7/3.x或未接入 Homebrew 环境的旧式pip install流程中。当前仓库要求requires-python 3.14见 pyproject.toml如果你通过 Homebrew 安装 Python 或使用 uv/poetry 管理虚拟环境依赖通常会以 wheel 形式直接命中跳过本地编译只有 wheel 源不可用或强制--no-binary编译时才会走到下面的排障路径。问题一cryptography 编译报 openssl/opensslv.h 找不到报错现场build/temp.macosx-10.13-intel-2.7/_openssl.c:483:10: fatal error: openssl/opensslv.h file not foundcryptography在 macOS 上编译其 C 扩展时需要从 OpenSSL 头文件中读取版本宏。如果系统里没有对应的 SDK 头文件比如只安装了 Homebrew 的openssl3但编译器找不到 include 路径就会在_openssl.c这一层直接 fatal error。修复命令issue.md 原版将 OpenSSL 的 include 与 lib 路径通过--global-option显式传给编译流程pip install cryptography \ --global-optionbuild_ext \ --global-option-L/opt/homebrew/Cellar/openssl3/3.1.1_1/lib \ --global-option-I/opt/homebrew/Cellar/openssl3/3.1.1_1/include注意三点/opt/homebrew是 Apple SiliconARM机器上 Homebrew 的默认前缀Intel 机器上通常是/usr/local/Cellar/...路径要按brew --prefix openssl3的实际输出调整openssl3/3.1.1_1是当时的具体版本目录Homebrew 升级后版本号会变化不要硬编码--global-option把参数透传给setup.py build_ext属于最后手段优先考虑让 pip 直接装到预编译 wheel。更稳的做法用 pkg-config 环境变量仓库配套脚本 requirements/mac_pkg.sh 对同类找不到头文件问题采用的是PKG_CONFIG_PATH方案——脚本里为mysqlclient/mariadb-connector-c导出路径后 pip 才能找到头文件与库。对 OpenSSL 可以照搬同一思路export PKG_CONFIG_PATH$(brew --prefix openssl3)/lib/pkgconfig:${PKG_CONFIG_PATH} export LDFLAGS-L$(brew --prefix openssl3)/lib export CFLAGS-I$(brew --prefix openssl3)/include pip install cryptography46.0.7这个库在 JumpServer 里做什么从源码看cryptography主要承担凭据加解密与签名类工作例如apps/common/utils/encode.py 通过cryptography.hazmat.primitives.serialization做密钥序列化/反序列化apps/common/utils/zip.py 在打包/解包过程中使用cryptography.hazmat.primitives.hashes与asymmetric.padding做哈希与 RSA 填充签名apps/authentication/api/connection_token.py、apps/authentication/backends/ukey/ukey 免密登录等认证链路同样直接 import 它。也就是说cryptography装不上JumpServer 的凭据加解密、UKey 认证和 zip 安全打包功能会整体不可用属于必须先修好的依赖。问题二Pillow 报 zlib failed报错现场Pillow zlib failedPillow 编译时若检测不到 zlibJPEG/PNG 支持所依赖的基础库就会以zlib failed之类的消息中止。issue.md 记录的修复方式是重新安装 Xcode Command Line Toolsxcode-select --installxcode-select --install会安装或修复clang、make、SDK 头文件等一套工具链。Pillow 的编译错误很多时候并不是 zlib 真的缺失而是 macOS SDK 头文件路径被破坏或未完全安装导致的连锁失败重装 Command Line Tools 即可恢复完整的编译环境。更完整的处理顺序先重装工具链xcode-select --install已安装时提示 command line tools are already installed 属于正常再安装图像库依赖——参照 requirements/mac_pkg.sh 里的 Homebrew 依赖清单其中与本问题直接相关的是libtiff libjpeg webp little-cms2brew install libtiff libjpeg webp little-cms2最后重装 Pillowpip install --force-reinstall pillow12.3.0这个库在 JumpServer 里做什么pillow在 JumpServer 中服务于图片验证码、头像等图形资源的处理前端模板中的django-simple-captcha见 pyproject.toml渲染验证码图片时依赖 Pillow 的图像能力。装不上 Pillow登录页的图片验证码将无法生成登录流程会被直接卡住。问题三libxmlsec 报错报错现场与原因xmlsecPython 绑定库版本 1.3.17见 pyproject.toml用于 XML 数字签名与加密。它编译时依赖 libxml2 与 libxmlsec1而 libxmlsec1 又依赖 OpenSSL 的 libcrypto 做签名运算。在 macOS 上Homebrew 的libxmlsec1公式曾出现过 unavailable/版本不兼容的情况导致编译失败。修复命令issue.md 原版从 Homebrew 仓库拉取指定 commit 的历史 Formula 文件离线方式安装 libxmlsec1wget https://raw.githubusercontent.com/Homebrew/homebrew-core/7f35e6ede954326a10949891af2dba47bbe1fc17/Formula/libxmlsec1.rb brew install ./libxmlsec1.rb7f35e6ed...是该 Formula 在 homebrew-core 仓库中某个可用状态的 commit 哈希。如果当前 Homebrew 的libxmlsec1公式已修复直接brew install libxmlsec1即可无需此绕行方案。为什么需要它SAML2 单点登录的签名基础在 JumpServer 中xmlsec服务于SAML2 认证。项目内置的 SAML2 后端位于 apps/authentication/backends/saml2/依赖python3-saml1.16.0见 pyproject.toml而python3-saml底层正是通过xmlsec完成对 SAML 断言Assertion的签名校验与加密。也就是说若xmlsec装不上JumpServer 的 SAML2 单点登录功能将无法工作。配套脚本一份完整的 macOS 依赖安装清单requirements/mac_pkg.sh 给出了 JumpServer 在 macOS 上的官方依赖安装脚本本文三个问题的依赖都能在脚本第 6-9 行找到brew install libtiff libjpeg webp little-cms2 openssl gettext git \ git-lfs libxml2 libxmlsec1 pkg-config postgresql freetds openssl \ mysql-client mariadb-connector-c \ libffi freerdp poppler关键点解读libtiff libjpeg webp little-cms2Pillow 编译所依赖的图像库对应问题二openssl脚本中出现了两次为cryptography、xmlsec等 C 扩展提供头文件与库对应问题一与问题三libxml2 libxmlsec1xmlsec编译的底层库对应问题三mysql-client mariadb-connector-cPKG_CONFIG_PATH/CFLAGS/LDFLAGS环境变量为mysqlclient2.2.4见 pyproject.toml提供 MariaDB 客户端头文件与pkg-config查找机制一致freetds为pymssql2.3.10见 pyproject.toml提供 SQL Server 连接支持脚本第 21-27 行还针对 Apple 处理器ARM64追加了pymssql的特殊编译参数LDFLAGS-L$(brew --prefix freetds)/lib -L$(brew --prefix openssl1.1)/lib \ CFLAGS-I$(brew --prefix freetds)/include \ pip install $(grep pymssql requirements.txt)其他平台的对照参考仓库还提供了 Linux 各发行版的系统依赖脚本供对照理解编译期需要哪些系统库Alpineapkrequirements/apk_pkg.sh 安装libffi-dev libressl-dev libxslt-dev libxml2-dev xmlsec-dev freerdp-dev等Debian/Ubuntuaptrequirements/deb_pkg.sh 安装libffi-dev libldap2-dev libsasl2-dev libxml2-dev libxmlsec1-dev libxmlsec1-openssl freetds-dev freerdp2-devCentOS/RHELyumrequirements/rpm_pkg.sh 安装xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel postgresql-devel freerdp-devel。可以看到无论哪个平台openssl、libxml2/libxmlsec1、freerdp都是固定的系统级依赖问题一与问题三的根源在跨平台层面是一致的。最小化排障路径总结把 issue.md 的三条记录整合成一份可执行的检查顺序先补工具链xcode-select --install解决 Pillow 等一切编译环境不完整的隐性失败再装 Homebrew 依赖对照 requirements/mac_pkg.sh 安装libtiff libjpeg webp little-cms2 openssl libxml2 libxmlsec1 pkg-config等一条命令补齐全部编译期依赖按需重装失败项cryptography报 OpenSSL 头文件缺失时用PKG_CONFIG_PATH/CFLAGS/LDFLAGS指向brew --prefix openssl3或使用 issue.md 的--global-option显式传路径Pillow报 zlib failed 时先重装 Command Line Tools 再pip install --force-reinstall pillow12.3.0xmlsec报 libxmlsec 错误时优先brew install libxmlsec1公式不可用时回退到 issue.md 记录的指定 commit 离线安装法验证python -c import cryptography, PIL, xmlsec无报错即说明三个核心 C 扩展均已就绪可以继续后续的依赖安装与manage.py初始化流程。结论cryptography、Pillow与xmlsec是 JumpServer 源码部署中编译期最脆弱的三个环节分别对应凭据加解密与 UKey 认证、图片验证码渲染、SAML2 单点登录签名这三类核心能力。issue.md 的三条记录虽然简短但每一条都指向 macOS 上系统级依赖缺失/损坏这一共同根因结合仓库的 pyproject.toml 版本声明与 requirements/mac_pkg.sh 安装脚本就能形成一套从工具链、系统库到 Python 包的三层排障方法让 JumpServer 的本地开发环境一次到位。【免费下载链接】jumpserverJumpServer is an open-source Privileged Access Management (PAM) platform that provides DevOps and IT teams with on-demand and secure access to SSH, RDP, Kubernetes, Database and RemoteApp endpoints through a web browser.项目地址: https://gitcode.com/GitHub_Trending/ju/jumpserver创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考