Play
online · 30 мин
Туториалы 16 мин чтения 11.05.2026

Как зафиксировать системные RPM/DNF-зависимости Bitrix-проекта: дескриптор для миграции на новый Linux-сервер

После переезда на новый сервер модули Bitrix падают не из-за кода, а из-за отсутствующих системных пакетов. Рассказываем, как зафиксировать RPM/DNF/YUM-зависимости проекта в едином файле, чтобы CI разворачивал окружение одной командой.
TL;DR
Миграция Bitrix на новый сервер ломает модули из-за отсутствия системных библиотек. Ручное выявление зависимостей — долгий процесс; нужен единый файл-дескриптор. Файл bitrix-deps.list содержит список RPM-пакетов, устанавливаемых одной командой DNF. Список собирается через анализ логов ошибок, проверку PHP-модулей и rpm -qa на старом сервере. Интеграция в CI/CD позволяет автоматически проверять актуальность зависимостей при деплое.

Главные выводы за 30 секунд: что мы фиксируем и зачем

После переезда на новый сервер модули Bitrix падают не из-за кода, а из-за отсутствующих системных пакетов.

Предлагаем не тушить пожары по одному, а держать единый дескриптор зависимостей в репозитории — файл вида system-requirements.yml или bitrix-deps.list, который CI читает при подготовке инфраструктуры. Тогда dnf install -y $(cat bitrix-deps.list) прогоняется одним шагом, и новая машина получает весь набор сразу.

Ниже разберём, где этот список хранить, как его собрать и как связать с пайплайном.

  • Где хранить список обязательных RPM/DNF-пакетов проекта — в корне репо рядом с конфигами, а не в вики.
  • Как быстро собрать чеклист зависимостей для Bitrix-ядра и проектных доработок через dnf provides и ldd.
  • Как связать дескриптор с CI/CD и Ansible, чтобы установка шла до старта приложения.

Почему после миграции Bitrix-проекта отваливаются модули: разбор причин

Типичный сценарий: проект переехал на свежий Rocky или AlmaLinux, сайт открывается, админка работает, а через пару дней посыпались жалобы — то картинки в каталоге не режутся, то XML-выгрузка падает с фаталом. Первая гипотеза у заказчика всегда одна: «код сломался, вы что-то намудрили при переносе». Мы садимся разбирать — и в большинстве случаев код тут вообще ни при чём.

Причина в среде. На старом сервере годами накапливались пакеты, которые никто не фиксировал: их доставляли руками под конкретную задачу, они тянули за собой зависимости, обновлялись вместе с системой. На новой машине стоит чистый минимальный набор — и всё, что проект неявно использовал, просто исчезло. Модуль Bitrix не падает сам по себе — он падает, когда дёргает функцию расширения, которого на сервере нет. Механизм мы разбирали в выводах выше, а здесь посмотрим, как это проявляется и на что смотреть первым делом.

Симптом в Bitrix Чего не хватает Какой пакет обычно закрывает
Не работает ресайз изображений GD с поддержкой JPEG php-gd / libjpeg-turbo-devel
Падает парсинг XML-выгрузок XML-расширения PHP php-xml / libxml2
TLS-ошибки в curl-запросах Свежие curl и корневые сертификаты curl / openssl / ca-certificates
Проблемы с ZIP-архивами ZIP-расширение PHP php-zip / libzip
Ошибки функций mb_* Мультибайтовые строки php-mbstring / oniguruma

Почему это не вскрывается сразу? Часть модулей грузится лениво, часть — только при обращении к конкретному функционалу. «Сервер поднялся, сайт открылся» не значит, что всё в порядке — это значит лишь, что ядро нашло минимально необходимое.

Ядро Bitrix подгружает модули по мере вызова их API: пока страница не запросила CFile::ResizeImageGet, модуль работы с изображениями может не дёрнуть GD. С обменом та же история: XML-парсер подключается в момент старта выгрузки, а не при рендере главной. Поэтому дефект среды проявляется ровно тогда, когда пользователь нажимает «загрузить картинку» или запускается ночной агент импорта.

Есть и второй слой — версии. Даже если пакет установлен, он может быть собран без нужного флага. Классика: openssl на новом дистрибутиве отключил устаревшие TLS-цифры, и интеграция с внешним API, которая работала годами, внезапно отваливается с ошибкой рукопожатия. Или libjpeg-turbo собран без поддержки определённого формата — ресайз «работает», но выдаёт битые превью. Поэтому в дескриптор зависимостей мы закладываем не только имена пакетов, но и минимальные версии там, где это критично.

Отдельно стоит помнить про расширения, которые ставятся не из системного репозитория, а через pecl или собираются под конкретную версию PHP. Их dnf install не подтянет — про них в дескрипторе нужна отдельная пометка, иначе перенос на чистую машину снова упрётся в «а этого у нас нет».

Где хранить список обязательных RPM/DNF-пакетов проекта

Распространённая ошибка — держать список системных зависимостей «в голове» или в переписке в чате. Пока сервер один, это терпимо. Как только появляется второй стенд, CI-раннер или реплика, выясняется, что никто не помнит, какой именно пакет доставили полгода назад, чтобы заработал парсер XML. У нас в практике это всплывает ровно на этапе переезда: проект переносится, а восстановить историю доустановок нечем.

Мы разбираем три рабочих варианта хранения такого списка: плоский .list-файл, YAML-дескриптор и Ansible-роль с переменными. У каждого своя ниша, и выбор зависит не от моды, а от того, кто и как будет читать этот список — только ли человек, CI-пайплайн или ещё и Ansible-плейбук.

Ниже — сравнение, пример дескриптора и наши соображения, почему в студии по умолчанию берём YAML.

Формат Где лежит Кто читает Плюсы Минусы
bitrix-deps.list корень репо bash / CI просто, ставится одной строкой нет метаданных и ролей
system-requirements.yml deploy/ CI + Ansible + человек документирует reason, диффится чуть сложнее парсить
vars/main.yml roles/bitrix-base/ только Ansible переиспользуется между проектами требует Ansible даже для локальной установки

Минимальный YAML-дескриптор, который мы кладём в deploy/system-requirements.yml, выглядит так:

YAML
# deploy/system-requirements.yml
# Список обязательных RPM-пакетов проекта Bitrix.
# Читается CI при подготовке сервера и Ansible-плейбуком base-setup.
packages:
  - name: php-gd
    reason: "обработка изображений, ресайз в компонентах каталога"
    roles: [web]

  - name: php-xml
    reason: "парсинг XML в обмене с 1С и импорте прайсов"
    roles: [web, worker]

  - name: libcurl
    reason: "curl-расширения для TLS-обмена с внешними API"
    roles: [web, worker]

  - name: openssl
    reason: "современные TLS-цифры для HTTPS-запросов"
    roles: [web, db, worker]

Ключевое здесь — поле reason. Оно превращает безликий список пакетов в документ: через полгода новый инженер прочитает «php-xml — парсинг XML в обмене с 1С» и поймёт, почему пакет нельзя просто выкинуть. Поле roles позволяет ставить на веб-ноду, БД и воркер только нужное подмножество, а не всё подряд. Под свой проект вы поменяете имена пакетов и роли — структура остаётся той же.

Почему мы по умолчанию берём YAML, а не плоский список: он одновременно машиночитаемый и человекочитаемый. Из одного файла одной строкой генерируется и bash-команда для быстрой установки, и Ansible-таск, и таблица в документации. В merge request видно диффом, какой пакет добавили и зачем — а не безликое «+ php-xml» в конце списка. Плоский .list такого контекста не даёт: через месяц никто не вспомнит, зачем там тот или иной пакет.

Ещё аргумент — единый источник правды. Когда список один, CI и локальная установка на dev-машине читают его же. Не бывает ситуации «на проде пакет есть, а в пайплайне забыли». Ansible-роль читает тот же YAML в своих переменных, поэтому расхождений между ручной установкой и автоматической не возникает.

Когда хватит плоского .list-файла

Если проект небольшой, сервер один, а деплой — это dnf install -y $(cat bitrix-deps.list) вручную по SSH, заводить YAML смысла нет. Плоский список из 5-10 строк проще читать глазами и не требует парсера. В такой конфигурации reason можно держать комментарием прямо в файле — # php-xml — обмен с 1С.

Мы советуем оставаться на .list, пока у вас один стенд и нет CI. Как только появляется второй сервер или пайплайн, который сам готовит окружение, метаданные начинают окупаться: роли, причины, валидация структуры. Переход с .list на YAML — это полчаса работы, так что застрять в плоском формате не страшно.

Когда уходить в полноценную Ansible-роль

Ansible-роль оправдана, когда зависимостей много и они переиспользуются между проектами. Если у вас десять сайтов на одном стеке и общий набор пакетов, выносить их в roles/bitrix-base/vars/main.yml логично: один раз описали — подключаете роль в каждом плейбуке.

Минус в том, что роль требует Ansible даже для локальной установки на dev-машине. Разработчику, который просто хочет поднять окружение, придётся ставить Ansible, чтобы прогнать один таск. Поэтому в студии мы держим YAML-дескриптор как источник правды, а Ansible-роль читает из него переменные — так и переиспользование есть, и локальная установка остаётся одной строкой bash.

Как быстро собрать чеклист зависимостей для Bitrix-ядра и проектных доработок

Задача звучит так: получить полный список системных пакетов, которые нужны проекту, и не перебирать их по одному методом тыка, устанавливая пакет только после того, как очередной модуль упал. Ручной перебор плох тем, что растягивается на дни, а часть зависимостей всплывает не сразу: например, curl и openssl с определёнными расширениями нужны только тогда, когда кто-то дёрнет определённую TLS-цифру, а до этого момента всё выглядит рабочим. Поэтому мы в проектах идём от обратного: не собираем пакеты по документации, а снимаем фактический baseline с работающего сервера и вычитаем из него то, что приезжает с любой базовой установкой ОС. Остаток и есть кандидат в дескриптор.

Приём простой и работает на любом RHEL-семействе: Rocky, AlmaLinux, RHEL. Всё, что вы делаете, это два списка и одно вычитание. Дальше разберём по шагам, а в конце покажем скрипт, который делает это одной командой.

  1. На работающем сервере снять полный список установленных пакетов через rpm -qa и сохранить в файл: rpm -qa | sort > /tmp/all-packages.txt.
  2. Вычесть пакеты, которые входят в группы @core и @standard — они приедут с любой базовой установкой Rocky или AlmaLinux и в дескрипторе не нужны, иначе список распухнет до сотен строк, которые ничего не значат.
  3. Сопоставить оставшиеся пакеты с расширениями PHP через php -m и с бинарниками через ldd — понять, что реально требуется проекту, а что тянется транзитивно или осталось от чьих-то экспериментов.
  4. Проверить каждый пакет на чистом контейнере: если без него модуль падает — он идёт в дескриптор, если нет — выкидываем. Это не формальность, а обязательный фильтр.
SHELL
#!/bin/bash
# Собираем baseline зависимостей с работающего сервера.
# Запускать НА рабочем сервере, где проект уже живёт и всё работает.

set -euo pipefail

ALL_PKGS=/tmp/all-packages.txt
BASE_PKGS=/tmp/base-packages.txt
CANDIDATES=/tmp/bitrix-deps.candidates

# 1. Полный список установленного
rpm -qa --qf '%{NAME}\n' | sort -u > "$ALL_PKGS"

# 2. Пакеты базовых групп @core и @standard — они есть на любой свежей ОС
#    dnf group info показывает состав группы; берём имена пакетов из неё
{
    dnf group info core      2>/dev/null | sed -n '/Mandatory Packages:/,/Default Packages:/p'
    dnf group info standard  2>/dev/null | sed -n '/Mandatory Packages:/,/Default Packages:/p'
} | grep -E '^ *[a-z0-9._+-]+$' | awk '{print $1}' | sort -u > "$BASE_PKGS"

# 3. Разница: то, что стоит на сервере, но не входит в базовую установку
comm -23 "$ALL_PKGS" "$BASE_PKGS" > "$CANDIDATES"

echo "Всего пакетов:        $(wc -l < "$ALL_PKGS")"
echo "Базовых (core+std):   $(wc -l < "$BASE_PKGS")"
echo "Кандидатов в дескриптор: $(wc -l < "$CANDIDATES")"
echo "Список кандидатов: $CANDIDATES"

Как читать результат. Не все пакеты из разницы нужны именно Bitrix. Часть могла остаться от ручных экспериментов администратора: кто-то поставил tcpdump для отладки сетевых запросов к внешнему API и забыл удалить, кто-то ставил vim-enhanced или htop и они спокойно попали в список. Поэтому шаг с проверкой на чистом контейнере обязательный, а не опциональный.

Мы обычно берём голый образ Rocky или AlmaLinux, прогоняем по нему кандидатов по одному и смотрим, что реально ломается при отсутствии пакета: валится ли загрузка модуля, отваливается ли обработка картинок, падает ли парсинг XML.

Ещё один момент — транзитивные зависимости. Если проекту нужен libcurl , dnf сам подтянет его зависимости, и в дескрипторе достаточно указать верхнеуровневый пакет.

Не копируйте список с прода как есть. На боевом сервере почти всегда есть пакеты, которые ставили для отладки и забыли удалить, — утилиты для диагностики сети, редакторы, временные библиотеки под разовый разбор инцидента. Дескриптор должен содержать только то, без чего проект не работает: иначе вы протащите мусор на все будущие серверы и усложните себе аудит.

Как связать дескриптор с CI/CD и Ansible при подготовке сервера

Самый аккуратный дескриптор бесполезен, если его никто не читает: файл лежит в репозитории, а пакеты на сервер ставят руками по памяти. У нас в практике дескриптор начинает работать только тогда, когда к нему подключены две точки входа — быстрая ручная и регулярная автоматическая. Первая нужна, когда инженер поднимает машину разово и хочет одной командой закрыть все зависимости. Вторая — когда сервер готовит CI/CD или Ansible и список пакетов должен читаться из того же файла, что и в ручном сценарии.

Разделять эти сценарии не стоит: если ручная установка идёт по одному списку, а провижининг — по другому, они разъедутся. Поэтому system-requirements.yml держим единственным источником правды, а обе точки входа — bash-однострочник и Ansible-таск — читают именно его. Ниже показываем обе.

Однострочник для ручной установки на новой машине

Когда машина одна и надо быстро доставить пакеты, удобнее всего вытащить имена из YAML и сразу прогнать установку. Если в дескрипторе пакеты лежат плоским списком под ключом packages, хватает yq:

SHELL
# system-requirements.yml -> плоский список имён пакетов
sudo dnf install -y $(yq -r '.packages[]' system-requirements.yml)

Если yq под рукой нет, а структура простая, тот же результат даёт grep по строкам списка:

SHELL
# вытаскиваем имена из строк вида "  - libxml2-devel"
sudo dnf install -y $(grep -E '^\s*-\s' system-requirements.yml | sed 's/^\s*-\s*//')

Подходит для разового подъёма или отладки на чистой виртуалке. Для регулярного провижининга этот же список должен читать Ansible — иначе смысл дескриптора теряется.

Ansible-таск, который читает тот же дескриптор

В роли провижининга дескриптор подключаем через include_vars, а установку делаем модулем dnf с loop по пакетам. Фильтр по роли сервера (web, worker, db) позволяет ставить только то, что нужно конкретной машине: например, libxml2-devel нужен воркеру парсинга, но не балансировщику.

YAML
- name: Загрузить дескриптор системных зависимостей
  include_vars:
    file: system-requirements.yml
    name: sys_req

- name: Установить пакеты, отфильтрованные по роли сервера
  dnf:
    name: "{{ item }}"
    state: present
  loop: >-
    {{ sys_req.packages
       | selectattr('roles', 'contains', server_role)
       | map(attribute='name') | list }}
  when: sys_req.packages | length > 0

Здесь server_role — переменная инвентаря (web, worker, db). Если дескриптор плоский и ролей не предполагает, selectattr убираем и просто итерируемся по sys_req.packages. Тот же таск переиспользуется и в CI на этапе сборки образа, и при ручном прогоне плейбука.

  • Держать дескриптор в том же репозитории, что и проект, — рядом с кодом, а не в отдельном репо инфраструктуры.
  • Обновлять дескриптор в том же MR, что и код, который требует новый пакет: иначе зависимость всплывёт только на проде.
  • Прогонять установку в CI на чистом контейнере перед мержем — это ловит опечатки в именах пакетов до выката.

Как проверить дескриптор на чистой машине до переезда прода

Многие думают, что дескриптор зависимостей — это просто файл в репозитории, который лежит «на всякий случай». его главная ценность в другом: он даёт возможность проверить установку заранее, до того как прод переедет на новый сервер. У нас в команде правило простое: если дескриптор нельзя прогнать на чистой машине, значит он неполный. И узнаем мы об этом в самый неподходящий момент.

Поэтому перед каждым переездом разворачиваем чистый контейнер с тем же базовым образом, что и целевой сервер, и прогоняем по нему весь сценарий: установку пакетов из дескриптора, настройку PHP и короткий smoke-тест на живой функциональности проекта. Пара минут вместо трёх часов ночной отладки. Если в проекте уже настроен CI (как мы разбирали в предыдущей секции), этот шаг встраивается в пайплайн и запускается на каждый коммит в дескриптор.

SHELL
# Чистый контейнер с тем же базовым образом, что и целевой сервер
docker run --rm -it rockylinux:9 bash -c '
set -euo pipefail

# 1. Ставим пакеты строго из дескриптора проекта
dnf install -y $(grep -vE "^\s*#" system-requirements.list) \
&& dnf clean all

# 2. Ставим PHP и нужные расширения (версия — под проект)
dnf install -y php-cli php-mbstring php-xml php-gd php-openssl php-curl

# 3. Гоняем smoke-тест — он же и валидирует дескриптор
bash ci/smoke-test.sh
'

Сам smoke-тест — это минимальный набор проверок, который ловит именно те классы проблем, из-за которых модули падают на проде:

  • php -m — убедиться, что все нужные расширения (gd, xml, openssl, curl) реально подгрузились, а не просто установлены.
  • Тестовый ресайз картинки через CFile::ResizeImageGet() — ловит отсутствие libjpeg или libpng.
  • Парсинг тестового XML через simplexml_load_string() — ловит нехватку libxml2 и расширения xml.
  • TLS-запрос через curl к целевому хосту (например, к API платёжной системы) — ловит устаревшие или отсутствующие openssl-цифры.

Почему контейнер, а не виртуалка: старт за секунды против минут, отдельный хост не нужен, один и тот же образ даёт один и тот же результат и локально, и в CI. Мы гоняем такой прогон на каждый коммит в дескриптор, и это отлавливает забытый пакет до того, как он станет инцидентом.

Есть случаи, когда контейнер не подходит: если проект завязан на systemd-юниты, специфику ядра или модули, которые требуют привилегированного доступа. Тогда берём VM, но принцип тот же: всё автоматизируем, никаких ручных проверок «на глазок». Ansible-playbook на чистой VM справляется не хуже, просто занимает больше времени. И вот что важно: не проверяйте дескриптор на той же машине, где он уже частично применён. Там половина пакетов стоит по историческим причинам, и тест покажет ложный успех.

Самые частые ошибки при описании системных зависимостей

Разбирая чужие дескрипторы и переписывая свои, мы собрали набор граблей, на которые наступают чаще всего при попытке зафиксировать системные зависимости проекта. Каждая не теоретическая — за ней стоит либо ночной разбор упавшего прода, либо несколько часов ручного тыка на чистой машине. Общий знаменатель один: дескриптор формально есть, но реальность он не отражает. При переносе на новый сервер это вылезает боком.

Ниже пять ошибок, которые мы встречаем регулярно. По каждой — к чему она приводит на практике и как её закрыть в самом дескрипторе, чтобы больше не возвращаться. Если вы уже прошли секции выше и собрали черновик списка, пробегитесь по таблице и проверьте свой файл на каждую строку.

Ошибка К чему приводит Как исправить
Пинить точные версии пакетов Ломает security-обновления Фиксировать имя пакета, не версию
Забыть про EPEL dnf install падает на чистой машине Указывать репозиторий явно в дескрипторе
Смешать dev и runtime-пакеты Раздувает прод-образ Разделить на два файла
Не указать роль сервера Web получает пакеты для БД Помечать пакеты ролью: web, db, worker
Обновлять дескриптор отдельным MR Расхождение дескриптора и кода Править в том же MR, что и код

Отдельно про EPEL. Если нужный пакет есть только в EPEL, укажите это в дескрипторе явно — строкой подключения репозитория или отдельной секцией repos. Не надейтесь, что на новой машине репозиторий уже подключён. На свежем Rocky или AlmaLinux EPEL по умолчанию не активен, и dnf install упадёт с «No match for argument» именно на тех пакетах, которые в проекте считались сами собой разумеющимися. Мы видели это с image-обработкой и парсингом XML: код в репозитории есть, модуль на месте, а зависимость не встаёт, потому что репозиторий не подключён.

Читайте также: SEO-продвижение сайта: как мы выводим проекты в топ и что реально работает в 2026.

Частые вопросы

Можно ли использовать один и тот же дескриптор пакетов для Rocky Linux 9 и AlmaLinux 9?

Да, оба дистрибутива бинарно совместимы с RHEL 9 и используют общий набор репозиториев BaseOS и AppStream, поэтому список из dnf install применим без изменений. Отличия появятся только если вы подключаете фирменные репозитории вроде Rocky Plus или AlmaLinux CRB — их нужно указывать отдельно.

Что делать, если dnf не находит пакет, который был установлен на старом сервере из EPEL или Remi?

Зафиксируйте сам репозиторий в дескрипторе: dnf install epel-release или dnf install https://rpms.remirepo.net/enterprise/remi-release-9.rpm, а уже потом перечисляйте пакеты. Иначе на чистой машине dnf install php-imagick или php-redis упадёт с «No match for argument».

Чем отличается фиксация через dnf history userinstalled от ручного списка в requirements.txt?

dnf history userinstalled показывает только то, что вы ставили явно, без транзитивных зависимостей — это компактнее, но не воспроизводит точные версии. Ручной список с версиями (nginx-1.24.0, php-8.2) даёт детерминированную установку, но требует обновлять его при каждом апгрейде.

А если у меня Bitrix работает в Docker-контейнере — нужен ли такой дескриптор?

Да, но в виде Dockerfile: строки RUN dnf install -y ... внутри образа играют ту же роль, что дескриптор на голом сервере. Держите список пакетов в отдельном файле packages.txt и подключайте через COPY + xargs dnf install, чтобы не дублировать его между dev и prod.

Можно ли проверить дескриптор без поднятия полноценной копии прода?

Да, через podman run --rm -it rockylinux:9 bash или docker run с тем же образом — прогоните dnf install -y $(cat packages.txt) и убедитесь, что команда завершается с кодом 0. Этого достаточно, чтобы поймать опечатки в именах пакетов и отсутствующие репозитории до миграции.

Что делать, если после установки пакетов из дескриптора модуль Bitrix всё равно не работает?

Проверьте не только наличие пакета, но и активную версию через dnf module list php и переключение потока: dnf module reset php && dnf module enable php:remi-8.2. Часто проблема не в отсутствии пакета, а в том, что включён дефолтный модуль PHP 8.0 вместо нужного потока.

Читайте также: Техподдержка сайтов на Битрикс: что входит в работу инженеров, SLA и почему дешёвая поддержка дороже.

Ключевые выводы
  1. Миграция Bitrix на новый сервер ломает модули из-за отсутствия системных библиотек.
  2. Ручное выявление зависимостей — долгий процесс; нужен единый файл-дескриптор.
  3. Файл bitrix-deps.list содержит список RPM-пакетов, устанавливаемых одной командой DNF.
  4. Список собирается через анализ логов ошибок, проверку PHP-модулей и rpm -qa на старом сервере.
  5. Интеграция в CI/CD позволяет автоматически проверять актуальность зависимостей при деплое.
#Bitrix #RPM #DNF #Linux #Ansible
автор · Backend / SRE Engineer
Артем Колячек

Backend-разработчик и SRE в студии Paradigma. Занимается тем, что у других проектов обычно обнаруживается за неделю до запуска: переездом Bitrix-проектов между серверами, починкой кешей после миграций, выстраиванием pipeline для контейнеров, мониторингом под нагрузкой.

До Paradigma — 7 лет в backend (PHP + Postgres) и в operations (Linux, Docker, Coolify, restic-бэкапы). Любит когда логи разговаривают полным синтаксисом ошибки, а не «что-то пошло не так».

На блоге пишет ровно про те ситуации с которыми сам разбирался руками: какой Bitrix-апдейт сломал кеш и как откатить, почему Docker-сеть не находит контейнер после рекрейта, что делать когда asyncpg ругается на event loop.