Установка BoxBilling с Nginx, PHP‑FPM и MariaDB на Debian 11

BoxBilling — это биллинговое ПО с открытым исходным кодом, написанное на PHP. Оно бесплатное, ориентировано на удобство клиентов и продавцов, и поддерживает несколько платёжных шлюзов. В этом руководстве показано, как развернуть BoxBilling на Debian 11 Bullseye с Nginx, PHP‑FPM и MariaDB.

Кому полезно это руководство

• Системным администраторам, которым нужно запустить BoxBilling в продакшене.
• Разработчикам, настраивающим окружение для тестовой среды.
• Хостинг‑провайдерам, которые хотят предложить биллинг на управляемых серверах.

Важно: в продакшене используйте домен с корректными DNS‑записями и HTTPS.

Основные шаги

1. Подготовить сервер и DNS.
2. Установить PHP‑FPM (версия ≥7.4) и расширения.
3. Установить Nginx и MariaDB.
4. Создать базу и пользователя MariaDB.
5. Скачать BoxBilling, настроить права и Nginx.
6. Пройти веб‑установку и выполнить постустановочные задачи.

Требования

• Сервер с Debian 11 Bullseye.
• Пользователь с sudo‑привилегиями.
• Домен или субдомен, указывающий на IP сервера (обязательно для HTTPS).

Установка и настройка PHP

BoxBilling требует PHP‑FPM версии 7.4 или выше. В репозитории Debian 11 по умолчанию доступна 7.4.

Обновите индекс пакетов:

sudo apt update

Установите PHP‑FPM и необходимые расширения:

sudo apt install php-fpm php-cli php-common php-zip php-mysql php-gd php-intl php-curl php-imap php-mbstring php-xml php-json libpcre3 openssl git unzip -y

Отредактируйте конфигурационные файлы php.ini для FPM и CLI:

sudo nano /etc/php/7.4/fpm/php.ini
sudo nano /etc/php/7.4/cli/php.ini

Рекомендуемые параметры для сервера с 2 ГБ ОЗУ (подкорректируйте под ваш хостинг):

memory_limit = 512M
max_execution_time = 360
date.timezone = Europe/Paris

Примечание: укажите ваш часовой пояс, например Europe/Moscow. Сохраните и закройте файлы.

Перезапустите PHP‑FPM и проверьте статус:

sudo systemctl restart php7.4-fpm
sudo systemctl status php7.4-fpm

Важно: если вы используете другую версию PHP (8.0, 8.1), замените пути и имена сервисов соответствующе (php8.0-fpm и т.д.).

Установка Nginx и MariaDB

BoxBilling работает с MySQL 8+ и совместим с MariaDB. Установите Nginx и MariaDB:

sudo apt install nginx-full mariadb-server -y

Проверьте статусы сервисов:

sudo systemctl status nginx
sudo systemctl status mariadb

Базовая защита MariaDB

Запустите утилиту безопасной настройки MariaDB:

mysql_secure_installation

Ответьте на вопросы утилиты по следующему сценарию:

• Нажмите Enter при текущем пароле (если ещё нет).
• Включите unix_socket authentication при необходимости.
• Установите root‑пароль.
• Удалите анонимных пользователей.
• Запретите удалённый вход root.
• Удалите тестовую базу.
• Перезагрузите привилегии.

Пример диалога показан в шаге ниже — утилита подскажет и подтвердит изменения.

Создание базы и пользователя для BoxBilling

Войдите в консоль MariaDB как root:

mysql -u root -p

Создайте базу и пользователя (замените пароль на надёжный):

CREATE DATABASE boxbilling;
CREATE USER boxbilling@localhost IDENTIFIED BY 'dbpassBoxBilling';
GRANT ALL ON boxbilling.* TO boxbilling@localhost WITH GRANT OPTION;
FLUSH PRIVILEGES;

Выйдите из оболочки:

exit

Совет по безопасности: используйте сложный пароль, ограничьте доступ по IP, и при возможности включите регулярное резервное копирование.

Скачивание исходников BoxBilling

Создайте веб‑корень и перейдите в него:

mkdir -p /var/www/boxbilling/
cd /var/www/boxbilling

Скачайте стабильную версию BoxBilling. На момент исходного руководства это v4.22:

wget https://github.com/boxbilling/boxbilling/releases/download/4.22.1.3/BoxBilling.zip
unzip Boxbilling.zip

Создайте каталоги для данных и кэша, установите права:

mkdir -p /var/www/boxbilling/bb-data/{cache,uploads}
sudo chown -R www-data:www-data /var/www/boxbilling
sudo chmod u+rw /var/www/boxbilling/bb-data/{cache,uploads}

Совет: храните bb-data на отдельном разделе или делайте симлинк на диск с резервным копированием.

Конфигурация Nginx для BoxBilling

Создайте серверный блок в /etc/nginx/sites-available/boxbilling.conf. В примере ниже замените billing.example.io на ваш домен и укажите пути к сертификатам:

server {
    listen 80;
    server_name billing.example.io;
    return 302 https://$server_name$request_uri;
}

server {
  listen 443 ssl http2;

     set $root_path '/var/www/boxbilling';

     server_name  billing.example.io;

     index index.html index.htm index.php;
     root $root_path;
     try_files $uri $uri/ @rewrite;
     sendfile off;

  ssl_certificate /etc/letsencrypt/live/billing.example.io/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/billing.example.io/privkey.pem;

  ssl_protocols TLSv1.2;
  ssl_prefer_server_ciphers on;
  ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384;
  ssl_ecdh_curve secp384r1;
  ssl_session_timeout  10m;
  ssl_session_cache shared:SSL:10m;
  ssl_session_tickets off;
  resolver 8.8.8.8 8.8.4.4 valid=300s;
  resolver_timeout 5s;
  add_header X-Frame-Options DENY;
  add_header X-Content-Type-Options nosniff;
  add_header X-XSS-Protection "1; mode=block";

    access_log /var/log/nginx/example.com.access.log;
    error_log /var/log/nginx/example.com.error.log;

     location @rewrite {
         rewrite ^/(.*)$ /index.php?_url=/$1;
     }

    location ~ \.php$ {
         include snippets/fastcgi-php.conf;
         fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
         include fastcgi_params;
         fastcgi_intercept_errors on;
    }

     location ^~ /bb-uploads/ { }
     location ^~ /bb-data/ {
       deny all;
     }

     location ~* ^/(css|img|js|flv|swf|download)/(.+)$ {
         root $root_path;
         expires off;
         proxy_no_cache 1;
         proxy_cache_bypass 1;
     }

     location ~ /\.ht {
         deny all;
     }
 }

Сделайте ссылку в sites-enabled и проверьте конфигурацию:

ln -s /etc/nginx/sites-available/boxbilling.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Советы по SSL: используйте certbot для автоматического получения и продления сертификатов Let’s Encrypt. Проверяйте цепочку сертификатов и включите HSTS с осторожностью.

Важно: убедитесь, что fastcgi_pass указывает на корректный сокет PHP‑FPM. Для других версий PHP путь будет отличаться.

Установка BoxBilling через веб‑интерфейс

Откройте браузер и перейдите по адресу:

https://boxbilling.example.io/

1. Убедитесь, что на странице проверки системы все требования отмечены зелёным.
2. Примите лицензию и нажмите NEXT.
3. Введите данные базы данных (boxbilling / dbpassBoxBilling).
4. Создайте администратора: логин, email, пароль.
5. Нажмите FINISH.

После установки вы попадёте на главную страницу BoxBilling.

Постустановочные шаги

1. Удалите каталог install:

rm -rf /var/www/boxbilling/install

2. Ограничьте права на конфигурационный файл:

sudo chmod 644 /var/www/boxbilling/bb-config.php

Это позволит пользователю www-data писать в файл, а остальным запретит запись.

3. Создайте cron задачу для выполнения фоновых задач BoxBilling от имени www-data:

export EDITOR=nano
sudo crontab -u www-data -e

Добавьте строку:

*/5 * * * * php /var/www/boxbilling/bb-cron.php

Сохраните и закройте редактор.

Вход в админку

Админ‑панель доступна по пути /bb-admin:

https://boxbilling.example.io/bb-admin/

Вводите логин и пароль администратора и нажмите LOG ME IN.

Проверочные тесты и критерии приёмки

Критерии приёмки перед сдачей установки в эксплуатацию:

• Сайт доступен по HTTPS и корректно перенаправляет с HTTP.
• PHP‑FPM работает и обрабатывает .php файлы.
• Подключение к базе данных работает, миграции выполнены.
• Cron‑задача работает (проверить логи и обновления статусов).
• Доступ к bb-data и uploads защищён (директории недоступны по HTTP).

Минимальный тестовый набор:

• Откройте главную страницу магазина и страницу входа.
• Создайте тестовый товар и выполните фиктивный заказ (sandbox).
• Проверьте уведомления по email (настройки SMTP).
• Проверьте резервное копирование базы и восстановление на тестовой машине.

Резервное копирование и восстановление

• База данных: используйте регулярные дампы через mysqldump или инструменты резервного копирования с хранением архива вне сервера.
• Файлы: резервируйте /var/www/boxbilling/bb-data и пользовательский upload.
• Проверяйте восстановление раз в месяц.

Пример команды резервного копирования базы:

mysqldump -u root -p boxbilling | gzip > /backup/boxbilling_$(date +%F).sql.gz

Безопасность и жёсткая настройка

• Пропишите строгие права на файлы: 644 для конфигов, 640/600 для секретов.
• Ограничьте доступ к SSH (ключи, 2FA, порт, fail2ban).
• Включите автоматические обновления безопасности или настройте уведомления об обновлениях.
• Ограничьте доступ к панели администрирования по IP, если возможно.
• Регулярно проверяйте логи Nginx и PHP‑FPM на предмет подозрительной активности.

Дополнительные меры:

• Включите Content Security Policy (CSP) для снижения риска XSS.
• Включите HSTS после подтверждения корректности HTTPS.
• Используйте WAF (например, ModSecurity) перед приложением.

Производительность и тюнинг

• Включите OPCache для PHP: добавьте в php.ini параметры opcache.
• Настройте Nginx: включите gzip, настройте буферы, используйте sendfile off для PHP‑приложений при необходимости.
• Используйте Redis или Memcached для кэширования, если BoxBilling или плагины поддерживают это.

Пример базовой конфигурации OPcache:

opcache.enable=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=10000
opcache.revalidate_freq=2

Тесты приёмки и контрольные кейсы

• Сценарий регистрации пользователя: регистрация, подтверждение email.
• Электронные счета: создание счёта, отправка на email.
• Обновление тарифа: услуга с периодичностью и автоматическим выставлением счета.
• Резервное восстановление: импорт дампа и проверка работоспособности.

Частые ошибки и их решение

• 502 Bad Gateway: проверьте, запущен ли php7.4-fpm и совпадает ли путь сокета в fastcgi_pass.
• 500 Internal Server Error: смотрите журналы Nginx и PHP‑FPM, включите отображение ошибок в dev‑режиме.
• Ошибки доступа к базе: проверьте учётные данные в web‑установщике и права пользователя базы.

Миграция и обновления

• Перед обновлением всегда делайте полный бэкап файлов и базы.
• Сверяйте совместимость версии BoxBilling с версией PHP и расширениями.
• Тестируйте обновление на стейджинг‑сервере перед применением в проде.

Роль‑ориентированные чеклисты

Администратор сервера:

• Установить и настроить Nginx, PHP‑FPM, MariaDB.
• Настроить HTTPS и защиту.
• Настроить cron и бэкапы.

Менеджер продукта / оператор:

• Проверить бизнес‑процессы в BoxBilling.
• Настроить валюты, тарифы и методы оплаты.
• Проверить уведомления и шаблоны писем.

Разработчик:

• Проверить логи и расширения PHP.
• Настроить интеграции с платёжными шлюзами.
• При необходимости написать миграции и тесты.

Мини‑методология развертывания (четкие шаги)

1. Подготовить сервер (обновления, пользователи).
2. Установить и настроить стэк (PHP, Nginx, MariaDB).
3. Настроить HTTPS.
4. Скопировать код и права доступа.
5. Запустить веб‑установщик и пройти настройку.
6. Постустановочные проверки, бэкап и мониторинг.

1‑строчный глоссарий

• PHP‑FPM: менеджер процессов PHP для веб‑серверов.
• Nginx: высокопроизводительный веб‑сервер и обратный прокси.
• MariaDB: форк MySQL, СУБД.
• bb-data: каталог BoxBilling для кэша и загруженных файлов.

Часто задаваемые вопросы

Какие версии PHP поддерживает BoxBilling?

BoxBilling в релизах v4.x стабильно работает с PHP 7.4 и выше; при использовании PHP 8 проверьте совместимость расширений и тесты.

Можно ли использовать MariaDB вместо MySQL?

Да. BoxBilling совместим с MariaDB. Главное — убедиться, что версия сервера совместима и поддерживает требуемые SQL‑функции.

Как настроить SSL автоматически?

Используйте certbot из пакета certbot‑nginx или certbot с ручной конфигурацией. Настройте автоматическое продление cron‑задачей.

Что делать, если Nginx возвращает 502?

Проверьте, запущен ли сервис php7.4-fpm; убедитесь, что fastcgi_pass указывает на корректный сокет или порт.

Заключение

Поздравляем! Вы установили и настроили BoxBilling на Debian 11 с Nginx, PHP‑FPM и MariaDB. Важно поддерживать систему в актуальном состоянии, регулярно резервировать данные и следить за безопасностью. После запуска проверьте бизнес‑функции: товары, выставление счетов и интеграции с платёжными шлюзами.

Важное: перед вводом в производство прогоните полные тесты на стейджинге и настройте мониторинг для оперативного реагирования.

Краткое резюме и дальнейшие шаги приведены в блоке ниже.

Ключевые действия после установки:

• Настроить резервное копирование.
• Подключить SMTP для уведомлений.
• Настроить платёжные шлюзы в тестовом режиме.
• Провести аудит прав доступа и логов.