跳到主要内容
版本：latest

宝塔面板 API 一键迁移

本文为宝塔面板 API 一键迁移的实操指南，通过「宝塔一键迁移 API 版本」插件，快速实现源服务器与目标服务器间网站、数据库、计划任务的无缝迁移，无需复杂手动配置。

插件安装与目标服务器配置​

1. 安装迁移插件​

登录源服务器宝塔面板，进入左侧菜单栏【软件商店】，搜索并安装【宝塔一键迁移 API 版本】。

在软件商店安装宝塔一键迁移 API 版本

2. 配置目标服务器信息​

打开已安装的迁移插件，填写**目标服务器（迁入端）**的以下信息：

配置项填写要求
面板地址格式：协议（http/https）+ 目标 IP + 面板端口（例：https://192.168.1.100:8888）
API 密钥从目标服务器面板获取：【面板设置】→【API 接口】→ 开启并复制密钥
IP 白名单目标服务器需添加源服务器 IP：【面板设置】→【API 接口】→【添加 IP 白名单】

填写目标服务器面板地址和 API 密钥

在目标服务器开启 API 接口并复制密钥

添加源服务器 IP 至白名单

⚠️ 注意事项：

  1. 面板地址必须包含完整协议和端口，不可省略。
  2. 目标服务器面板版本需 ≥ 6.9.8，否则无法兼容。
  3. 白名单未添加源服务器 IP 将直接导致连接失败。

迁移操作流程​

1. 环境兼容性检测​

填写完目标服务器信息后，点击【下一步】，系统将自动检测目标服务器环境（包括面板版本、依赖组件等）。

若检测提示"环境不完整"，需先根据提示在目标服务器上安装缺失组件，再继续操作。

环境兼容性检测结果

2. 选择迁移内容​

环境检测通过后，进入【迁移内容选择】页面，勾选需要迁移的资源：

  • 网站（含站点配置、文件，可多选）
  • 数据库（含数据、账号权限）
  • 计划任务

选择需要迁移的内容

3. 执行一键迁移​

确认选择后，点击【一键迁移】，系统进入后台传输状态。可关闭插件窗口，不影响传输进度。

迁移任务开始执行

4. 迁移结果验证​

等待迁移完成后，登录目标服务器宝塔面板，逐项核验：

  1. 查看【网站】，确认迁移的站点是否存在，且文件与源服务器一致。
  2. 查看【数据库】，确认数据库实例和数据是否完整。
  3. 查看【计划任务】，确认定时任务配置是否已同步。

目标服务器网站列表验证

目标服务器数据库列表验证

传输过程注意事项​

  1. 迁移在后台运行，关闭插件窗口不影响传输进度。
  2. 传输期间请勿操作目标服务器面板：
    • 不可修改面板端口、重置 API 密钥。
    • 不可删除或修改目标服务器上的同名站点、数据库。
  3. 保持网络稳定：源服务器与目标服务器之间的网络波动可能导致传输失败，建议迁移期间避免占用过多带宽。

常见问题排查​

目标面板连接失败​

目标面板连接失败报错

报错表现：插件提示"目标面板连接失败"。

排查步骤：

  1. 在本地 ping 目标服务器 IP，检查网络连通性（不通则排查防火墙、安全组）。
  2. 核对面板地址：协议、IP、端口是否填写正确（重点检查 https/http 是否混淆）。
  3. 验证 API 密钥：检查目标服务器是否重新生成了密钥，如有则重新复制最新密钥。
  4. 检查面板版本：目标服务器面板版本是否 ≥ 6.9.8，低于则需先升级面板。
  5. 白名单配置：确认目标服务器已添加源服务器 IP（注意区分内网/外网 IP）。
  6. 插件修复：若以上均正常，在源服务器软件商店找到迁移插件，点击【修复】后重试。

传输失败​

传输失败日志示例

通过迁移日志定位问题：进入迁移插件 → 【迁移日志】，查看具体失败原因。

迁移后仅显示默认文件（未同步数据）​

原因：目标服务器已存在同名站点目录或数据库，导致迁移数据未能覆盖。

解决方案：

  1. 登录目标服务器面板，删除同名站点及对应的数据库、配置文件。
  2. 重新执行迁移操作。