Делюсь опытом разработки проекта, где потребовалось совместить Laravel и «Битрикс Управление Сайтом» в одной системе: подробно описал путь от настройки окружения и выбора инструментов до внедрения CI/CD и решения возникавших проблем. Если вы стоите перед выбором: быть или не быть, то сперва прочитайте эту статью.
Оглавление
Техническое задание
Инфраструктура
Документация
Битрикс как сервис
Классы сущностей для инфоблоков
JWT-авторизация
Организация маршрутов API: принципы и структура
Контроллеры: структура и принципы организации
Сервисы
Репозитории
Выводы и предостережения
Техническое задание
Техническое задание жёстко требовало использования CMS «Битрикс Управление Сайтом» для административной части. Однако, оценив сложность предстоящего REST API и имеющийся опыт команды в Laravel, я выбрал гибридную архитектуру: подход позволил соблюсти формальные требования ТЗ, но вести разработку API в предсказуемой и знакомой экосистеме.
Мой первый опыт работы с Битрикс сводился к классической разработке — внедрению верстки в готовые компоненты. Самым сложным испытанием тогда стала кастомизация процесса оформления заказа. Система казалась невероятно громоздкой. Сейчас, конечно, меня ей не напугать, потому что знаю, что всё можно переопределить или написать собственную реализацию. Но лёгкая тревога осталась: а справлюсь ли я?
Изучая опыт рынка, я встречал кейсы успешной интеграции Laravel и Битрикс в крупных студиях. Этот подход позволял оставить мощную админку Битрикс для клиента, но вести разработку по современным стандартам. Учитывая требования ТЗ и положительный опыт коллег, такое решение казалось оптимальным компромиссом.
Инфраструктура
Перед деплоем на тестовый сервер, я локально подготовил окружение и определил список сервисов, которые потребуются для работы проекта. Я не нашёл официальной информации от разработчиков Битрикс о рекомендуемом образе docker: встретил парочку репозиториев, но они показались нестабильными. Поэтому я решил собрать свой контейнер на базе php-8.4, написав инструкцию по созданию в Dockerfile.
Во время установки Bitrix выполняется проверка установленных расширений PHP, необходимых для корректной работы модулей Битрикс. Используя установщик Битрикс и немного Google, нашёл всё необходимое для добавления в свой PHP-образ.
php/Dockerfile
FROM php:8.4-fpm
RUN apt-get update && apt-get install -y \
libfreetype6-dev \
libjpeg62-turbo-dev \
libpng-dev \
libzip-dev \
libonig-dev \
libxml2-dev \
curl \
git
RUN docker-php-ext-configure gd --with-freetype --with-jpeg \
&& docker-php-ext-install -j$(nproc) gd \
&& docker-php-ext-install pdo_mysql \
mysqli \
mbstring \
xml \
zip
# Install Composer globally
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
# Add Composer to the PATH
ENV PATH="$PATH:/usr/local/bin"
WORKDIR /app/laravel
EXPOSE 9000
CMD ["php-fpm"]
Для базы данных я использовал образ MySQL из официального репозитория. Образ поставляется со всем необходимым для работы. Достаточно указать данные пользователя, имя базы данных и root-пароль. После скачивания система автоматически создаст базу данных и пользователя. Хост подключения будет доступен внутри сети по имени сервиса, а чтобы подключиться снаружи, нужно пробросить порт.
Уточнил версию Node у фронтенд-разработчика, чтобы избежать возможного конфликта, и загрузил из официального репозитория образ. Настроил автоматический npm install при создании контейнера.
Сделал маршрутизацию в nginx, настроив доступ к сервисам на одном домене.
Конфигурация NGINX
По умолчанию Laravel использует /public для точки входа, поэтому указал root /app/laravel/public. Там же разместил ядро Битрикс и upload для доступа к загружаемым файлам. Маршрут с /api обрабатывал Laravel, поэтому его тоже отдаём php-сервису. Все остальные маршруты обслуживает сервер Node с Next.js-фронтендом.
server {
listen 80;
root /app/laravel/public;
index index.php index.html;
client_max_body_size 25m;
location /upload/ {
try_files $uri $uri/;
}
# Обработка /bitrix/
location /bitrix/ {
try_files $uri $uri/ @bitrix;
}
# Обработка /api/
location /api/ {
try_files $uri $uri/ /index.php$is_args$args;
}
# Проксирование на фронтенд
location / {
proxy_pass http://frontend:3000/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location @bitrix {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root/bitrix/urlrewrite.php;
fastcgi_pass backend:9000;
fastcgi_index index.php;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
}
# Обработка PHP-запросов
location ~ \.php$ {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_pass backend:9000;
fastcgi_index index.php;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
}
}
Деплой и CI/CD
Когда появился каркас проекта, руководство запросило желаемые характеристики тестового сервера. На старте высоких нагрузок не предвиделось, поэтому взял скромный VPS: 20 ГБ SSD, 1 ГБ RAM.
Для настройки CI/CD мне рекомендовали использовать Drone.io, так как у команды уже был опыт работы с этим self-hosted решением. Drone.io поставляется как docker-образ и имеет множество плагинов, облегчающих интеграцию с другими системами. У сервиса есть удобная панель управления (Dashboard). Интерфейс отображает репозитории, за которыми следит Drone, логи и статусы обновлений. Секреты тоже настраиваются через веб-интерфейс.
После настройки панели управления нужно настроить runner. Runner — это приложение, которое будет подключаться к серверу и выполнять инструкции. Существует несколько способов подключения, я выбрал доступ по SSH. Есть официальный образ, но мы использовали сторонний:
docker pull appleboy/drone-ssh
Для оповещения команды об обновлении подключил готовый и настроенный образ для уведомлений в Telegram. Достаточно передать токен, и приложение будет ожидать сообщений для отправки.
В каждый репозиторий добавил файл конфигурации drone. В файле описан pipeline, который срабатывает каждый раз, когда была обновлена main-ветка. Drone подключается к серверу, выполняет обновление локального репозитория, перезапускает контейнер и отправляет уведомление в Telegram. В рамках пайплайна доступны переменные окружения, содержащие информацию о коммите, авторе и SHA-идентификаторе. По идентификатору можно собрать ссылку на GitHub.
.drone.yml
kind: pipeline
type: docker
name: default
steps:
- name: backend
image: appleboy/drone-ssh
settings:
host:
from_secret: SSH_HOST
username:
from_secret: SSH_USER
key:
from_secret: SSH_KEY
port: 22
script:
- echo "Run backend update"
- cd /app/backend/laravel
- git reset --hard HEAD
- git pull origin main
- echo "Backend updated!"
- cd /app
- git pull origin main
- docker compose restart
- echo "Backend config updated!"
- echo "Containers restarted!"
- name: notify
image: appleboy/drone-telegram:1.3.10
settings:
token:
from_secret: TELEGRAM_TOKEN
to:
from_secret: TELEGRAM_CHAT_ID
message: |
✅ Успешно развернуто приложение после коммита на ветке main!
Интересные статьи
Интересные статьи
