# 宝塔面板 API 一键迁移

> 通过宝塔面板（BT Panel）「一键迁移 API 版本」插件，快速实现源服务器与目标服务器间网站、数据库、计划任务、SSL 证书的无缝迁移，适用于服务器替换与云间迁移。

原文：[宝塔面板 API 一键迁移](https://docs.bt.cn/practical-tutorials/api-migration)

文档范围：宝塔面板及相关产品（当前文档）。生成时间：2026-09-22。

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

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

### 1. 安装迁移插件

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

![在软件商店安装宝塔一键迁移 API 版本](https://docs.bt.cn/img/practical-tutorials/api-migration/image-20260326092120150.png)

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

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

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

![填写目标服务器面板地址和 API 密钥](https://docs.bt.cn/img/practical-tutorials/api-migration/image-20260326092232752.png)

![在目标服务器开启 API 接口并复制密钥](https://docs.bt.cn/img/practical-tutorials/api-migration/image-20260326154932180.png)

![添加源服务器 IP 至白名单](https://docs.bt.cn/img/practical-tutorials/api-migration/image-20260326155107488.png)

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

## 迁移操作流程

### 1. 环境兼容性检测

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

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

![环境兼容性检测结果](https://docs.bt.cn/img/practical-tutorials/api-migration/image-20260326155251383.png)

### 2. 选择迁移内容

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

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

![选择需要迁移的内容](https://docs.bt.cn/img/practical-tutorials/api-migration/image-20260326160718770.png)

### 3. 执行一键迁移

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

![迁移任务开始执行](https://docs.bt.cn/img/practical-tutorials/api-migration/image-20260326161349699.png)

### 4. 迁移结果验证

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

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

![目标服务器网站列表验证](https://docs.bt.cn/img/practical-tutorials/api-migration/image-20260326163052966.png)

![目标服务器数据库列表验证](https://docs.bt.cn/img/practical-tutorials/api-migration/image-20260326163057563.png)

## 传输过程注意事项

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

## 常见问题排查

### 目标面板连接失败

![目标面板连接失败报错](https://docs.bt.cn/img/practical-tutorials/api-migration/image-20260326160056656.png)

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

排查步骤：

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

### 传输失败

![传输失败日志示例](https://docs.bt.cn/img/practical-tutorials/api-migration/image-20260327091924563.png)

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

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

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

解决方案：

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