维护 PmaControl Commercial 分支：升级、回滚与最佳实践

PmaControl 是基于 Git 的部署

PmaControl 不以 .deb 或 .rpm 包的形式分发。它是基于 Git 的部署：你克隆仓库，安装 Composer 依赖，运行安装脚本，它就投入生产了。

git clone -b commercial https://github.com/pmacontrol/pmacontrol.git /srv/www/pmacontrol
cd /srv/www/pmacontrol
composer install --no-dev
./install.sh

这种模式有优势（快速更新、便于回滚、无需包管理器），也有劣势（没有系统依赖的自动管理、没有标准化的安装后脚本）。本指南涵盖日常维护。

版本追踪

PmaControl 将版本信息存储在站点配置文件中：

// configuration/site.config.php
define('SITE_VERSION', '3.2.1');
define('SITE_LAST_UPDATE', '2026-04-01 14:30:00');

这些常量在安装（install.sh）过程中会自动更新。你可以通过以下方式检查它们：

• 通过 Web 界面："关于"页面或页脚
• 通过 CLI：grep SITE_VERSION configuration/site.config.php
• 通过 API：GET /api/v1/status 返回版本信息

在任何更新之前，记下当前版本：

cd /srv/www/pmacontrol
grep -E 'SITE_VERSION|SITE_LAST_UPDATE' configuration/site.config.php

升级前检查清单

在启动更新之前，完成以下完整检查清单：

1. 备份数据库

mysqldump --single-transaction --routines --triggers \
  -u pmacontrol -p pmacontrol > /backup/pmacontrol_$(date +%Y%m%d_%H%M%S).sql

--single-transaction 参数至关重要：它保证在不锁表的情况下获得一致的备份（InnoDB/RocksDB）。

验证转储大小：

ls -lh /backup/pmacontrol_*.sql

空的或异常小的转储文件表示存在问题。

2. 备份配置

cp -r /srv/www/pmacontrol/configuration/ /backup/pmacontrol_config_$(date +%Y%m%d)/

配置文件是最关键的：db.config.ini.php（凭据）、telegram.php、acl.config.ini、site.config.php。升级不应修改它们，但人为错误发生得很快。

3. 记录当前版本和提交

cd /srv/www/pmacontrol
git log --oneline -1
# fe0911d (HEAD -> commercial) Fix: replication display for MySQL 8.4

grep SITE_VERSION configuration/site.config.php
# define('SITE_VERSION', '3.2.1');

保存提交哈希值（此处为 fe0911d）——这是你的回滚点。

4. 检查 Git 状态

git status

如果存在未提交的本地修改，现在就做决定：提交它们、暂存它们或丢弃它们。带有本地修改的 git pull 可能产生冲突。

# 如果修改需要保留
git stash save "pre-upgrade $(date +%Y%m%d)"

# 如果需要丢弃
git checkout -- .

5. 检查磁盘空间

df -h /srv/www/pmacontrol/
df -h /var/lib/mysql/

升级和迁移可能需要临时空间。确保两个分区都有至少 20% 的可用空间。

升级流程

步骤 1：获取更改

cd /srv/www/pmacontrol
git fetch origin commercial

在合并之前，检查有哪些更改：

git log --oneline HEAD..origin/commercial

这将列出你的版本和最新版本之间的所有提交。阅读提交信息以识别：

• 数据库模式更改
• 配置修改
• 添加或修改的 Composer 依赖
• 标记的破坏性更改

步骤 2：应用更新

git pull origin commercial

如果出现冲突，几乎总是在配置文件中。永远不要通过盲目接受"theirs"来解决冲突——需要手动验证。

步骤 3：更新依赖

composer install --no-dev

composer install（不带 update）使用仓库的 composer.lock，这保证了与开发团队相同的版本。永远不要在生产环境中使用 composer update——它可能拉取未经测试的版本。

验证安装是否成功：

# 检查错误
echo $?
# 应返回 0

# 检查 vendor 目录
ls -la vendor/autoload.php

步骤 4：检查配置更改

将示例文件与当前配置进行比较：

diff -r config_sample/ configuration/ --brief

如果 config_sample/ 中出现新文件而 configuration/ 中不存在，这些是需要集成的新配置：

# 列出 config_sample 中的新文件
for f in config_sample/*; do
    base=$(basename "$f")
    if [ ! -f "configuration/$base" ]; then
        echo "新增: $base — 需要复制和配置"
    fi
done

对于每个新文件：

cp config_sample/new_config.php configuration/new_config.php
# 编辑并调整值以适应你的环境

步骤 5：运行迁移

./install.sh

install.sh 脚本处理数据库模式迁移。它会：

1. 检测当前模式版本
2. 按顺序应用缺失的迁移
3. 更新 SITE_VERSION 和 SITE_LAST_UPDATE

建议手动审查：在运行 install.sh 之前，检查迁移文件：

# 列出迁移文件
ls -la data/migrations/ 2>/dev/null || ls -la install/migrations/ 2>/dev/null

如果迁移包含对大表（如 ts_value_general_int）的 ALTER TABLE，请规划更长的维护窗口。

升级后检查清单

1. 重启服务

./glial control service

此命令重启采集和处理周期。验证它是否未返回错误。

2. 验证定时任务

crontab -l -u www-data

验证三个基本定时任务是否存在：

* * * * * cd /srv/www/pmacontrol && ./glial agent check_daemon >> /tmp/pmacontrol_agent.log 2>&1
* * * * * cd /srv/www/pmacontrol && ./monitor_mysql.sh >> /tmp/pmacontrol_monitor.log 2>&1
0 */4 * * * cd /srv/www/pmacontrol && ./glial control service >> /tmp/pmacontrol_control.log 2>&1

3. 检查错误日志

# PHP 日志
tail -20 /var/log/apache2/error.log

# PmaControl 日志
tail -20 /tmp/pmacontrol_agent.log
tail -20 /tmp/pmacontrol_monitor.log
tail -20 /tmp/pmacontrol_control.log

查找致命错误、类缺失警告、数据库错误。成功的升级不应产生新的错误。

4. 验证 Web 访问

在浏览器中打开 PmaControl 并验证：

• 登录页面正常工作
• 主仪表板加载
• 服务器列表显示
• 可以访问单个服务器
• 从库页面正常工作（如适用）
• Dot3 拓扑加载

5. 验证指标

等待 5 分钟（一个完整的采集周期），然后验证：

# agent 是否在采集？
./glial agent check_daemon

# 数据是否到达？
mysql -u pmacontrol -p pmacontrol -e "
SELECT server_id, MAX(timestamp) as last_data
FROM ts_value_general_int
GROUP BY server_id
HAVING last_data < NOW() - INTERVAL 5 MINUTE;
"

如果此查询返回结果，说明某些服务器不再接收数据——需要调查。

6. 验证 Dot3 和拓扑

./glial dot3 generate

验证拓扑重新生成时没有错误，且 Web 界面中的图表一致。

回滚流程

如果出现问题，以下是回滚方法。

代码回滚

cd /srv/www/pmacontrol
git checkout <previous-commit-hash>
composer install --no-dev

例如，如果升级前的提交是 fe0911d：

git checkout fe0911d
composer install --no-dev

数据库回滚（如果模式已更改）

如果 install.sh 修改了模式，你需要恢复备份：

mysql -u root -p pmacontrol < /backup/pmacontrol_20260413_143000.sql

警告：此操作会覆盖备份以来采集的所有数据。如果升级发生在 2 小时前，你将丢失 2 小时的指标数据。这就是为什么升级应该安排在维护窗口期间。

配置回滚

cp /backup/pmacontrol_config_20260413/* /srv/www/pmacontrol/configuration/

回滚后操作

./glial control service
# 检查日志
tail -20 /tmp/pmacontrol_agent.log
# 验证 Web 访问
curl -s -o /dev/null -w "%{http_code}" https://pmacontrol.example.com/
# 应返回 200

Composer 依赖管理

理解锁文件

composer.lock 文件在仓库中受版本控制。它保证所有人使用完全相同的依赖版本。当 composer.lock 在拉取中发生变化时：

# 查看依赖更改
git diff HEAD~1 composer.lock | grep '"name"'

检查破坏性更改

如果一个主要依赖发生变化（例如 Glial 框架从 2.x 升级到 3.x），这是一个有风险的更改。检查该依赖的 CHANGELOG：

# 列出已更新的依赖
composer show --latest --outdated

永远不要在生产环境中 composer update

# 不要这样做 — 拉取最新可能的版本
composer update

# 应该这样做 — 安装锁文件中的确切版本
composer install --no-dev

数据库迁移

工作原理

install.sh 按顺序执行迁移。每个迁移都是幂等的——它首先检查修改是否已经应用：

-- 典型迁移示例
-- 在添加列之前检查列是否存在
SET @exist := (SELECT COUNT(*) FROM information_schema.COLUMNS
               WHERE TABLE_SCHEMA = 'pmacontrol'
               AND TABLE_NAME = 'mysql_server'
               AND COLUMN_NAME = 'new_column');

SET @sql = IF(@exist = 0,
    'ALTER TABLE mysql_server ADD COLUMN new_column VARCHAR(255) DEFAULT NULL',
    'SELECT "Column already exists"');
PREPARE stmt FROM @sql;
EXECUTE stmt;

高风险迁移

某些迁移比其他迁移风险更高：

对于大表（如 ts_value_general_int 可能有数 GB），ADD INDEX 可能需要数分钟甚至数小时。请做好相应规划。

建议手动审查

在运行 install.sh 之前，阅读迁移文件以了解将要修改什么。如果某个迁移看起来有风险（对数 GB 的表执行 ALTER TABLE），请先在测试环境中测试。

最佳实践

1. 测试环境

维护一个复制生产环境的测试环境。升级先在测试环境中进行测试，然后再应用到生产环境：

1. 测试环境: git pull -> composer install -> install.sh -> 验证
2. 等待 24 小时 — 观察日志
3. 生产环境: 相同流程

测试环境不需要监控与生产环境一样多的服务器。5-10 台 MariaDB / MySQL 服务器足以验证正常运行。

2. 计划维护窗口

永远不要在周五下午 5 点进行升级。计划时间为：

• 周二或周三：一周中间，团队可用
• 上午：有一整天时间来发现问题
• 非高峰时段：不在应用部署或夜间批处理期间

3. 沟通

升级前通知团队：

主题: PmaControl 维护 — 周二 4月13日 09:00-10:00

PmaControl 实例将从版本 3.2.1 更新到 3.3.0。
维护期间（约 30 分钟）：
- 仪表板可能暂时不可用
- 指标采集将中断（自动补采）
- Telegram 告警将暂停后恢复

联系人: dba@company.com

4. 升级后验证 Dot3 + 指标

这是最重要的冒烟测试。如果指标正常到达且拓扑正确，则升级成功。如果两者中的任何一个不工作，则需要调查。

5. 保持升级历史

维护一个简单的文件，记录已执行的升级：

2026-04-13 09:15 | 3.2.1 -> 3.3.0 | fe0911d -> a1b2c3d | 成功
2026-03-15 10:00 | 3.1.0 -> 3.2.1 | 1234abc -> fe0911d | 成功 — ts_value 迁移较慢（45分钟）
2026-02-01 08:30 | 3.0.5 -> 3.1.0 | 9876def -> 1234abc | 回滚 — Listener 中的 bug #342

6. 成熟后自动化

在完成 5-10 次无故障的手动升级后，你可以用脚本自动化：

#!/bin/bash
# upgrade_pmacontrol.sh
set -euo pipefail

BACKUP_DIR="/backup/pmacontrol/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

# 备份
mysqldump --single-transaction -u pmacontrol -p"$DB_PASS" pmacontrol > "$BACKUP_DIR/db.sql"
cp -r /srv/www/pmacontrol/configuration/ "$BACKUP_DIR/config/"
git -C /srv/www/pmacontrol log --oneline -1 > "$BACKUP_DIR/version.txt"

# 升级
cd /srv/www/pmacontrol
git pull origin commercial
composer install --no-dev
./install.sh

# 验证
./glial control service
curl -s -o /dev/null -w "%{http_code}" https://pmacontrol.example.com/ | grep -q 200

echo "升级成功"

但始终保留手动回滚的能力。

常见错误

升级后 "Class not found"

症状：日志中出现 PHP 错误 Class 'Xyz' not found。

原因：拉取后未运行 composer install，或未重新生成自动加载器。

解决方案：

composer install --no-dev
composer dump-autoload

迁移错误 "Table already exists"

症状：install.sh 失败，提示 Table 'xyz' already exists。

原因：迁移不是幂等的（迁移脚本中的 bug）。

解决方案：手动检查表/列是否存在，必要时跳过该迁移。向 PmaControl 团队报告此 bug。

配置中的 Git 冲突

症状：git pull 因 configuration/ 中的冲突而失败。

原因：你修改了一个同样在上游被修改的配置文件。

解决方案：

# 保存你的版本
cp configuration/problematic_file.php /tmp/

# 接受上游版本
git checkout --theirs configuration/problematic_file.php
git add configuration/problematic_file.php

# 手动重新应用你的修改
# 比较 /tmp/problematic_file.php 与上游版本

丢失的 Stash

症状：你在升级前执行了 git stash，但找不到你的修改。

解决方案：

git stash list
# stash@{0}: On commercial: pre-upgrade 20260413

git stash pop stash@{0}

结论

在生产环境中维护 PmaControl 是一个可预测的过程，只要你遵循流程：备份、拉取、composer install、install.sh、验证。Git 模式使升级和回滚快速，但需要在配置管理和备份方面保持严谨。

成功的关键：一个测试环境、一个计划的维护窗口、与团队的清晰沟通以及每次升级后的系统性验证。遵循这些实践，PmaControl 的升级就会成为一项日常操作——而非压力的来源。