宝塔一键迁移失败90%因目标端/api/panel/move接口未运行，需确认迁移插件已安装启用、API密钥有效、源服务器公网IP在白名单中，并用curl直连验证真实连通性。
宝塔一键迁移失败，90%是因为目标端的 /api/panel/move 接口压根没跑起来——它不依赖 SSH 连通性，也不看面板是否能登录，只认迁移插件服务本身是否在监听、密钥是否有效、源 IP 是否被白名单放行。
确认目标服务器已安装并启用「一键迁移」插件
迁移不是面板原生功能，而是由独立插件提供服务。如果插件未安装或被禁用，/api/panel/move 路径会直接返回 404 或空响应，前端却只显示“连接服务器失败”，毫无提示。
- 登录目标服务器终端，执行
bt install plugin move，确保插件已安装且状态为“已启用” - 进宝塔 →「软件商店」→ 搜索「一键迁移」→ 点击「设置」→ 查看「API密钥」是否非空；若为空，点「重新生成」
- 密钥生成后必须手动点击「启用API服务」开关（旧版还需执行
systemctl restart bt-move）
检查 API 白名单是否填了源服务器的真实出口IP
迁移 API 的白名单和面板登录白名单是两套逻辑，填错 IP 是最隐蔽的失败原因。即使 SSH 能通、面板能打开、curl 测试也返回 200，只要白名单里没写对源 IP，请求就会被静默拒绝（返回 403 或空体）。
- 在目标端迁移插件设置页找到「API白名单」输入框
- 填入源服务器的**公网出口IP**，不是内网 IP，也不是云厂商 NAT 后的私有 IP；可用
curl ifconfig.me在源服务器上确认 - 多个 IP 用英文逗号分隔，例如：
203.208.60.1,119.123.45.67 - 保存后有约 30 秒缓存延迟，别立刻重试
绕过面板 UI，用 curl 直连验证真实连通性
面板上的“测试连接”按钮容易因前端 JS 错误、跨域策略或证书校验失败而静默失败，根本看不出是网络不通、密钥错误还是服务宕机。
- 在源服务器终端执行（替换为目标 IP、端口、密钥）：
curl -X POST "https://目标IP:8888/api/panel/move?access_key=your_access_key_here" -H "Content-Type: application/json" -d '{"action":"test"}' - 预期返回：
{"status":true,"msg":"success"} - 若返回 403 或空响应 → 白名单或密钥错误；若超时或
connection refused→ 服务未运行或端口被防火墙拦截 - 注意：目标端若启用了 SSL，必须用
https+ 面板端口（如 8888）；未启用 SSL 则必须用http，否则 curl 因证书错误失败
最容易被忽略的是：迁移插件服务（bt-move）和面板主进程是分离的，重启面板不会自动拉起它；密钥重新生成后，旧密钥不会立即失效，但白名单修改后有缓存延迟；云服务器的真实出口 IP 往往和你认为的那个不一样——这些点卡住时，日志里通常什么也不写。
