---
name: session-20260716-1
description: 2026-07-16 第1次会话 — 宝塔API返回HTML错误排查（IP白名单变更）
metadata:
  type: session
  date: 2026-07-16
  sessionNumber: 1
  startTime: 2026-07-16T00:00:00+08:00
---

# 2026-07-16 第1次会话

## 会话摘要
排查 `/api/rules` 接口报错问题，确认根因是 10.1.1.170 出公网 IP 发生变化，宝塔面板白名单中仍是旧 IP `183.192.136.97`，导致宝塔拒绝请求返回 HTML 登录页。用户更新白名单后解决。

## 关键操作

### 1. 前端打包命令确认
- **做了什么**: 查看了 `nginx-manager-frontend/package.json`，确认打包命令为 `npm run build`（执行 `vite build`）
- **结果**: 无单独的 prod 命令，`build` 默认即生产模式打包，输出到 `dist/` 目录

### 2. 宝塔API /api/rules 报错排查
- **现象**: 前端访问 `https://gw.server.zgitm.com/api/rules` 报错:
  ```
  获取转发规则失败: 宝塔API请求失败: Could not extract response: 
  no suitable HttpMessageConverter found for response type 
  [java.util.Map<java.lang.String, java.lang.Object>] 
  and content type [text/html;charset=utf-8]
  ```
- **调用链路**: Vue前端 → Gateway → Java后端(10.1.1.170:4002) → btRestTemplate → 宝塔面板(101.132.183.138:18888) → 返回 text/html 而非 JSON
- **排查**: 阅读了 `BTPanelApiClient.java`、`ForwardingRuleService.java`、`ForwardingRuleController.java`、`RestTemplateConfig.java`、`application.yml`，确认代码逻辑没问题
- **根因**: 10.1.1.170 出公网 IP 从 `183.192.136.97` 变成了新 IP，宝塔面板白名单拦截请求，返回 HTML 登录页
- **解决**: 用户更新宝塔面板 IP 白名单后恢复正常

### 3. 可能原因分析（按可能性排序）
| 排名 | 原因 | 说明 |
|------|------|------|
| 1 | 宝塔面板服务挂了 | 138 上的宝塔面板进程崩溃，nginx 返回 HTML 错误页 |
| 2 | API Key 过期/失效 | 宝塔返回登录页 HTML |
| **3** | **IP 白名单变化** ✅ | **确认为此原因** |
| 4 | 宝塔面板端口变更 | 138:18888 端口改了 |

## 重要信息

### 当前架构（无变化）
| 组件 | 机器 | 端口 | 说明 |
|------|------|------|------|
| Vue 前端 | 10.1.1.170 Docker | 3002 | Nginx转发管理/SSL/DNS |
| Java 后端 | 10.1.1.170 Docker | 4002 | 宝塔API接入 + 阿里云DNS |
| DNS Python API | 101.132.183.138 | 32210 | 阿里云DNS解析 |
| 宝塔面板 | 101.132.183.138 | 18888 | Nginx反代管理（API Key: ahv5RRcYm3Vi2PzEFvqYsZvsS8LeGkYp） |
| MySQL | 10.1.1.122 | 3306 | DNS审计 + 证书通知配置 |

### 宝塔面板连接信息
- 面板地址: https://101.132.183.138:18888
- API Key: ahv5RRcYm3Vi2PzEFvqYsZvsS8LeGkYp
- ⚠️ IP 白名单需要与 10.1.1.170 实际出公网 IP 保持一致

## 改进建议
- [ ] 考虑添加健康检查端点，主动监控宝塔 API 连通性
- [ ] 考虑在 `BTPanelApiClient` 中增加响应 Content-Type 检测，当返回 HTML 时给出更友好的错误提示（而非 `HttpMessageConverter` 的底层错误）