Создание и использование wheelhouse для офлайн-установки Python
Wheelhouse - это директория с предварительно собранными wheel-файлами, создаваемая на машине с доступом к сети и устанавливаемая офлайн на целевой машине. Процесс включает закрепление версий в requirements-файле, запуск pip wheel, архивацию через tar и установку с флагами --no-index --no-deps --force-reinstall.
В этом материале
Короткий ответ
Wheelhouse представляет собой директорию с предварительно собранными wheel-файлами, которую вы создаете на машине с доступом к сети, а затем переносите на изолированную целевую машину. Машина для сборки считывает закрепленный файл требований, запускает pip wheel с параметром --wheel-dir для компиляции каждой зависимости и упаковывает директорию с помощью tar. На целевой машине вы извлекаете архив и запускаете pip install с флагами --no-index --no-deps --force-reinstall, чтобы pip никогда не обращался к PyPI и устанавливал только входящие в комплект wheel-файлы. Проверка хешей может быть добавлена путем включения записей --hash в файл требований, что позволяет проверить целостность пакетов на этапе сборки. Этот метод подходит, когда целевая машина не имеет сетевого доступа, вы хотите избежать повторной компиляции на целевой машине и можете контролировать ОС и архитектуру. Это не является заменой частному индексу, поскольку архив представляет собой статический снимок, обычно специфичен для конкретной ОС и архитектуры и не обеспечивает постоянную доступность или контроль доступа.
Сборка wheelhouse с помощью pip wheel
Основной рабочий процесс начинается с закрепленного файла требований. Выполните команду python -m pip wheel -r requirements.txt --wheel-dir=/tmp/wheelhouse, чтобы скомпилировать каждую зависимость в wheel-файл и сохранить его в директории wheelhouse. Машина для сборки выполняет компиляцию, поэтому целевой машине не потребуются компилятор или инструменты сборки. После завершения команды директория wheelhouse будет содержать по одному wheel-файлу для каждого пакета, включая транзитивные зависимости. Следующим шагом является архивация этой директории для последующей передачи. В современной системе Unix выполните tar -cjvf wheelhouse.tar.bz2 -C /tmp/wheelhouse ., чтобы создать один сжатый архив. Именно этот архив вы передаете в изолированную среду. Файл требований служит входными данными для этого этапа, поэтому он должен быть точным и полным перед началом сборки.
mkdir -p /tmp/wheelhouse && python -m pip wheel -r requirements.txt --wheel-dir=/tmp/wheelhouse && tar -cjvf wheelhouse.tar.bz2 -C /tmp/wheelhouse .Практический совет
Сгенерируйте файл требований с помощью pip freeze на машине для сборки, затем убедитесь, что закрепленный файл содержит каждую транзитивную зависимость перед запуском pip wheel. Это предотвратит возникновение ошибок при офлайн-установке из-за отсутствующих пакетов.
Установка из wheelhouse без доступа к сети
На целевой машине извлеките архив во временную директорию, затем запустите pip install с тремя важными флагами. --no-index указывает pip не обращаться к любому индексу пакетов, чтобы он не мог вернуться к PyPI. --no-deps предотвращает разрешение или установку зависимостей вне комплекта, что безопасно, так как файл требований уже содержит все пакеты. --force-reinstall гарантирует установку входящих в комплект wheel-файлов, даже если соответствующая версия уже присутствует. Команда python -m pip install --force-reinstall --no-index --no-deps /tmp/wheelhouse/* устанавливает все wheel-файлы из извлеченной директории. Эта последовательность действий обеспечивает истинную офлайн-установку, так как на этапе установки не создается никаких сетевых запросов. Файл требований должен содержать все транзитивные зависимости, иначе флаг --no-deps оставит среду неполной.
tar -xvf wheelhouse.tar.bz2 -C /tmp/wheelhouse && python -m pip install --force-reinstall --no-index --no-deps /tmp/wheelhouse/*Подготовка закрепленного файла требований
Wheelhouse собирается на основе файла требований с точно указанными версиями. Вы можете сгенерировать этот файл с помощью pip freeze, который фиксирует пакеты, установленные в текущей среде, включая транзитивные зависимости, а не только пакеты верхнего уровня. Каждая строка использует оператор == для указания конкретной версии, например SomePackage == 1.2.3. Закрепление версий защищает вас от ошибок или несовместимостей в новых версиях, так как pip не будет обновлять ничего в процессе сборки или установки. Файл требований является входным параметром для этапа сборки wheel-файлов, поэтому он должен быть полным и точным до запуска pip wheel. Если в файле отсутствует транзитивная зависимость, офлайн-установка завершится ошибкой, так как --no-deps запрещает pip загружать ее из индекса. Проверьте сгенерированный файл, чтобы убедиться, что он включает все транзитивные зависимости перед запуском pip wheel.
Архивация wheelhouse для передачи
Как только директория с wheel-файлами будет заполнена, преобразуйте ее в единый переносимый архив с помощью tar. Команда tar -cjvf wheelhouse.tar.bz2 -C /tmp/wheelhouse . создает сжатый tar-архив, содержащий все wheel-файлы. Именно этот архив переносится в изолированную среду. Архив является статическим снимком состояния машины для сборки, поэтому он сохраняет точно скомпилированные пакеты и их версии. Он не включает скрипты сборки или исходный код, только готовые к установке wheel-файлы. Архив должен быть передан на целевую машину до начала установки. Поскольку архив представляет собой один файл, его легко перемещать между машинами, но он не переносим между разными операционными системами или архитектурами процессора.
Добавление проверки хешей в рабочий процесс wheelhouse
Проверка хешей может быть объединена с методом wheelhouse, так как оба используют файл требований. Вы добавляете записи --hash в файл требований, например FooProject == 1.2 --hash=sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824. Эти хеши проверяются, когда pip wheel загружает пакеты, что защищает от компрометации исходного индекса или цепочки сертификатов HTTPS. Это также защищает от случаев, когда пакет изменяется без изменения номера версии в индексах, которые это позволяют. Это слой целостности поверх офлайн-комплекта. Хеши должны быть действительными и соответствовать пакетам в архиве. Если хеши не совпадают, pip откажется использовать пакет, что защищает сборку от незаметных изменений. Режим проверки хешей - это слой целостности, а не упрощенная альтернатива запуску сервера частного индекса, так как он не обеспечивает преимуществ доступности, которые дает частный индекс или вендорированная библиотека.
Объявление зависимостей сборки в pyproject.toml
Таблица [build-system] в файле pyproject.toml объявляет зависимости на уровне Python, которые должны быть установлены для работы системы сборки проекта. Ключ requires перечисляет эти зависимости, например requires = [setuptools]. Эти требования на время сборки влияют на то, что компилирует pip wheel, так как бэкенду сборки они необходимы для создания wheel-файла. Понимание этой таблицы помогает гарантировать, что wheelhouse захватывает все необходимые зависимости инструментов сборки для успешной компиляции на машине для сборки. Если системе сборки требуются дополнительные пакеты, они должны быть перечислены в requires, чтобы машина для сборки могла установить их перед запуском pip wheel. При отсутствии файла pyproject.toml применяются семантики по умолчанию, но явная таблица делает требования к сборке понятными и воспроизводимыми.
Ограничения переносимости и случаи, когда wheelhouse недостаточно
Wheelhouse содержит скомпилированные пакеты, которые обычно специфичны для конкретной ОС и архитектуры, поэтому архивы не обязательно переносимы между разными машинами. Один и тот же wheel-файл не будет работать на другой операционной системе или архитектуре процессора без перекомпиляции. Этот метод также требует наличия машины для сборки с доступом к сети; он не поможет, если ни одна машина не может связаться с PyPI. Wheelhouse не заменяет частный индекс, когда вам нужна кроссплатформенная поддержка или живой журнал аудита, выходящий за рамки статического архива. Проверка хешей сама по себе обеспечивает целостность, но не доступность, а wheelhouse обеспечивает доступность только для тех пакетов и платформ, которые в него включены. Если вам нужно поддерживать несколько платформ, вы должны создать отдельные wheelhouse для каждой целевой среды. Архив - это снимок, а не сервис, поэтому он не может обеспечить постоянную доступность или контроль доступа.
Когда wheelhouse является подходящим инструментом
Wheelhouse - подходящий инструмент, когда целевая среда не имеет сетевого доступа к PyPI, вы хотите избежать трудоемкой перекомпиляции на целевой машине и можете контролировать ОС и архитектуру. Он упаковывает всю работу по компиляции в один архив, что отличается от простого закрепления версий или использования только проверки хешей. Закрепление версий защищает от ошибок в новых версиях, а проверка хешей добавляет целостность, но ни одно из этих средств не обеспечивает доступности или удобства офлайн-установки, которые дает wheelhouse. Wheelhouse - это набор предварительно собранных wheel-файлов, которые целевая машина устанавливает без обращения к любому индексу. Этот подход работает между разными ОС и архитектурами только в том случае, если машина для сборки и целевая машина используют одну и ту же платформу. Это практичное решение для изолированных развертываний, где сетевой доступ недоступен или ограничен.
Что проверить
- Файл требований должен закреплять каждый пакет с помощью == и включать транзитивные зависимости, а не только пакеты верхнего уровня.
- Машина для сборки должна иметь сетевой доступ для загрузки и компиляции всех зависимостей перед архивацией.
- Целевая машина должна использовать ту же ОС и архитектуру ЦП, что и машина для сборки, чтобы wheel-файлы были совместимы.
- Команда установки должна включать --no-index, --no-deps и --force-reinstall для предотвращения сетевого доступа и внешнего разрешения зависимостей.
- Архив должен быть создан из директории wheel с помощью tar перед передачей и извлечен перед установкой.
- Записи проверки хешей в файле требований должны быть действительными и соответствовать пакетам в архиве.
- Wheelhouse содержит скомпилированные пакеты и не переносим между разными операционными системами или архитектурами.
- Wheelhouse не заменяет частный индекс для обеспечения постоянной доступности, контроля доступа или управления аудитом.
Границы применения
Wheelhouse содержит скомпилированные пакеты, которые обычно специфичны для конкретной ОС и архитектуры, поэтому архивы не обязательно переносимы между машинами. Подход требует наличия машины для сборки с сетевым доступом; он не поможет, если ни одна машина не может связаться с PyPI. Скомпилированные wheel-файлы могут содержать платформозависимый бинарный код, поэтому кросс-компиляция не поддерживается только этим методом. Архив является статическим снимком и не обеспечивает постоянную доступность или управление ACL, как сервер частного индекса. Использование --no-deps означает, что оператор должен убедиться, что файл требований уже перечисляет каждую транзитивную зависимость.