宝塔面板整机迁移需同时满足API开放（目标机填源机公网IP白名单）、环境一致（Pure-FTPd、PHP/MySQL/Nginx版本完全相同）、FTP服务可用（端口放行、账号密码正确）三条件，缺一即失败。
宝塔面板用 一键迁移API版本 插件做整机迁移，不是“点一下就完事”，而是依赖两台服务器的 API 开放、环境一致性、FTP 服务三者同时满足——缺一不可，否则卡在「环境检测失败」或「连接被拒绝」。
迁入服务器必须提前开启并配置 API 接口
很多人卡在第一步：只开了 API，但没填对 IP白名单。迁入服务器（目标机）的 API 设置里，IP白名单 必须填迁出服务器（源机）的**公网IP**，不是内网IP，也不是 0.0.0.0。如果源机是阿里云ECS且开了安全组，还要确认该IP没被安全组拦截。接口密钥生成后建议立即复制，重置会失效，且面板不会二次提示。
迁出服务器要装插件，但不能开API
一键迁移API版本 插件只需安装在迁出服务器（源机），它的作用是发起迁移请求，不提供接收能力。迁出服务器**不需要开启自己的API接口**，也不用填任何白名单——这是常见误解。装好插件后，在「设置」里填的是迁入服务器的 面板地址（如 http://123.56.78.90:8888）和 API密钥（来自迁入服务器面板设置页），协议、端口、路径一个字符都不能错。
环境检测失败的三个硬性条件
迁移前自动执行环境检测，以下任一不满足都会中断：
- 两台服务器都必须已安装并启用
Pure-FTPd（不是 vsftpd 或其他 FTP 服务） - PHP 版本号、MySQL 版本号、Nginx/Apache 主版本号必须完全一致（例如都是
php7.4，不能一边是php7.4.33一边是php7.4.30；mysql5.7和mysql8.0直接不兼容） - 宝塔面板版本需为最新稳定版（v8.0+），旧版插件可能调用不到新 API 接口
迁移过程中的文件传输实际走 FTP，不是面板直传
看着是「一键迁移」，底层其实是迁出服务器通过 FTP 连上迁入服务器，把 /www 下的网站、数据库备份、配置文件拉过去再解压还原。所以：
- 迁入服务器的 FTP 账号密码必须能被迁出服务器访问（默认账号是
btftp，密码在 Pure-FTPd 设置页查看） - 如果迁入服务器防火墙开了，得放行 FTP 端口（默认
21）和被动模式端口段（如30000-40000） - 大站点迁移时，FTP 传输中断不会自动续传，得重来——建议先在内网或同地域云服务器间测试通路
最易被忽略的一点：迁移完成后，网站根目录权限 和 数据库用户权限 不一定自动继承。比如旧站用 www 用户跑 PHP，新站可能因用户不存在而 500；或者数据库导入后，宝塔里显示数据库存在，但网站连不上，原因是新服务器的 MySQL 没给对应用户授权 host 为 % 或具体 IP。这些得手动补全，不能只信进度条。
