Руководство описывает развёртывание PmaControl для мониторинга серверов MariaDB / MySQL и проверку интерфейса, локальной базы и сбора данных.

Актуальный способ установки — пакет pmacontrol из подписанного APT-репозитория проекта. Он устанавливает MariaDB, плагин RocksDB, PHP CLI, FrankenPHP и зависимости приложения, а также инициализирует базу, учётные записи, периодические задания и веб-конфигурацию. Выделенная машина или ВМ позволяет избежать конфликтов с существующими службами.

Установка одной командой

На выделенной машине amd64 с Debian 12/13 или Ubuntu 24.04/26.04 выполните эту команду в терминале. Скрипт проверяет систему и ключ подписанного репозитория, затем устанавливает пакет PmaControl и его зависимости. Права администратора запрашиваются через sudo.

curl -fsSL https://pmacontrol.com/install.sh | sudo bash

Если вы уже работаете от root, замените sudo bash на bash. Посмотреть скрипт. После установки выполните описанные ниже проверки, настройку HTTPS и первый вход.

1. Выбор операционной системы

Система	Ветка APT	Архитектура	Метод
Debian 12	`bookworm`	`amd64`	Пакет APT
Debian 13	`trixie`	`amd64`	Пакет APT
Ubuntu 24.04 LTS	`noble`	`amd64`	Пакет APT
Ubuntu 26.04 LTS	`resolute`	`amd64`	Пакет APT
Docker	—	—	См. раздел Docker

На 26 сентября 2026 года во всех четырёх ветках доступен пакет 5.4.36-1. Актуальную версию на момент установки проверяйте командой apt-cache policy pmacontrol. Ветка разработки может быть новее опубликованного пакета. Пакеты ARM64 и старые версии Ubuntu не входят в эту процедуру.

2. Подготовка машины и сети

Подготовьте административный доступ, работающий DNS, синхронизированные часы и постоянное хранилище. Для небольшой инфраструктуры 2–4 vCPU, 4–8 ГиБ ОЗУ и 40 ГиБ SSD — ориентировочная начальная конфигурация, а не гарантированный минимум. Объём данных зависит от количества серверов, метрик, срока хранения и резервных копий. При включении резервного копирования выделите для него отдельное хранилище.

Разрешите входящий TCP 443 для уполномоченных пользователей и TCP 80 для перенаправления и, при необходимости, ACME. UDP 443 используется HTTP/3 и для клиентов необязателен. Нужны исходящий HTTPS к репозиториям, DNS/NTP к вашим службам, SQL к наблюдаемым серверам на их реальных портах и SSH 22 только для использующих его функций. Локальную базу не требуется открывать в Интернет.

Выполните проверки до установки. Если /var/lib/mysql ещё нет, проверьте свободное место в файловой системе, где он появится. Веб-порты должны быть свободны: пакет отклоняет чужой слушающий процесс и не отключает автоматически Apache, Nginx или Caddy.

cat /etc/os-release
dpkg --print-architecture
df -h / /var/lib/mysql
free -h
timedatectl status
ss -ltnp '( sport = :80 or sport = :443 )'
ss -lunp 'sport = :443'

3. Установка на Debian 12 или Debian 13

На выделенной машине Debian выполните следующий блок. Он автоматически выбирает bookworm или trixie, проверяет amd64, добавляет отдельный ключ репозитория через signed-by, показывает версию-кандидат и моделирует установку перед выполнением. На этапе моделирования проверьте добавляемые пакеты и прочие изменения. Последующие команды выполняются в оболочке root, открытой через sudo -i.

Отпечаток ключа, проверенный 26 сентября 2026 года: CAFD ABF8 7717 CC60 291E 68E4 D56A 0ADA AB5F 97E2. При изменении подтвердите ротацию у проекта, прежде чем продолжать. Не обходите ошибку подписи с помощью trusted=yes.

sudo -i
set -eu
. /etc/os-release
case "$ID:$VERSION_CODENAME" in
  debian:bookworm|debian:trixie|ubuntu:noble|ubuntu:resolute) ;;
  *) echo "Unsupported distribution: $ID:$VERSION_CODENAME" >&2; exit 1 ;;
esac
test "$(dpkg --print-architecture)" = amd64
apt-get update
apt-get install -y ca-certificates curl gnupg
install -d -m 0755 /etc/apt/keyrings
curl -fsSL --retry 3   https://repo.pmacontrol.com/debian/pmacontrol-archive-keyring.gpg   -o /etc/apt/keyrings/pmacontrol-archive-keyring.gpg
chmod 0644 /etc/apt/keyrings/pmacontrol-archive-keyring.gpg
gpg --show-keys --with-fingerprint   /etc/apt/keyrings/pmacontrol-archive-keyring.gpg
printf 'deb [arch=amd64 signed-by=/etc/apt/keyrings/pmacontrol-archive-keyring.gpg] https://repo.pmacontrol.com/debian %s main\n'   "$VERSION_CODENAME" > /etc/apt/sources.list.d/pmacontrol.list
apt-get update
apt-cache policy pmacontrol
apt-get -s install pmacontrol
apt-get install pmacontrol

4. Установка на Ubuntu 24.04 или Ubuntu 26.04

На Ubuntu выполните тот же блок APT из предыдущего раздела: он выбирает noble для 24.04 и resolute для 26.04. Сохраните уже настроенные официальные репозитории Ubuntu с правильной веткой. Репозиторий PmaControl предоставляет пакет и необходимые зависимости; не подменяйте noble на trixie на машине Ubuntu.

После apt-get install pmacontrol не запускайте повторно install.sh, не создавайте базу вручную и не добавляйте второй стек Apache/PHP-FPM. Скрипт post-install пакета уже выполняет инициализацию. PHP командной строки и PHP, встроенный во FrankenPHP, — разные среды: одной команды php -v недостаточно для проверки веб-среды.

5. Проверка установки и получение доступа

Пакет должен иметь состояние install ok installed, dpkg --audit не должен сообщать о незавершённой настройке, а MariaDB, FrankenPHP и cron должны быть активны. Маркер среды должен содержать frankenphp. Проверьте также загрузку RocksDB. HTTP-запрос должен перенаправляться на HTTPS; страница входа HTTPS должна отвечать без серверной ошибки.

Параметр -k в этой локальной проверке используется только для начального внутреннего сертификата. Для обычного доступа настройте сертификат по следующему разделу и проверяйте соединение без -k.

dpkg-query -W -f='${Status} ${Version}\n' pmacontrol
dpkg --audit
systemctl is-active mariadb frankenphp cron
systemctl is-enabled mariadb frankenphp cron
cat /etc/pmacontrol/active-runtime
mariadb -N -e "SELECT VERSION(); SELECT 1;"
mariadb -e "SHOW PLUGINS;" | awk 'NR == 1 || /ROCKSDB/'
curl -q --noproxy '*' -I http://127.0.0.1/
curl -q --noproxy '*' -k -I https://localhost/fr/user/connection/

Созданные данные доступа сохраняются в /root/pmacontrol-install.env, доступном только root, обычно с правами 0600. Просматривайте его в приватном терминале: PMACTRL_ADMIN_LOGIN и PMACTRL_ADMIN_PASSWORD дают административный доступ; переменные webservice относятся к API. Не отправляйте файл в обращении, репозитории или снимке экрана.

Откройте https://ВАШ-ХОСТ/fr/user/connection/, войдите и задайте личный пароль в профиле. Сохраните файл восстановления в зашифрованной резервной копии и обновляйте его при ротации записанных данных. После успешной инициализации временный /root/pmacontrol-install.json должен исчезнуть. Его наличие может означать незавершённую инициализацию: найдите ошибку перед удалением.

sudo stat -c '%a %U %G %n' /root/pmacontrol-install.env
sudo less /root/pmacontrol-install.env
sudo test ! -e /root/pmacontrol-install.json

6. Настройка имени DNS и HTTPS

По умолчанию FrankenPHP использует внутренний сертификат для localhost. Доступ по IP или ненастроенному имени может вызвать предупреждение о доверии или имени. Для публичного имени создайте запись DNS, указывающую на экземпляр, и замените ниже каждое вхождение pmacontrol.example.com своим именем.

Блок импортирует фрагмент PmaControl. Caddy может автоматически получить публичный сертификат, если имя и проверки ACME доступны. В частной сети используйте доверенный клиентами центр сертификации или собственные файлы: tls /путь/fullchain.pem /путь/private.key. Дайте службе право чтения ключа, не делая его публичным. Файлы в /etc/pmacontrol/frankenphp.d/ сохраняются при обновлениях; созданные пакетом файлы Caddy могут генерироваться заново.

sudo install -d -m 0755 /etc/pmacontrol/frankenphp.d
sudo tee /etc/pmacontrol/frankenphp.d/pmacontrol.example.com.caddyfile >/dev/null <<'CADDY'
pmacontrol.example.com {
    import pmacontrol_app
}
CADDY
(
  set -eu
  validation_dir="$(mktemp -d /tmp/pmacontrol-validation.XXXXXX)"
  trap 'sudo rm -rf -- "$validation_dir"' EXIT
  sudo env HOME="$validation_dir" frankenphp validate     --adapter caddyfile --config /etc/frankenphp/Caddyfile
)
sudo systemctl reload frankenphp
curl -I https://pmacontrol.example.com/fr/user/connection/

7. Использование обратного прокси

Предпочтителен HTTPS с проверкой сертификата между прокси и FrankenPHP. Сохраняйте исходный публичный Host и заменяйте входной X-Forwarded-Proto значением, определённым самим прокси.

Если архитектура требует HTTP к внутреннему серверу, укажите в /etc/pmacontrol/trusted-proxies только IP непосредственно подключённого прокси. Замените 192.0.2.10 в примере; не разрешайте весь Интернет. Пакет обслуживает приложение по HTTP только для разрешённого узла с точным значением X-Forwarded-Proto: https. Остальные запросы перенаправляются. Для применения политики повторно настройте пакет.

sudo tee /etc/pmacontrol/trusted-proxies >/dev/null <<'PROXY'
192.0.2.10
PROXY
sudo chown root:root /etc/pmacontrol/trusted-proxies
sudo chmod 0644 /etc/pmacontrol/trusted-proxies
sudo apt-get install --reinstall pmacontrol

8. Добавление первых серверов MariaDB / MySQL

В интерфейсе добавьте адрес, порт и SQL-учётные данные наблюдаемого сервера, затем проверьте соединение. Локальная база MariaDB PmaControl отделена от наблюдаемых серверов: переносить прикладные базы не требуется.

Создайте отдельную учётную запись мониторинга, ограниченную адресом PmaControl, с правами для выбранных функций. Права на метрики, репликацию, анализ, резервное копирование и администрирование различаются между MariaDB, MySQL и их версиями; не заменяйте их универсальным удалённым root. Включите Performance Schema на целевых серверах, если этого требуют выбранные страницы. SSH необязателен и нужен только соответствующим функциям системного сбора, журналов и резервного копирования.

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

PmaControl в снимках экрана

Десять представлений мониторинга, топологий и инструментов PmaControl. Нажмите на снимок, чтобы открыть его в исходном размере. Снимки сделаны 26 сентября 2026 года.

1. Список серверов

Список серверов, доступность, версии и время последнего сбора данных.

2. Архитектура Galera + ProxySQL

Визуализация VIP, групп ProxySQL и участников кластеров Galera.

3. Оповещения и инциденты

Открытые и закрытые инциденты, уровни важности и фильтры по серверам.

4. Состояние узлов Galera

Участники кластеров, состояние синхронизации, сегменты и версии.

5. Группы хостов и маршрутизация ProxySQL

Группы writer и reader, серверы backend и состояние соединений.

6. Память баз данных

Сравнение буферов и параметров памяти по серверам.

7. Ресурсы PmaControl

Графики соединений, памяти и предупреждений о ресурсах.

8. Репликация MariaDB

Источники, цепочки репликации, версии и соединения SSL.

9. Резервные копии и расписание

История выполнения, место в хранилище и расписание резервного копирования.

10. Использование индексов

Счётчики чтений и доля чтений, обслуживаемых индексами.

9. Файлы, данные и резервное копирование

Пути ниже относятся к пакетному развёртыванию. Сохраняйте локальную базу, /etc/pmacontrol/, данные приложения, сертификаты и данные восстановления доступа. Ключ шифрования приложения входит в конфигурацию: одной SQL-копии недостаточно для восстановления зашифрованных учётных данных.

Используйте резервное копирование MariaDB, обеспечивающее согласованность имеющихся движков хранения. Один экспорт --single-transaction не гарантирует согласованность всех таблиц при нескольких движках. Для копирования файлов или снимка остановите сбор и MariaDB в запланированное окно либо используйте механизм, проверенный для вашего движка и версии. Испытайте восстановление на изолированном экземпляре, прежде чем полагаться на копию.

/usr/share/pmacontrol/                 application
/usr/bin/pmacontrol                    CLI
/etc/pmacontrol/                       configuration
/etc/pmacontrol/frankenphp.d/           operator TLS policy
/etc/pmacontrol/trusted-proxies         immediate trusted proxy peers
/var/lib/pmacontrol/                   persistent application data
/var/lib/mysql/                        local MariaDB data
/var/cache/pmacontrol/tmp/              application cache and logs
/etc/frankenphp/php.d/pmacontrol.ini    packaged PHP settings
/root/pmacontrol-install.env            bootstrap recovery credentials

10. Обновление PmaControl

Перед обновлением подготовьте восстанавливаемую копию данных и конфигурации и прочитайте примечания к версии-кандидату. Post-install применяет миграции и возвращает демоны в предусмотренное состояние; намеренно остановленные задания должны оставаться остановленными. Обычная процедура — обновление пакета, а не git pull в /usr/share/pmacontrol.

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

sudo apt-get update
apt-cache policy pmacontrol
sudo apt-get -s install --only-upgrade pmacontrol
sudo apt-get install --only-upgrade pmacontrol
sudo dpkg --audit
systemctl is-active mariadb frankenphp cron

11. Docker: текущее состояние и варианты развёртывания

Проверено 26 сентября 2026 года: текущий репозиторий не содержит Dockerfile, Compose или ссылки на образ PmaControl для полной поддерживаемой установки. Имеющиеся Docker-файлы относятся к инструментам или тестовым базам. Предлагать docker pull pmacontrol/pmacontrol без опубликованного и проверенного образа было бы неверно.

Пакет APT использует systemd, локальную MariaDB, cron, права файлов и проверки слушающих процессов при запуске. Помещение пакета в обычный PHP-образ не воспроизводит установку. Реализация Docker должна обеспечивать инициализацию и повторные попытки, постоянные тома, секреты, миграции, демоны, проверки состояния и проверенное восстановление.

Уже сейчас можно установить PmaControl в ВМ Debian или Ubuntu по этому руководству и наблюдать за серверами MariaDB / MySQL в Docker, если их SQL-адреса доступны. localhost внутри контейнера означает сам контейнер, а не ВМ PmaControl. Процедура установки самого PmaControl в Docker будет добавлена с образом и воспроизводимыми тестами; её нельзя путать с мониторингом контейнерных баз.

12. Диагностика незавершённой установки

Начните с журналов и состояния пакетов. При ошибке APT проверьте ветку, архитектуру, время, ключ и сеть. При конфликте портов определите службу и выберите место для PmaControl; пакет не должен прерывать работу другого сайта. При ошибке TLS проверьте DNS, проверки ACME, сертификат и права. Если веб работает, но графики устарели, проверьте SQL/SSH, демоны и ошибки сбора.

sudo journalctl -u frankenphp -u mariadb -u cron --since '-30 min' --no-pager
sudo tail -n 100 /var/cache/pmacontrol/tmp/log/error_php.log
sudo tail -n 100 /var/log/apt/term.log
sudo dpkg --audit
sudo ss -ltnp '( sport = :80 or sport = :443 )'
sudo ss -lunp 'sport = :443'

После устранения указанной причины повторите настройку следующими командами. При неудачной ротации демонов может потребоваться sudo runuser -u www-data -- pmacontrol Daemon startAll, но только для восстановления сохранённого состояния этой операции и проверки единственного JSON-результата с ok: true. Не удаляйте ключ шифрования или файл доступа ради новой инициализации.

sudo dpkg --configure -a
sudo apt-get -f install

13. Удаление пакета

Сначала сохраните и проверьте данные, которые хотите оставить. Смоделируйте удаление, затем удалите пакет, если это ваша цель. purge — другая операция, которая не заменяет план сохранения данных. TLS-файлы оператора могут остаться на диске; проверьте сохранённые службы и данные перед повторным использованием машины.

sudo apt-get -s remove pmacontrol
sudo apt-get remove pmacontrol

14. Проверка ввода в эксплуатацию

Пакет настроен, необходимые службы активны.
DNS и сертификат соответствуют; обычный доступ работает без -k.
Данные администратора и webservice безопасно сохранены.
Сервер MariaDB / MySQL проходит проверку соединения.
Сбор создаёт свежие выборки и согласованные графики.
Права, срок хранения и хранилище соответствуют включённым функциям.
Полная резервная копия восстанавливается на изолированном экземпляре.

Источники и объём проверки. Руководство основано на установочных скриптах и документации официального репозитория, индексах APT и пакете 5.4.36-1, просмотренных 26 сентября 2026 года. Подпись индекса проверена. Эта документальная проверка не является новым испытанием установки на каждой из четырёх систем.

Установка PmaControl на Debian и Ubuntu: полное руководство и состояние Docker