1Panel V1 到 V2 升级：详细指南与避坑分享

发表于 2025/07/27 更新于 2025/07/27

作者 Dignite

・・ 7 分钟阅读

1Panel 是一款现代化、开源的 Linux 面板，以其简洁的界面和强大的功能深受用户喜爱。随着 V2 版本的发布，带来了架构上的重大更新。本文将为您详细介绍如何将 1Panel 从 V1 平滑升级至 V2，并分享在升级过程中可能遇到的问题及解决方案。

重要提示： 在进行升级操作时，强烈建议通过本地终端使用 SSH 连接到服务器进行操作，避免在浏览器中直接进行，以确保过程的稳定性和安全性。对于大多数单服务器部署的用户，升级为主节点即可。

在开始升级前，务必提前创建系统快照，可以通过 1Panel 控制台或云服务商平台进行，以防止意外情况发生，确保数据安全。当前仅支持 1Panel v1.10.29-lts 及以上版本进行迁移操作。

1. 准备阶段：下载并配置迁移工具

首先，您需要下载 1Panel 官方提供的迁移工具 1panel-migrator。

进入临时目录：在终端中执行以下命令，进入一个临时目录，例如 /tmp：
1 cd /tmp
下载 1panel-migrator 工具：使用 wget 命令从官方发布页面下载适用于您系统架构的 1panel-migrator 工具。例如，对于 Linux ARM64：
1 wget https://gitee.com/fit2cloud-feizhiyun/1panel-migrator/releases/download/v2.0.0/1panel-migrator-linux-arm64
您可以在 1Panel-migrator 的发布页面找到最新版本的下载链接。
添加执行权限并移动到系统路径：下载完成后，需要为该文件添加执行权限，并将其移动到系统路径中，以便随时调用：
1 2 chmod +x 1panel-migrator-linux-arm64 sudo mv 1panel-migrator-linux-arm64 /usr/local/bin/1panel-migrator
（图2：展示下载并移动工具的过程）

2. 核心服务升级

在成功配置 1panel-migrator 工具后，我们将首先升级 1Panel 的核心服务。

执行核心升级命令：在终端中运行以下命令：
1 sudo 1panel-migrator upgrade core
注意事项与确认：在执行过程中，系统会提示一些重要的注意事项，包括：
- 原有 V1 版本的许可证信息将被清除，统一迁移为社区版本。
- 出于兼容性考虑，所有 V1 网站、应用和数据库的备份记录将被清空。
- 计划任务的执行记录不会保留。
- V1 的快照记录无法迁移至 V2。
系统会要求您确认是否继续迁移至 V2 主节点。输入 y 并回车确认。

（图3：展示核心升级过程和成功提示）

待所有步骤执行完毕，您将看到“迁移成功，版本已成功迁移至 V2.0.0”的提示，这表示核心服务已成功升级。

3. 网站服务升级与问题解决

核心服务升级完成后，接下来是网站服务的升级。

尝试执行网站升级命令：继续在终端中执行以下命令：
1 sudo 1panel-migrator upgrade website

Docker 镜像拉取超时报错与解决方案：在执行网站升级命令时，您可能会遇到 Docker 镜像拉取超时的问题，错误信息类似：“Error response from daemon: Get “https://registry-1.docker.io/v2/”: net/http: request canceled while waiting for connection (Client.Timeout exceeded while waiting for connection)” [图4]。

这是由于 Docker 官方镜像仓库在国内访问可能不稳定或速度较慢导致的。解决方法是配置 Docker 镜像加速器。

解决方案步骤：

编辑 Docker 配置文件：使用 vi 或您喜欢的编辑器打开 Docker 的配置文件 /etc/docker/daemon.json：

sudo vi /etc/docker/daemon.json

（图5：展示编辑 daemon.json 文件）

在文件中添加或修改 registry-mirrors 配置，指向 1Panel 提供的镜像加速地址：

{
    "log-driver": "json-file",
    "log-opts": {
        "max-size": "10m",
        "max-file": "3"
    },
    "default-address-pools": [
        {
            "base": "10.0.0.0/8",
            "size": "24"
        }
    ],
    "registry-mirrors": [
        "https://docker.1panel.live"
    ]
}

保存并退出文件（在 vi 中按 Esc，然后输入 :wq! 并回车）。

重载 Docker 配置并重启服务：执行以下命令使配置生效：
1 2 sudo systemctl daemon-reload sudo systemctl restart docker

重新运行网站升级命令：在修复 Docker 镜像加速问题后，再次执行网站升级命令：
1 sudo 1panel-migrator upgrade website
此时，您将看到 Docker 镜像成功拉取并完成后续的网站迁移、OpenResty 升级等操作 [图6, 7]。

（图6, 7：展示网站升级成功的过程）