Backup & Migration 扩展

ram0ng1

📦 Backup & Migration - Flarum 2 便携备份工具

Flarum 的完整备份、导出和导入系统 - 将你的论坛打包成单个 .flarum 文件，可在相同或不同服务器上恢复，支持可选的 libsodium 加密。

管理后台

受 All-in-One WP Migration 启发，但完全从零编写，使用自定义流式格式（无需 .wpress，无需 zip），因此多 GB 的备份从不需要全部载入内存。

✨ 功能

单个便携 .flarum 文件 — 数据库、public/assets、storage 以及所有已安装的扩展（workbench 或 vendor）
逐扩展选择器，每行带标签显示是 composer 管理还是本地安装
composer.json + composer.lock 在打包扩展时一同携带，确保目标站点的 vendor 扩展可复现
可续传的导出和导入（每次 HTTP 请求 4 MB），带实时进度条和上传百分比指示器
可选的 libsodium 加密 — 密封盒包装每个存档的 XChaCha20-Poly1305 流密钥。公钥在数据库中，私钥仅在 config.php 中
跨服务器传输 — 使用对方的公钥加密，导入时粘贴匹配的私钥
自动 URL 重写 — 源 URL 记录在存档头部，在不同主机上恢复时会自动重写 settings、posts.content 和 posts.parsed_content
可选择恢复 — 按分区和扩展勾选复选框，从存档清单中读取选项
此外还有：外键安全的 DDL 重放、node_modules/.git 清理、当数据库恢复替换管理员 session 时显示专用的"你已登出"页面

📸 截图

创建备份
创建备份弹窗

选择要恢复的内容
恢复选择界面

恢复成功后
登出提示页

📥 安装

composer require ramon/backup
php flarum migrate
php flarum cache:clear

然后在 Extensions 页面启用 Backup & Migration。

🔗 链接

GitHub: https://github.com/ram0ng1/backup
Packagist: https://packagist.org/packages/ramon/backup
问题/反馈: https://github.com/ram0ng1/backup/issues

MIT 许可证，已发布到 Packagist。在 Flarum 2.0 + MySQL 8 / PHP 8.3 和 8.5 上测试通过。libsodium 仅在你选择加密时才需要。

欢迎反馈 — 特别是 vendor 扩展恢复和大存档的边界情况。Bug 报告和 PR 请在 GitHub 提交。🙌

navindra

ram0ng1 单个便携 .flarum 文件 — 数据库、public/assets、storage 以及所有已安装的扩展

太厉害了，这个真是超乎想象！👏

user_46896

我很需要这个

jedafe

非常感谢你开发这个出色的扩展 🙏

我之前尝试在 Postgres 上安装 Flarum 2.x，但由于"未找到驱动"错误没成功，后来改用 MySQL 数据库安装了。但我的主要目标是用 Postgres。虽然我在花了很多时间在 MySQL 上安装配置 Flarum 之后才找到了 Postgres 安装的问题。

所以我的问题是：

我可以用这个扩展把我的 Flarum 从原有的 MySQL 迁移到新安装的 Postgres 吗？

MaxDob

这个扩展确实很需要！我在创建备份时遇到了一个问题。有解决办法吗？

ram0ng1

jedafe
MaxDob

目前还不支持 PostgreSQL。不过我今天晚些时候会检查一下当前状态。

ram0ng1

试试：

composer update ramon/backup -W

php flarum migrate

php flarum cache:clear

jedafe

ram0ng1 非常感谢。我会试试看。

GreXXL

ram0ng1 这很有意思。你还在里面做了一个数据库迁移工具。很期待看看不同数据库之间迁移的效果如何。

KBExit

GreXXL 谢谢提醒。我停止所有 linkrobins/db-transfer 的工作了 lol

ram0ng1

GreXXL 虽然 Flarum 核心支持扩展，但第三方扩展可能无法正常工作。我已经添加了一个警告，说明当选择时某些扩展数据会丢失（主要是数据库不兼容导致的）。

这个扩展目前还不完美，我正在努力提升所有驱动的兼容性。

在我自己的 MySQL 到 PostgreSQL 测试中，甚至发现我的 Avocado 主题也不兼容，帖子未能迁移。简而言之：我仍在改进中。

数据库迁移架构

当前能力：

引擎无关的 Schema： 使用抽象模型（ColumnType.php）将列类型规范化为 25 种通用类型（BIGINT、JSON、UUID 等）。
多引擎支持： 包含 MySQL、MariaDB、PostgreSQL 和 SQLite 的专用 Introspector 和 Emitter。
智能修复： * Postgres： 延迟外键防止创建错误，重同步序列（setval）避免 ID 冲突。
- SQLite： 将自增字段强制转换为 INTEGER PRIMARY KEY 以保持兼容。
- MariaDB/MySQL： 处理两者之间特定的 JSON 实现差异。

已知限制：

Postgres 特性： 原生 PG 类型（INET、Arrays）回退为字符串；ENUM 渲染为 CHECK 约束而非 CREATE TYPE。
元数据： 排序规则和字符集重置为目标服务器的默认值。
Flarum 优先： 虽然针对 Flarum 的 MySQL 便携 schema 做了优化，但任意复杂 schema 可能触发回退路径。

总结： 仍然存在很多缺陷，我还在继续工作中。我会很快发布一些进展和发现！

ram0ng1

MySQL 到 Postgres 的测试已完成！恢复成功地将所有内容从 MySQL 迁移到了 PostgreSQL。😃

要更新到 ramon/backup:2.0.13，运行以下命令：

composer update ramon/backup
php flarum migrate
php flarum cache:clear

源服务器：

目标服务器：

权限：

目标权限：

成功完成！数据从 MySQL 服务器迁移到 PostgreSQL 服务器，没有任何问题。😃

@GreXXL

迁移修复逻辑总结

2. ENUM CHECK 约束

文件： src/Database/Emitter/PostgresEmitter.php
逻辑： MySQL 对无效 ENUM 值比较宽容（将其转为空字符串），而 Postgres 的 CHECK 约束很严格，会导致整批数据失败。修复移除了 CHECK 约束，将该列作为纯 TEXT 输出，以确保导入时的数据完整性。

3. 外键验证

文件： src/Database/Emitter/PostgresEmitter.php
逻辑： 旧数据库通常包含"孤儿"行（外键检查曾被禁用）。如果现有数据违反外键约束，Postgres 会阻止创建外键。修复在 ALTER TABLE 语句中添加了 NOT VALID，允许创建约束而不立即验证历史数据。

4. Btree 索引大小限制

文件： - src/Database/Emitter/PostgresEmitter.php
- src/Database/Emitter/SqlEmitter.php
- src/Database/Emitter/AbstractEmitter.php
- src/Database/DatabaseDumper.php
逻辑： Postgres 的 btree 索引有严格的 2704 字节每行限制。MySQL 中超过此限制的大文本或 blob 列会导致迁移失败。逻辑现在会检测这些列并跳过索引创建以保留实际数据，并向管理员发出警告。

5. Postgres 序列重同步

文件： src/Job/ImportJob.php
逻辑： 在使用显式 ID 批量加载数据后，Postgres 的内部序列（SERIAL/IDENTITY）不会自动更新。这会导致下次插入时主键冲突。修复实现了一个恢复后扫描，通过 pg_get_serial_sequence 检测序列并将其重置为 MAX(id) + 1。

luceos

我认为这是一个很棒的功能。但我很好奇对于较大的社区，导出和导入如何工作，例如多 GB 的数据库。据我所知，管理员需要保持标签页打开才能让导出在超时之间继续？你有在大型数据库上测试过吗？

ram0ng1

luceos 到目前为止，我只用示例模型测试过，但我可以用几 GB 的测试数据来做适当的压力测试。唯一的缺点是我只能下周才能做这个，哈哈。

ram0ng1

luceos 是的！需要保持连接活跃。

luceos

ram0ng1 我好奇的是，是否可以依赖 CLI 端进程（如 cronjob 定时任务或队列）来分片生成备份？队列也有时间限制。因为依赖客户端连接（可能因为各种原因超时）似乎不太可靠？

CLI 通常没有内存限制和时间限制。

KBExit

luceos CLI 正是我在托管服务上使用的方式，我可以保证这是正确的做法。

flavour1

MaxDob

@ram0ng1 你有计划支持 MariaDB 吗？

(ramon-backup 2.0.13, MariaDB 版本: 10.11.14)