Установка FOSSBilling на Debian 11 с LEMP

Зачем этот материал

FOSSBilling — свободная система биллинга, подходящая для малого и среднего бизнеса. Руководство ориентировано на системных администраторов и инженеров DevOps, которым нужно быстро и прозрачно развернуть рабочую инстанцию с учётом безопасности и эксплуатации.

Важно: перед началом убедитесь, что у вас есть доступ к серверу с Debian 11, домен, указывающий на IP, и пользователь с правами sudo.

Содержание

• Требования и подготовка
• Установка Nginx
• Настройка UFW
• Установка MariaDB и подготовка базы
• Установка PHP-FPM 8.2 и расширений
• Скачивание и установка FOSSBilling
• Настройка Nginx для FOSSBilling
• SSL/TLS через LetsEncrypt и Certbot
• Финальная настройка и запуск установщика
• Рекомендации по безопасности и резервированию
• Чек-листы для ролей: админ, оператор, разработчик
• Тесты приёмки и сценарии отката
• Часто задаваемые вопросы

Требования

Кратко — что потребуется перед началом:

• Сервер с Debian 11 (в примерах hostname: fossbilling-server).
• Непользователь root: пользователь с sudo.
• Домен или поддомен, указывающий на IP сервера (пример: fossbilling.howtoforge.local).
• Доступ к электронной почте для регистрации в LetsEncrypt.

Совет: для тестов в локальной сети можно использовать /etc/hosts, но для получения сертификата LetsEncrypt потребуется публичный DNS.

Установка Nginx

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

sudo apt update
sudo apt install nginx

Проверьте статус сервиса и включение при старте:

sudo systemctl is-enabled nginx
sudo systemctl status nginx

Если всё нормально, Nginx будет в состоянии active (running) и enabled.

Совет: если порт 80 занят, найдите процесс через sudo ss -ltnp | grep :80 и остановите конфликтующий сервис.

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

UFW — простой фронтенд для iptables. Установите и откройте порты SSH, HTTP и HTTPS:

sudo apt install ufw
sudo ufw allow OpenSSH
sudo ufw allow "WWW Full"
sudo ufw enable
sudo ufw status

Ожидаемый вывод: Firewall is active и правила для OpenSSH и WWW Full.

Важно: включайте UFW только после добавления правила для SSH, чтобы не потерять доступ.

Установка и защита MariaDB

Установите MariaDB и запустите скрипт безопасной конфигурации:

sudo apt install mariadb-server
sudo systemctl enable --now mariadb
sudo mariadb-secure-installation

При выполнении mariadb-secure-installation рекомендуется:

• Switch local authentication to unix_socket? — n
• Set up root password? — y (и введите надёжный пароль)
• Remove anonymous users? — y
• Disable root remote login? — y
• Remove test database? — y
• Reload privilege tables? — y

Создайте базу и пользователя для FOSSBilling (замените password на собственный):

sudo mariadb -u root -p
CREATE DATABASE fossbillingdb;
CREATE USER 'fossbilling'@'localhost' IDENTIFIED BY 'password';
GRANT ALL ON fossbillingdb.* TO 'fossbilling'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;
EXIT;

Проверьте права:

SHOW GRANTS FOR 'fossbilling'@'localhost';

Совет по безопасности: используйте длинные случайные пароли и храните их в менеджере секретов (vault, pass, LastPass и т.д.).

Установка PHP-FPM 8.2 и расширений

FOSSBilling поддерживает PHP 8.x. В Debian 11 PHP 8.2 не в основном репозитории, поэтому используем репозиторий Ondřej Surý.

Установите зависимости и добавьте репозиторий:

sudo apt install ca-certificates gnupg2 apt-transport-https software-properties-common
wget -q -O /usr/share/keyrings/sury-php.gpg https://packages.sury.org/php/apt.gpg
echo "deb [signed-by=/usr/share/keyrings/sury-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/sury-php.list
sudo apt update

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

sudo apt install php8.2 php8.2-fpm
sudo apt install libcurl4-openssl-dev php8.2-mysql php8.2-curl php8.2-cli php8.2-zip php8.2-common php8.2-mbstring php8.2-xml

Настройте параметры php.ini для FPM (откройте файл для редактирования):

sudo nano /etc/php/8.2/fpm/php.ini

Измените или добавьте значения:

upload_max_filesize = 16M
post_max_size = 32M
memory_limit = 256M
max_execution_time = 600
max_input_vars = 3000
max_input_time = 1000

Перезапустите сервис и проверьте его статус:

sudo systemctl restart php8.2-fpm
sudo systemctl is-enabled php8.2-fpm
sudo systemctl status php8.2-fpm
php --version
php -m

Примечание: путь к сокету может быть /run/php/php8.2-fpm.sock. Запомните точный путь для конфигурации Nginx.

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

Создайте директорию и скачайте стабильный релиз:

sudo apt install unzip -y
sudo mkdir -p /var/www/fossbilling
cd /var/www/fossbilling
sudo curl https://fossbilling.org/downloads/stable -L --output FOSSBilling.zip
sudo unzip FOSSBilling.zip
sudo chown -R www-data:www-data /var/www/fossbilling
sudo chmod -R 755 /var/www/fossbilling

Проверьте, что файлы извлечены и доступны пользователю www-data.

Настройка Nginx для FOSSBilling

Создайте конфигурацию сайта:

sudo nano /etc/nginx/sites-available/fossbilling

Пример server-блока (не забудьте заменить server_name и путь к сокету PHP-FPM):

server {
    listen 80;

    set $root_path '/var/www/fossbilling';
    server_name fossbilling.howtoforge.local;

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

    include /etc/nginx/mime.types;

    location ~* \.(ini|sh|inc|bak|twig|sql)$ {
        return 404;
    }

    location ~ /\.(?!well-known/) {
        return 404;
    }

    location ~* /uploads/.*\.php$ {
        return 404;
    }

    location ~* /data/ {
        return 404;
    }

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

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_intercept_errors on;
        include fastcgi_params;
    }

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

Активируйте сайт, проверьте конфигурацию и перезапустите Nginx:

sudo ln -s /etc/nginx/sites-available/fossbilling /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Ошибка: если nginx -t выдаёт сообщение о fastcgi_pass, убедитесь, что путь к сокету совпадает с тем, что показан в systemctl status php8.2-fpm.

SSL/TLS: Certbot и LetsEncrypt

Установите Certbot и плагин для Nginx:

sudo apt install certbot python3-certbot-nginx

Создайте сертификат и включите перенаправление на HTTPS (замените email и домен):

sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email admin@example.com -d fossbilling.howtoforge.local

Certbot автоматически обновит конфигурацию Nginx и добавит задачу для автообновления сертификата.

Проверка принудительного обновления сертификатов:

sudo certbot renew --dry-run

Примечание: сертификаты хранятся в /etc/letsencrypt/live/ваш-домен/.

Запуск установщика FOSSBilling

Откройте браузер по адресу: https://fossbilling.howtoforge.local/

Установщик проверит системные требования. На этапе ввода данных укажите:

• Данные MariaDB (fossbillingdb, пользователь fossbilling и пароль).
• Административный аккаунт: email, пароль, имя пользователя и валюту по умолчанию.

После успешной установки удалите папку install и обновите права:

sudo rm -rf /var/www/fossbilling/install
sudo chmod 0644 /var/www/fossbilling/config.php

Создайте cron для фоновых задач FOSSBilling под пользователем www-data:

sudo crontab -u www-data -e

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

*/5 * * * * php /var/www/fossbilling/cron.php

Проверьте доступ к клиентской и админ-панелям и войдите в систему.

Рекомендации по безопасности и эксплуатация

1. Права и владельцы

   • Веб-файлы должны принадлежать www-data:www-data.
   • Конфигурационный файл config.php — 0644.
   • Установочная папка — удалена.

2. Обновления

   • Обновляйте Debian и пакеты с sudo apt update && sudo apt upgrade.
   • Следите за обновлениями FOSSBilling и плагинов.

3. Бэкапы

   • Резервируйте базу данных (mysqldump или инструменты копирования).
   • Резервируйте /var/www/fossbilling и конфиги Nginx.
   • План: ежедневный дамп БД и еженедельный бэкап файлов.

4. Мониторинг и логи

   • Настройте логирование: /var/log/nginx и /var/log/php8.2-fpm.log.
   • Используйте мониторинг состояния (Prometheus, Netdata, Zabbix).

5. Жёсткая конфигурация Nginx

   • Ограничьте доступ к административной панели по IP, если возможно.
   • Включите HTTP Strict Transport Security (HSTS) через Certbot флаг –hsts.

6. Защита от брутфорса

   • Используйте fail2ban с фильтрами для Nginx и админ-логина.

7. SMTP

   • Настройте отдельный SMTP-сервер или сервис (SendGrid, Postfix с relay).
   • Не используйте localhost без защиты.

Резервирование и откат (Rollback)

Минимальный план отката:

• Перед обновлением: сделать полный дамп базы и архив /var/www/fossbilling.
• Если обновление привело к сбою:
  1. Остановить веб-сервер: sudo systemctl stop nginx
  2. Восстановить файлы из архива
  3. Восстановить дамп БД: mysql -u root -p fossbillingdb < dump.sql
  4. Перезапустить сервисы

Критерии приёмки: установка доступна по HTTPS, вход в админ-панель возможен, cron выполняет задачи (последняя запись в логах cron.php), все системные проверки в инсталлере — Ok.

Чек-листы по ролям

Чек-лист для системного администратора:

• Домен указывает на сервер
• Пользователь sudo создан
• Установлен и запущен Nginx
• UFW настроен и SSH открыт
• MariaDB настроен и защищён
• PHP-FPM 8.2 установлен и запущен
• SSL получен и проверен
• Cron для www-data создан
• Бэкап настроен

Чек-лист для оператора (DevOps):

• Мониторинг метрик и логов настроен
• Автообновление сертификатов работает
• Политика ротации логов настроена
• План восстановления протестирован

Чек-лист для разработчика/интегратора:

• Локальная копия базы и файлов доступна для разработки
• Поддерживается тестовая инстанция
• Плагин или модуль проверен в staging

Тесты приёмки (Acceptance)

1. Доступность: HTTPS на главной странице, код ответа 200.
2. Авторизация: создание админа на этапе установки и успешный логин.
3. База: соединение с MariaDB — успешное использование учетных данных.
4. Cron: задача cron.php запускается каждые 5 минут и выполняет работу без ошибок.
5. Безопасность: install каталог удалён; config.php не имеет прав на запись для группы/других.

Частые проблемы и способы их решения

Проблема: 502 Bad Gateway после настройки Nginx.

• Причина: PHP-FPM не запущен или сокет указан неверно.
• Решение: sudo systemctl status php8.2-fpm и проверьте путь сокета в конфиге Nginx (fastcgi_pass).

Проблема: Certbot не может подтвердить домен.

• Причина: DNS не пропагирован или порт 80 заблокирован.
• Решение: проверьте A-запись, убедитесь, что UFW разрешает HTTP, и что Nginx отвечает по 80.

Проблема: Ошибки прав на файлы (permission denied).

• Решение: sudo chown -R www-data:www-data /var/www/fossbilling и проверьте umask/ACL.

Альтернативы и варианты развёртывания

• Apache вместо Nginx: можно использовать Apache + PHP-FPM, но потребуется адаптировать конфигурацию виртуального хоста.
• Docker: развернуть FOSSBilling в контейнерах (Nginx, PHP-FPM, MariaDB). Удобно для изоляции и оркестрации, но требует Docker/Compose знаний.
• Управляемые БД: использовать удалённую MariaDB в облаке, следить за сетевой безопасностью и latency.

Когда не использовать FOSSBilling:

• Если нужна коммерческая поддержка с SLA, и проект требует корпоративной подписки — выбирайте решения с поддержкой.
• Если необходима интеграция с проприетарными шлюзами, не поддерживаемыми FOSSBilling.

Миграция из BoxBilling

FOSSBilling — форк BoxBilling. При миграции:

• Создайте резервную копию базы BoxBilling.
• Проверьте структуру таблиц — некоторые поля могли измениться в форке.
• Запустите тестовую миграцию в staging и проверьте целостность данных и платежные интеграции.

Совет: сохраните старую систему в режиме только чтения до проверки миграции.

Безопасность и соответствие (GDPR/конфиденциальность)

• Логи и бэкапы содержат персональные данные. Ограничьте доступ к ним и храните шифрованными, если это возможно.
• Убедитесь, что политики хранения данных соответствуют локальным требованиям (удаление/архивация данных клиентов по запросу).
• Включите двухфакторную аутентификацию для административного доступа, если модуль доступен.

Небольшая методология развертывания (mini-метод)

1. Подготовка сервера и резервной среды (staging).
2. Установка LEMP и базовой безопасности (UFW, MariaDB secure).
3. Развёртывание FOSSBilling и выполнение инсталлятора.
4. Тестирование функциональности и интеграций (платежи, письма).
5. Перенос в production с сохранением откатной точки.

Принцип принятия решений: Impact × Effort

• SSL (высокое влияние, низкие усилия) — делайте сразу.
• Бэкап БД (высокое влияние, низкие усилия) — делать регулярно.
• WAF/Fail2ban (среднее влияние, средние усилия) — внедрять по приоритету.

Советы по производительности

• Включите кэширование на стороне Nginx для статики.
• По необходимости используйте opcode-кеш (Zend OPcache включён в PHP).
• Для большого количества клиентов рассмотрите репликацию базы данных и балансировщик нагрузки.

Совместимость и примечания по версиям

• Рекомендуемые PHP: 8.1 или 8.2. Проверяйте совместимость плагинов перед обновлением.
• MariaDB: совместима с версиями 10.x; при переходе на MySQL проверьте сопоставимость SQL.

Decision flowchart

flowchart TD
  A[Начало: есть сервер Debian 11?] --> B{Домен публичен?}
  B -- Да --> C[Установить LEMP]
  B -- Нет --> D[Настроить DNS или /etc/hosts для теста]
  C --> E{PHP 8.2 доступен?}
  E -- Да --> F[Установить PHP-FPM 8.2 и расширения]
  E -- Нет --> G[Добавить репозиторий Sury и повторить]
  F --> H[Скачать FOSSBilling и настроить Nginx]
  H --> I[Получить SSL через Certbot]
  I --> J[Запустить веб-инсталлятор]
  J --> K{Инсталляция успешна?}
  K -- Да --> L[Удалить /install, настроить cron]
  K -- Нет --> M[Проверить логи и права, исправить и повторить]

Короткое руководство по откладке (cheat sheet)

• Проверить сокет PHP-FPM: sudo systemctl status php8.2-fpm
• Проверить Nginx: sudo nginx -t && sudo systemctl restart nginx
• Проверить UFW: sudo ufw status verbose
• Проверить доступность порта: sudo ss -ltnp | grep LISTEN
• Просмотреть логи: sudo tail -f /var/log/nginx/error.log

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

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

Да. Конфигурация виртуального хоста и правила перезаписи будут отличаться. Apache + PHP-FPM работает корректно, но примеры в этом руководстве рассчитаны на Nginx.

Как продлить сертификат LetsEncrypt?

Certbot выполняет автоматическое продление. Для ручной проверки используйте sudo certbot renew –dry-run.

Как настроить почту для отправки писем от FOSSBilling?

Рекомендуется внешний SMTP (например, SendGrid, Mailgun) или настроенный Postfix с relay. Укажите данные SMTP в админ-панели FOSSBilling.

Что делать, если при установке инсталлер жалуется на права файлов?

Проверьте владельца и права: sudo chown -R www-data:www-data /var/www/fossbilling && sudo chmod -R 755 /var/www/fossbilling, а затем убедитесь, что config.php — 0644.

Краткое резюме

В этой инструкции вы узнали, как развернуть FOSSBilling на Debian 11 с использованием LEMP, защитить сайт SSL-сертификатом от LetsEncrypt, создать базу данных и настроить фоновые задачи. Приложены чек-листы, тесты приёмки, рекомендации по безопасности и варианты миграции.

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

Ключевые ссылки и команды в одном месте:

• Установить Nginx: sudo apt install nginx
• Установить MariaDB: sudo apt install mariadb-server
• Безопасность MariaDB: sudo mariadb-secure-installation
• Установить PHP 8.2: добавить репозиторий sury и sudo apt install php8.2 php8.2-fpm
• Скачать FOSSBilling: curl https://fossbilling.org/downloads/stable -L –output FOSSBilling.zip
• Certbot: sudo apt install certbot python3-certbot-nginx
• Создать cron: crontab -u www-data -e и добавить /5 * php /var/www/fossbilling/cron.php

Примечание: все пути и доменные имена в примерах нужно заменить на реальные значения вашей среды.