控制面恢复与元数据排障
本页用于处理控制面不可用、管理 API 异常、CubeMaster 不健康、MySQL / Redis 异常，以及升级后元数据状态漂移等问题。
如果你现在遇到的是鉴权、模板构建或代理入口问题，请优先看对应专题页；本页重点只放在控制面恢复和元数据一致性。
先冻结现场，不要先写入
在没有确认故障层级前，不建议立刻执行高危修复动作。
优先做：
- 保存当前版本、关键配置和时间点
- 记录最近一次变更动作
- 保留
journalctl与/data/log/关键日志 - 暂缓
restoredb、全量清理、整组重装等高风险操作
相关说明：
先做最小只读判断
建议按这个顺序判断：
bash
sudo ./smoke.sh
curl -fsS http://127.0.0.1:19090/healthz
curl -fsS http://127.0.0.1:8089/notify/health
curl -fsS http://127.0.0.1:3000/health
curl -fsS http://127.0.0.1:12088/cubeapi/v1/health快速判断：
19090异常：先看基础服务与节点侧依赖8089异常：优先排查CubeMaster3000异常：优先排查cube-api3000正常但12088异常：更像 Web / 反代问题
安全恢复顺序
控制面恢复建议按依赖层级进行：
- 先确认 MySQL / Redis 可用
- 再恢复
CubeMaster - 再恢复
cube-api - 最后恢复 WebUI / Proxy
不要在上层服务明显不健康时继续往下恢复，否则容易让元数据状态进一步漂移。
如果你已经确认问题更像支撑层或核心控制面进程，可以直接继续看：
元数据一致性怎么查
建议同时从三个视角核对：
控制面视角
重点确认：
CubeMaster是否健康- 节点是否仍能出现在控制面
- 模板与沙箱列表是否还能被正常读取
节点注册视角
重点确认：
/internal/meta/nodes/<node-ip>是否仍能查到节点meta_server_endpoint是否正确- 节点是否在恢复后重新注册成功
只读元数据视角
如需进一步核对，可结合只读元数据命令：
bash
cubecli meta dbs
cubecli meta view --db <db-name> <bucket>先比对，再修复；不要一上来就执行写入类命令。
高频症状与判断建议
症状一：smoke.sh 失败，落在 notify/health 或 3000/health
优先看：
CubeMaster/cube-api服务状态journalctl中的启动错误- MySQL / Redis 是否可用
症状二：Dashboard 能打开，但按钮全失败
先区分是：
- 控制面本身异常
- 还是鉴权 / 反代问题
建议联动：
症状三：节点消失在 /internal/meta
优先看：
- 节点与控制面的连通性
meta_server_endpoint- 节点是否已在恢复后重新注册
症状四：服务恢复了，但模板/副本状态不一致
这通常说明控制面基础恢复了，但业务对象还没完全收敛。
建议继续看：
什么时候才考虑 restoredb 或回滚
更适合考虑这些动作的前提是：
- 已确认元数据确实损坏
- 已有可靠备份
- 当前写路径已冻结
- 恢复顺序和回滚点都明确
否则，优先做只读比对、单服务恢复或版本回滚。
恢复后最小验收
建议至少验证：
CubeMaster、cube-api健康- Dashboard / API 连通
/internal/meta中能查到关键节点- 至少一个模板状态正常
- 至少一个沙箱关键路径可用