升级与回滚
读者：生产环境需要滚动升级 Master 或 Client 的运维人员。
XCTL 支持在线升级 Master 与 Client（套餐全档包含）。升级替换二进制与静态资源，保留数据库、master.yaml、master.env 与管理员凭据。
1. Master 升级
Section titled “1. Master 升级”方式 A：运维菜单（推荐）
Section titled “方式 A：运维菜单（推荐）”在 Master 服务器上：
sudo xctl master# 选择「升级 Master」或对应菜单项或：
sudo bash /path/to/xctl-master-install.sh -upgradedo_upgrade 行为：
- 替换
xctl-master二进制、web/、dl/、migrations/ - 不覆盖
configs/master.yaml、/etc/xctl/master.env、数据库 - 重启
xctl-master.service
方式 B：控制台
Section titled “方式 B：控制台”若控制台 设置 → 升级 已启用，可按页面指引触发（本质调用同上升级逻辑）。
- 备份 MariaDB 与
/etc/xctl/master.env - 阅读 更新日志 是否有破坏性变更
- 低峰期操作；通知团队短暂维护窗口
官方升级脚本不提供自动回滚。若新版本异常：
- 停止服务：
systemctl stop xctl-master - 从备份恢复上一版 tarball 中的
xctl-master与web/ - 若已跑新 migration，需按发布说明处理数据库（通常向前兼容）
- 启动服务并验证
建议在升级前保留上一版 xctlmaster-linux-{arch}-{version}.tar.gz。
2. Client 升级
Section titled “2. Client 升级”Client 二进制来源：
- Master
/dl/xctl-client-linux-{arch}（与 Master 版本对齐） - GitHub
client-latestRelease（Masterdl/缺失时回退）
- 先升级 Master，使
dl/内 Client 为新版本 - 在各节点执行安装脚本 Client 模式或运维 playbook 覆盖二进制
systemctl restart xctl-client- 控制台确认 Host 在线、 配置同步 无异常
分批重启 Client，避免同一条逻辑节点下所有 Host 同时离线。
3. 数据库迁移
Section titled “3. 数据库迁移”Master 启动时若 auto_migrate: true，会应用 migrations/ 新 SQL。升级前备份数据库；跨大版本时阅读 changelog 是否需手工步骤。
4. 注意事项
Section titled “4. 注意事项”- 不要用新安装包覆盖整个
/etc/xctl/master目录，会丢失配置 MWAAS_MASTER_KEY不可变；升级脚本不会重置- WHMCS / 面板插件版本应与 Master API 匹配，必要时同步升级插件
5. 常见问题
Section titled “5. 常见问题”Q：升级后控制台 502？
A：journalctl -u xctl-master 查 migration 或配置错误；检查数据库连通。
Q：Client 版本必须和 Master 完全一致吗？
A：建议 major 版本对齐；过旧 Client 可能不支持新 WS 消息类型。
Q：能否只升级 Client 不升级 Master？
A：短期可以；长期应双端一起升，避免协议与 dl/ 不一致。