Mealie v1 迁移指南：从旧版导出备份到新实例的完整实操与源码解析

Mealie v1 迁移指南从旧版导出备份到新实例的完整实操与源码解析【免费下载链接】mealieMealie is a self hosted recipe manager and meal planner with a RestAPI backend and a reactive frontend application built in Vue for a pleasant user experience for the whole family. Easily add recipes into your database by providing the url and mealie will automatically import the relevant data or add a family recipe with the UI editor项目地址: https://gitcode.com/GitHub_Trending/me/mealieMealie 的 v1 版本从底层重构了数据模型、API 与权限体系旧版数据无法直接平滑升级。本文基于官方迁移文档完整讲解旧实例导出备份 → 新实例导入迁移 → 校验报告的四步迁移路径并深入剖析仓库内MealieAlphaMigrator迁移器的字段映射、报告机制与图片导入实现帮助你安全、快速地把旧版食谱数据搬进 v1 实例。迁移前必须了解的三件事v1 发布版本应当被视为一个全新的应用大量改动提升了应用性能与开发者体验但也带来了无法回避的破坏性变更。在动手迁移之前请先确认以下三点API 集成将被破坏v1 中多个 API 端点已经变化。如果你依赖旧版 API 编写了外部脚本或集成代码必须改用新的端点。食谱默认私有v1 中食谱默认只能被登录用户查看。你可以精细配置公开访问也可以让实例保持完全私有。详见权限与公开访问指南。迁移支持范围有限目前迁移工具只覆盖以下数据类型其余类型如用户、分组、饮食计划、Cookbook/页面仍在开发中数据类型迁移支持状态Recipes食谱✅ 已支持Categories分类✅ 已支持Tags标签✅ 已支持Users用户❌ 未支持Groups分组❌ 未支持Meal Plans饮食计划❌ 未支持Cookbooks / Pages食谱簿/页面❌ 未支持官方说明支持更多数据类型的工作正在推进中但并非当前优先级欢迎通过 PR 贡献额外数据的迁移支持。Step 1搭建全新 v1 实例考虑到升级的本质强烈建议在现有实例旁边并行搭建一个新的 v1 实例而不是在旧实例上原地升级。这样可以安全、快速地进行数据迁移且不会影响正在运行的旧服务。按照安装清单完成新实例的搭建并成功登录后再继续进入 Step 2。从仓库结构看v1 采用了docker-compose.yml、Dockerfile等标准的容器化部署方式同时支持通过uv.lock与pyproject.toml管理 Python 依赖新实例与旧实例可在不同端口/目录下并存运行。Step 2从 Pre-v1 旧实例导出数据在旧版pre-v1实例中进入Admin 管理后台找到标记为Backups的区块如上图所示执行一次数据导出备份。导出时请注意务必勾选包含食谱recipes这是迁移所需的核心数据勾选其他额外项目不会影响迁移流程但即便包含它们也会被迁移器忽略因为迁移器只解析食谱、分类与标签相关的数据导出产物是一个.zip归档文件请妥善保存。从前端迁移页面展示的目录树见 migrations.vue可以确认旧版备份包的内部结构大致如下mealie.zip └── recipes/ ├── recipe-name/ │ ├── recipe-name.json # 食谱元数据 │ └── images/ │ ├── original.webp │ ├── full.jpg │ └── thumb.jpg └── recipe-name-1/ ├── recipe-name-1.json └── images/ ...其中recipe-name.json为食谱数据文件images目录存放该食谱的图片原图、全尺寸图与缩略图。Step 3使用迁移工具导入 v1 实例在新 v1 实例中按以下步骤操作浏览器访问/group/migrations页面在迁移类型下拉框中选择 Mealie即 pre-v1 迁移器前端代码中映射为mealie_alpha见 migrations.vue上传第 2 步从旧实例导出的.zip备份文件可选勾选为所有导入食谱添加迁移标签选项迁移器会自动为导入的食谱打上mealie_alpha标签便于事后识别与批量管理点击提交迁移随即开始。整个过程可能需要一些时间迁移完成后页面下方的Previous Migrations历史迁移表格中会出现一条新记录点击查看迁移报告确认每条食谱的导入结果。关于迁移报告存在个别食谱导入失败的情况但迁移器仍会继续导入其余成功的食谱。多数情况下手动迁移失败食谱比排查失败原因更快。若迁移工具本身出现问题可在 GitHub 上提交 issue 反馈。迁移前端页面的实现细节迁移页面frontend/app/pages/group/migrations.vue的界面元素与后端能力一一对应迁移类型下拉框支持 Mealie pre-v1 以及 Chowdown、CopyMeThat、MyRecipeBox、Nextcloud、Paprika、PlanToEat、RecipeKeeper、Tandoor、Cookn 等十余种来源Mealie 迁移只接受.zip文件acceptedFileType: .zip页面上用树状视图直观展示备份包的期望结构方便你对照检查导出的压缩包格式勾选添加迁移标签对应请求参数addMigrationTag提交后调用api.groupMigration.startMigration(payload)触发后端POST /groups/migrations接口返回的ReportSummary会插入到历史迁移列表顶部。后端的迁移入口与执行流程后端迁移接口由 GroupMigrationController 提供路由为POST /groups/migrations表单参数包括参数类型说明archive文件必填上传的 zip 备份文件服务端会先保存到临时目录migration_type枚举必填迁移来源类型如mealie_alphaadd_migration_tag布尔可选是否给导入食谱添加来源标签默认false控制器会根据migration_type从SupportedMigrations见 group_migration.py映射出对应的迁移器类并传入当前登录用户、所在分组group与家庭household上下文然后调用迁移器的migrate()方法。整个执行过程分为三步见 BaseMigrator_create_report()在数据库中创建一条状态为in_progress的迁移报告_migrate()执行实际的数据解析与导入由各子类实现_save_all_entries()将所有导入条目的成功/失败信息写入报告并汇总出最终状态——全部成功为success、全部失败为failure、部分成功为partial。MealieAlphaMigrator旧版数据的字段映射与导入MealieAlphaMigratormealie_alpha.py是本次迁移的核心实现。它做了以下几件事字段别名映射旧版 JSON 字段名与 v1 新 Schema 不一致通过key_aliases完成转换旧字段alias新字段key处理函数titlename无ingredientsrecipeIngredient无directionsrecipeInstructions无tagstagssplit_by_comma按逗号拆分、去除空白并转为首字母大写Schema 归一化_convert_to_new_schemacategories→recipeCategory删除旧版内部字段_id、date_added过滤掉 tags/categories 中的空字符串元素若extras为列表则重置为空字典将comments置空列表将id重置为None让数据库为新食谱生成全新主键。压缩包解压与图片搬运_migrate迁移器将 zip 解压到临时目录通过rglob(**/recipes/**/[!.]*.json)递归找出所有食谱 JSON 文件逐个解析并导入数据库导入成功后再把原备份中该食谱images目录下的图片复制到新实例的食谱图片目录中。此外BaseMigrator.get_zip_base_path还处理了 Safari 等工具解压产生的__MACOSX目录干扰确保能正确定位备份包的根目录。食谱所有者分配执行任何迁移时导入食谱的所有者会自动分配给执行迁移操作的用户。分组内的所有成员仍可访问该食谱但所有者拥有特殊权限可以锁定食谱、禁止其他用户编辑。这一逻辑在import_recipes_to_database中体现见 _migration_base.py每条食谱被写入user_id当前用户与group_id标签与分类还会通过get_or_set_tags/get_or_set_category归并到分组现有的标签与分类体系中。食谱默认设置的继承迁移时导入食谱的各项显示设置是否公开、是否显示营养信息、是否显示素材、是否横向视图、是否禁用评论并非硬编码而是从当前家庭household的偏好设置中读取并应用到每条导入食谱上见 _migration_base.py。因此导入前可以先在 v1 实例中配置好家庭偏好迁移后的食谱会自动遵循这些默认值。Step 4迁移完成后的检查与收尾迁移完成后建议做以下检查查看迁移报告确认每条食谱的状态成功/失败对失败条目决定是手动重建还是重新导入确认访问权限由于 v1 食谱默认私有请按需为公开食谱、分组或家庭配置公开访问。完整的判定规则私有分组/家庭/食谱层层拦截、私密链接可绕过所有权限等见权限与公开访问指南使用mealie_alpha标签如果勾选了迁移标签可在食谱列表中按该标签筛选快速复核导入结果或进行批量清理体验 v1 新功能v1 引入了大量新特性与改进可通过项目的发布变更说明仓库根目录的cliff.toml即用于生成变更日志了解每个版本的新增内容确认新实例数据无误后再逐步下线旧实例完成整体切换。常见问题与注意事项汇总导出包包含食谱以外的数据怎么办会被迁移器忽略不影响迁移流程。个别食谱导入失败怎么办迁移报告会给出失败原因其余成功食谱不受影响官方建议直接手动重建失败的食谱效率更高。图片没有迁移成功迁移器会尝试从备份的images目录复制图片见 migration_helpers.py 中的import_image/scrape_image若源文件缺失或格式无法识别UnidentifiedImageError该食谱会保留但图片导入会被跳过并记录日志。安全提示迁移器对备份包内的图片路径做了目录穿越防护safe_local_path任何试图逃逸解压根目录的路径都会被静默拒绝避免归档文件触发任意本地文件读取。通过以上四步你可以把旧版 Mealie 的食谱、分类与标签数据完整搬入 v1 新实例并在全新的权限体系与架构下继续使用。仓库中迁移相关的全部实现迁移控制器、迁移基类、Mealie 迁移器与前端页面migrations.vue均可直接查阅作为理解或扩展迁移能力的参考。【免费下载链接】mealieMealie is a self hosted recipe manager and meal planner with a RestAPI backend and a reactive frontend application built in Vue for a pleasant user experience for the whole family. Easily add recipes into your database by providing the url and mealie will automatically import the relevant data or add a family recipe with the UI editor项目地址: https://gitcode.com/GitHub_Trending/me/mealie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考