本指南介绍如何部署 PmaControl 以监控 MariaDB / MySQL 服务器，并确认界面、本地数据库和数据采集正常运行。

当前安装方式是项目签名 APT 仓库提供的 pmacontrol 软件包。它安装 MariaDB、RocksDB 插件、PHP CLI、FrankenPHP 及应用依赖，同时初始化数据库、账户、定时任务和 Web 配置。使用专用主机或虚拟机可以避免与现有服务发生冲突。

一条命令完成安装

在运行 Debian 12/13 或 Ubuntu 24.04/26.04 的专用 amd64 主机上，在终端执行以下命令。脚本会检查操作系统和签名仓库密钥，然后安装 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 章节

截至 2026 年 9 月 26 日，四个发行分支均提供 5.4.36-1 软件包。安装时以 apt-cache policy pmacontrol 显示的可用版本为准。开发分支可能比已发布的软件包更新。本流程不涵盖 ARM64 软件包及较旧的 Ubuntu 版本。

2. 准备主机和网络

准备管理员权限、可用的 DNS、同步的系统时钟和持久化存储。对于小型基础设施，2～4 个 vCPU、4～8 GiB 内存和 40 GiB SSD 可作为初始容量估算，并非保证可用的最低配置。数据量取决于服务器数量、指标、保留周期及备份。启用备份时应为备份安排独立存储。

允许授权用户访问入站 TCP 443，允许重定向及必要的 ACME 验证使用 TCP 80。UDP 443 用于 HTTP/3，客户端可不使用它。需要允许访问软件仓库的出站 HTTPS、访问自有服务的 DNS/NTP、访问被监控服务器实际端口的 SQL，以及仅在相应功能需要时使用 SSH 22。本地数据库无需暴露到互联网。

安装前执行以下检查。如果 /var/lib/mysql 尚不存在，请检查将来承载该目录的文件系统空间。Web 端口必须可用：软件包会拒绝其他程序占用端口的情况，不会自动停用 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 仅为此仓库添加密钥，显示候选版本，并在正式安装前进行模拟。模拟时检查新增软件包和其他变化。后续命令在 sudo -i 打开的 root shell 中执行。

2026 年 9 月 26 日核实的密钥指纹为 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 命令块：24.04 自动选择 noble，26.04 自动选择 resolute。保留已配置的 Ubuntu 官方仓库及其正确发行代号。PmaControl 仓库提供软件包和所需依赖；不要在 Ubuntu 主机上将 noble 替换为 trixie。

执行 apt-get install pmacontrol 后，不要再次运行 install.sh，不要手工创建数据库，也不要添加第二套 Apache/PHP-FPM。软件包安装后脚本已经完成初始化。命令行 PHP 与 FrankenPHP 内嵌 PHP 是不同的运行环境：仅运行 php -v 不能验证 Web 运行环境。

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 提供的片段。主机名和 ACME 验证可达时，Caddy 可以自动申请公共证书。私有网络可使用客户端信任的证书颁发机构，或通过 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. 使用反向代理

优先在代理与 FrankenPHP 之间使用验证证书的 HTTPS 连接。保留原始公共 Host，并将收到的 X-Forwarded-Proto 替换为代理自行确定的值。

若架构要求使用 HTTP 上游，只在 /etc/pmacontrol/trusted-proxies 中填写直接连接到实例的代理 IP。替换示例中的 192.0.2.10，不要允许整个互联网。仅当直接对端在允许列表中且 X-Forwarded-Proto 精确为 https 时，软件包才通过 HTTP 提供应用；其他请求会重定向。重新配置软件包以应用此策略。

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 凭据，然后测试连接。PmaControl 的本地 MariaDB 数据库独立于被监控服务器，不需要迁移业务数据库。

创建专用监控账户，将来源限制为 PmaControl 地址，并授予所选功能需要的权限。指标、复制、分析、备份及管理的权限因 MariaDB、MySQL 和版本而异，不应以通用远程 root 账户代替权限配置。如果所选视图需要 Performance Schema，请在目标服务器上启用。SSH 是可选的，仅用于需要它的系统采集、日志或备份功能。

经过数个采集周期后，检查最新样本时间、图表和拓扑。登录页可访问并不能证明指标是最新的。还应检查界面中的错误和活动任务；不要忽略有意停用的功能而启用所有守护进程。

PmaControl 界面截图

通过十个视图了解 PmaControl 的监控、拓扑和工具。点击截图可查看原始尺寸。截图拍摄于 2026 年 9 月 26 日。

1. 服务器列表

服务器清单、可用性、版本和最近一次采集时间。

2. Galera + ProxySQL 架构

展示 VIP、ProxySQL 分组和 Galera 集群成员。

3. 告警与事件

查看未解决和已解决的事件、严重级别及按服务器筛选的结果。

4. Galera 节点状态

集群成员、同步状态、分段和版本。

5. ProxySQL 主机组与路由

writer 和 reader 分组、后端服务器及连接状态。

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

升级前准备可恢复的数据和配置备份，并阅读候选版本说明。安装后脚本应用迁移并恢复守护进程的预期状态；有意停止的任务应保持停止。正常流程是升级软件包，而不是在 /usr/share/pmacontrol 中执行 git pull。

升级后重新执行第 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：当前状态和部署选择

2026 年 9 月 26 日核实的状态：当前仓库未提供用于完整受支持安装的 Dockerfile、Compose 文件或 PmaControl 镜像引用。现有 Docker 文件用于工具或测试数据库。没有已发布且已验证的镜像时，建议执行 docker pull pmacontrol/pmacontrol 会产生误导。

APT 软件包依赖 systemd、本地 MariaDB、cron、文件权限及启动时的监听端口检查。把它放进通用 PHP 镜像并不能重现这套安装。Docker 适配必须处理初始化和重试、持久卷、密钥、迁移、守护进程、健康检查以及经过测试的恢复流程。

目前可按本指南在 Debian 或 Ubuntu 虚拟机中安装 PmaControl，并监控 Docker 中运行的 MariaDB / MySQL，前提是其 SQL 地址可达。容器中的 localhost 指容器自身，而不是 PmaControl 虚拟机。PmaControl 本身的 Docker 安装流程将随镜像和可复现测试一同提供，不应将它与监控容器化数据库混为一谈。

12. 排查未完成的安装

先检查日志和软件包状态。APT 出错时，检查发行代号、架构、时间、密钥和网络。端口冲突时，识别占用服务并确定 PmaControl 的部署位置；软件包不应中断其他网站。TLS 出错时，检查 DNS、验证挑战、证书和权限。Web 正常但图表过旧时，检查 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，但仅用于恢复该次操作保存的状态，并核实只有一个 ok: true 的 JSON 结果。不要删除加密密钥或凭据文件来强制重新初始化。

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 服务器通过连接测试。
采集产生近期样本和一致的图表。
权限、保留周期和存储符合已启用功能的需要。
完整备份可在隔离实例上恢复。

来源与核实范围。本指南依据官方仓库的安装脚本和文档，以及 2026 年 9 月 26 日查看的 APT 索引和 5.4.36-1 软件包编写。索引签名已验证。本次文档核实不代表在四种发行版上分别重新进行了安装测试。

在 Debian 和 Ubuntu 上安装 PmaControl：完整指南与 Docker 现状