Nexus/docs/changelog/2026-06-21-btpanel-monitor-ip-whitelist-auto-repair.md

2026-06-21 宝塔系统监控 IP 白名单自愈

摘要

修复 #/btpanel/monitor（及全部宝塔代理 API）在子机返回 {"status":false,"msg":"IP校验失败..."} 时被当作正常 JSON 展示的问题；遇 IP 白名单失败时自动 SSH 追加中心 IP 并重试一次。

动机

生产验收：GET /api/btpanel/servers/{id}/system/total 对部分已 configured 服务器返回 HTTP 200 + 宝塔错误 JSON，前端「系统概览」卡片直接显示 IP校验失败 对象而非指标。根因：

1. 历史 bootstrap 曾写入 data/api.json，面板实际读 config/api.json，白名单未生效；
2. BtPanelClient 未识别宝塔 status: false 语义。

手动 POST .../bootstrap 可修复（appended_whitelist），但需用户逐台操作。

涉及文件

• server/infrastructure/btpanel/client.py — raise_if_panel_error
• server/application/services/btpanel_service.py — proxy IP 失败自愈 + _repair_ip_whitelist
• frontend/src/pages/btpanel/BtPanelMonitorPage.vue — 失败时清空卡片并 snackbar
• tests/test_btpanel_client.py

迁移 / 重启

• 需部署 API；无需 DB 迁移。
• 已 configured 且 SSH 可达的服务器：首次访问监控/站点等代理接口时自动补白名单。

验证

.venv/bin/pytest tests/test_btpanel_client.py -q
# 生产：对曾报 IP 校验失败的服务器 GET .../system/total 应返回 memTotal/cpuNum 等指标
# 前端：#/btpanel/monitor 选服务器后应显示指标 JSON，失败时红色 snackbar 而非假数据