宝塔一键迁移依赖目标服务器启用的迁移API服务及有效密钥。需确认迁移插件已安装启用、API密钥已生成并启用服务、源服务器公网IP在API白名单中、API端点可直连验证，且两端面板版本兼容（建议均升级至8.5.3）。
检查目标服务器是否启用迁移API并生成有效密钥
宝塔一键迁移不是单纯走SSH，它依赖目标服务器上运行的迁移服务API（/api/panel/move），该服务由宝塔迁移插件提供。如果没启用或密钥失效，前端显示“连接服务器失败”，但错误日志里往往不报具体原因。
实操建议：
- 登录目标服务器，在终端执行
bt install plugin move确保迁移插件已安装且状态为“已启用” - 进入宝塔面板 →「软件商店」→ 找到「一键迁移」插件 → 点击「设置」→ 查看「API密钥」是否已生成；若为空，点击「重新生成」
- 密钥生成后不会自动生效，需手动点击「启用API服务」开关（部分旧版面板需重启迁移服务：
systemctl restart bt-move）
确认源服务器IP是否在目标端的API白名单中
迁移API默认开启IP白名单校验，即使SSH能通、面板能访问，只要源服务器IP不在白名单里，请求直接被拒绝，表现就是“连接失败”。这个白名单和宝塔面板登录白名单是两套逻辑，容易混淆。
实操建议：
- 在目标服务器的迁移插件设置页，找到「API白名单」输入框
- 填入源服务器的**公网出口IP**（不是内网IP，也不是NAT后的IP），多个用英文逗号分隔，例如：
203.208.60.1,119.123.45.67 - 注意：某些云厂商（如阿里云、腾讯云）的ECS默认使用SNAT，源IP可能是云平台分配的共享出口IP，建议在源服务器上执行
curl ifconfig.me确认真实出口IP - 保存后无需重启，但白名单变更有约30秒缓存延迟，稍等再试
验证API端点是否可被源服务器直连（绕过面板UI）
面板UI的“测试连接”按钮有时会因前端JS异常或跨域策略静默失败，无法反映真实网络层问题。直接用 curl 模拟请求，能快速定位是认证问题、网络问题还是服务未启动。
实操建议：
- 在源服务器终端执行（替换为目标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），不能用 http；若未启用SSL，强制用 http，否则 curl 会因证书错误失败
新版面板（≥8.5）对迁移API的兼容性限制
2025年底起，宝塔8.5+ 版本将迁移API的认证方式从简单 access_key 升级为带时间戳和签名的 HMAC 认证，旧版源面板（如8.3或手动覆盖安装的非标准包）发来的请求会被直接拒收，现象仍是“连接服务器失败”，但目标端日志里会出现 invalid signature 提示。
实操建议：
- 两端面板都执行
bt update升级到最新稳定版（截至2026年4月为8.5.3） - 避免“下载安装包覆盖安装”——这种操作常导致
/www/server/panel/class/move.py文件残留旧逻辑，应统一用bt update或重装插件：bt uninstall plugin move && bt install plugin move - 如果必须跨版本迁移（如源为8.3），不要用一键迁移UI，改用
scp+bt backup手动导出站点+数据库，再在目标端导入
