Главные выводы за 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, выглядит так:
# 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. Всё, что вы делаете, это два списка и одно вычитание. Дальше разберём по шагам, а в конце покажем скрипт, который делает это одной командой.
- На работающем сервере снять полный список установленных пакетов через
rpm -qaи сохранить в файл:rpm -qa | sort > /tmp/all-packages.txt. - Вычесть пакеты, которые входят в группы
@coreи@standard— они приедут с любой базовой установкой Rocky или AlmaLinux и в дескрипторе не нужны, иначе список распухнет до сотен строк, которые ничего не значат. - Сопоставить оставшиеся пакеты с расширениями PHP через
php -mи с бинарниками черезldd— понять, что реально требуется проекту, а что тянется транзитивно или осталось от чьих-то экспериментов. - Проверить каждый пакет на чистом контейнере: если без него модуль падает — он идёт в дескриптор, если нет — выкидываем. Это не формальность, а обязательный фильтр.
#!/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:
# system-requirements.yml -> плоский список имён пакетов
sudo dnf install -y $(yq -r '.packages[]' system-requirements.yml)Если yq под рукой нет, а структура простая, тот же результат даёт grep по строкам списка:
# вытаскиваем имена из строк вида " - 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 нужен воркеру парсинга, но не балансировщику.
- 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 (как мы разбирали в предыдущей секции), этот шаг встраивается в пайплайн и запускается на каждый коммит в дескриптор.
# Чистый контейнер с тем же базовым образом, что и целевой сервер
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 и почему дешёвая поддержка дороже.
- Миграция Bitrix на новый сервер ломает модули из-за отсутствия системных библиотек.
- Ручное выявление зависимостей — долгий процесс; нужен единый файл-дескриптор.
- Файл bitrix-deps.list содержит список RPM-пакетов, устанавливаемых одной командой DNF.
- Список собирается через анализ логов ошибок, проверку PHP-модулей и rpm -qa на старом сервере.
- Интеграция в CI/CD позволяет автоматически проверять актуальность зависимостей при деплое.