Portabase数据库恢复教程：如何从备份快照快速找回丢失的数据

Portabase是一款开源的数据库备份与恢复工具，支持 PostgreSQL、MySQL、MariaDB、MsSQL、Firebird、SQLite、MongoDB、Redis 和 Docker Volume 等引擎。本教程带你从零开始，使用 Portabase 的**数据库恢复（Restore）**功能，从任意一份历史备份快照中快速找回丢失的数据，全程只需几次点击，无需手写任何恢复命令。

一、为什么需要 Portabase 数据库恢复功能？

误删表、错误执行 UPDATE/DELETE、磁盘故障……这些事故每天都在发生。传统的数据库恢复需要人工敲pg_restore、mysqldump等命令，还要确认备份文件完好。Portabase 把整个过程产品化了：

• ✅图形化一键恢复：在网页上点一下 Restore，后台自动调度 Agent 执行恢复
• ✅可视化进度追踪：恢复状态（waiting / ongoing / success / failed）实时刷新，附带完整执行日志
• ✅快照完整性校验：Portabase 会定期检查备份文件是否真实存在于存储端，文件丢失会提前标记为missing，避免你"恢复一个不存在的快照"
• ✅失败可重试：恢复失败后可以查看日志定位原因，并一键重新排队执行
• ✅多数据库批量恢复：一次操作为项目内多个数据库恢复最新可用快照

二、恢复前提：先准备好这 3 样东西

在动手之前，请确认以下条件（相关说明见 README.md）：

1. 已连接 Agent 的数据库：Portabase 通过部署在数据库服务器上的 Agent 执行实际恢复操作
2. 至少一份状态为success的备份：只有成功的备份快照才允许恢复
3. 备份文件仍在存储端：备份可能同时保存在本地、S3、Google Drive 等多个存储渠道，恢复时你可以选择从哪个存储位置读取文件

💡 注意：Redis 和 Valkey 只支持备份、不支持恢复，Portabase 界面会自动隐藏它们的 Restore 按钮。

三、数据库恢复五步操作指南

步骤 1：进入数据库详情页

登录 Portabase 仪表盘后，依次进入Projects → 选择项目 → 选择数据库，打开数据库详情页面（对应源码 database 详情页/dashboard/(organization)/projects/[projectId]/database/[databaseId]/page.tsx)）。

页面下方有两个标签页：Backup（备份列表）和Restoration（恢复记录），标签页切换逻辑见 database-tabs.tsx。

步骤 2：找到正确的备份快照

在Backup标签页的列表中，每个备份快照都会显示创建时间、状态和存储位置。用筛选器把状态过滤为Available（可用），找到事故发生之前最近的那一条备份。

恢复入口位于每行最右侧的 "···" 下拉菜单中，仅当备份状态为success时才会出现Restore和Download选项，菜单实现见 backup-actions-cell.tsx。

步骤 3：一键发起恢复

点击Restore后会弹出确认对话框。如果这份备份保存到了多个存储渠道，你需要选择从哪个存储位置恢复（推荐选present状态且距离近的存储），确认后 Portabase 会创建一条恢复任务（waiting状态）并提交给 Agent 执行，核心调用见 backup-actions-form.tsx。

步骤 4：在 Restoration 标签页跟踪进度

切到Restoration标签页，可以看到恢复记录列表，包含以下关键列（列定义见 restore-columns.tsx）：

列表每 4 秒自动刷新，恢复完成后你会收到通知，无需守着页面等待。

步骤 5：失败怎么办？

如果状态变成failed：

1. 点击Logs查看 Agent 执行的原始命令和退出码，定位失败原因（常见原因：数据库连接失败、快照文件损坏、目标库正在写锁）
2. 问题解决后，在操作菜单中点击Rerun，任务会被重新置为waiting并再次排队执行，重试逻辑见 restore.action.ts

⚠️ 同一时间一个数据库只能有一个进行中的恢复任务，界面会对已有排队任务的情况禁用 Restore 按钮，防止并发冲突。

四、进阶技巧

批量恢复多个数据库

如果你的项目下有多个数据库同时受损，可以使用项目页的批量恢复功能：勾选多个数据库后确认，Portabase 会自动为每个数据库挑选最新的可用成功备份并批量排队恢复，没有可用备份的会被跳过并给出原因。实现见 bulk-restore.action.ts。

用 API 自动化恢复流程

Portabase 提供了 REST API，适合接入告警系统或运维脚本实现"数据丢失自动恢复"。对数据库恢复接口（restore/route.ts）发起 POST 请求，只需传两个参数：

{ "backupId": "备份快照的 UUID", "backupStorageId": "存储副本的 UUID" }

服务端会严格校验：备份必须属于该数据库、未删除、对应存储状态为success且文件存在，否则会返回明确的 404 / 422 错误，避免误恢复。

跨环境迁移数据

Portabase 的Migration 工具本质上是"备份 + 恢复"的组合：从源项目选择备份快照，恢复到目标项目的新数据库，即可完成跨服务器、跨项目甚至跨数据库类型的数据迁移。流程步骤定义见 migration-flow.tsx。

五、常见问题 FAQ

Q1：恢复会把现有数据覆盖掉吗？A：是的，恢复操作会用快照中的数据还原目标数据库。建议先给当前库再打一份备份，"恢复前备份"是生产环境的最佳实践。

Q2：备份文件被误删了还能恢复吗？A：Portabase 会持续检查各存储渠道的文件存在性（状态present/missing），文件丢失的副本不可用于恢复，但如果你在其他存储渠道还有副本，依然可以恢复。

Q3：恢复速度取决于什么？A：主要取决于备份文件大小、所选存储渠道的读取带宽（如 S3 恢复需要先把文件下载到 Agent 服务器）以及数据库本身的还原性能。

六、总结

掌握本教程后，你就拥有了一套可视化、可追踪、可重试的数据库恢复能力——当数据丢失时，最快几分钟内即可从备份快照中找回一切。