1.4 升级与迁移出问题怎么办

先给一个判断

升级和迁移出的问题，九成可以通过“先备份”避免。 1Panel 的升级本身有回滚机制——官方文档明确写了：更新失败时会自动回滚到更新前状态。但前提是你没在升级过程中手动改坏东西。所以这一节的中心思想就一句话：动手之前先快照，出了问题看日志。

升级篇

升级的三种姿势

第三种是认真的。没做备份之前，别点升级按钮。

升级都更新了哪些东西

官方说得很清楚，更新会替换三样东西：

• /usr/local/bin/1panel（主程序二进制）
• /usr/local/bin/1pctl（命令行工具）
• /etc/systemd/system/1panel.service（系统服务）

知道这个有用：如果升级后面板起不来，重点查这三个文件，尤其是 service 文件是否完整。

升级失败怎么办

第一步：看日志，不要猜。

面板内：日志审计 → 系统日志，按时间筛选到升级那个时间点，看报错原文。

命令行：

journalctl -u 1panel.service --no-pager -n 100

第二步：确认是否已自动回滚。

官方机制：更新失败会回滚所有更新内容。所以如果升级后版本号没变，多半是已经回滚了，服务应该还在。

# 看当前版本
1pctl version

# 看服务状态
1pctl status

第三步：如果服务真的起不来了。

# 重启服务
1pctl restart

# 还是不行，看 service 文件是否正常
systemctl status 1panel.service
cat /etc/systemd/system/1panel.service

第四步：终极手段——用快照恢复。

如果你升级前创建了系统快照（下面会讲），这时候就是它发挥作用的时候。

一个真实的坑

升级前没备份，升级后数据库起不来，网站全挂。

回头查日志发现：升级本身成功了，但升级过程中有人顺手改了数据库配置。两个操作叠在一起，分不清是谁的锅。

教训：升级窗口期内，不要同时做任何其他配置变更。要么排队，要么别升级。

快照篇：你唯一的后悔药

系统快照是全量备份 1Panel 产生的数据。官方列出的快照范围：

关键限制（官方明确说明）：创建和同步快照只支持选择第三方账号，不能存本地磁盘。所以你得先在“面板设置 → 备份账号”里配好一个第三方存储（OSS、COS、S3、OneDrive 等都行）。

快照恢复的注意事项

1. 恢复过程中，会自动对恢复前的数据做一次备份，默认路径是 [安装目录]/original_[快照名]；
2. 恢复失败，先看 日志审计 → 系统日志，排查后可以重试，或者回滚到恢复前的版本；
3. 如果以上都不行，手动拿到恢复前的备份文件，手动替换系统数据，然后重启；
4. 服务器迁移场景，把快照传到目标服务器的备份目录下（如服务器磁盘：/opt/1panel/backup/system_snapshot/）。

注意：快照路径里的 /opt 要换成你的实际安装目录。不是所有人装的时候都用默认路径。

迁移篇

场景一：整机迁移

思路很简单：老服务器做快照 → 新服务器装同版本 1Panel → 恢复快照。

步骤：

1. 老服务器：创建系统快照，同步到第三方备份账号；
2. 新服务器：安装同版本的 1Panel（版本不一致可能出问题）；
3. 新服务器：配置同一个备份账号；
4. 在快照列表里找到快照，执行恢复；
5. 验证网站、数据库、应用是否正常。

验证这一步不能省。恢复成功只是“数据回来了”，不代表应用都跑起来了。重点是：网站能不能打开、数据库能不能连、容器是不是都在运行。

场景二：主从节点切换

多节点架构里，主节点挂了，需要把从节点提升为主节点。官方提供了专门的工具 1panel-migrator：

# 从节点升主节点
1panel-migrator promote

# 主节点降为从节点
1panel-migrator demote

前提条件（官方强调）：

• 1panel-migrator 版本 >= v2.0.8 才支持主从切换；
• 升级主节点之前，原主节点必须先配置好主节点备份，并执行一次备份——只有存在备份文件的主节点才支持升级；
• 降级后的从节点必须被其他主节点添加才能使用，不支持独立访问。

场景三：v1 老版本迁移到 v2

官方有专门的 v1 迁移文档和迁移工具。核心原则：按官方文档的步骤一步步来，不要自己发挥。迁移前一定做好快照备份。

具体步骤见 1Panel 官方文档：版本迁移。

版本切换的坑：企业版体验结束后

离线安装包自带企业版全功能体验。试用期结束后，面板不会自动切回社区版，登录页会要求导入许可证。这时候要手动恢复：

1. 打开 1Panel 登录页；
2. 单击右上角恢复社区版；
3. 能上网选在线恢复，内网选离线恢复；
4. 离线恢复需要准备社区版官方安装包（版本不低于当前企业版），上传到 /opt/1panel/tmp/community-restore 目录；
5. 单击确认。

官方特别警告：这个目录里千万别放企业版离线包。放错了，切换会执行完成，但面板仍是企业版，而且账号可能被改成 username、密码被改成 password。万一真放错了，用命令补救：

1pctl update username
1pctl update password

两份清单：照着做，出事概率减半

升级前检查清单

迁移后验证清单

为什么强调逐项验证：恢复成功只表示“数据回来了”，不等于“业务起来了”。数据库容器可能起不来、网站配置可能少了一段、证书可能没跟着过来。不验证的迁移，等于没做完。

本节要点

• 升级有自动回滚机制，但不备份就升级是在赌；
• 升级失败先看系统日志，版本号没变多半已回滚；
• 快照是全量备份，只能存第三方账号，本地磁盘不行；
• 迁移的核心是“老服务器快照 → 新服务器同版本 → 恢复 → 逐项验证”；
• 主从切换用 1panel-migrator promote/demote，版本要求 v2.0.8+；
• 升级窗口期内不要做其他配置变更。

备份账号和快照的详细配置见 1Panel 官方文档：面板设置。

下一章：装好了、能进了，接下来就是建网站。第二章我们处理所有“网站打不开”的问题——502、504、证书、跨域，一个一个来。