Mealie 介绍与选型指南

目标：回答"Mealie 是什么、架构长什么样、能力边界在哪、该不该选它"四个问题。本文为认知篇，全部数据来自官方仓库、官方文档与社区渠道的联网实查（查询日期 2026-11-02），不含本地实测；部署与配置实操见本专栏后续篇目。

一、环境信息

本文引用的实查渠道与查询条件（查询日期均为 2026-11-02）：

• 官方仓库：mealie-recipes/mealie（GitHub，经 GitHub API 与 releases.atom 查询）
• 最新版本：v3.30.0（发布于 2026-10-31）
• 官方文档：docs.mealie.io（安装清单、后端配置、SQLite/PostgreSQL 部署页）
• 官方镜像：ghcr.io/mealie-recipes/mealie（GitHub Container Registry）
• 技术栈：Python 3.14.8 / FastAPI + Uvicorn 后端，Nuxt 3（Vue 3 + Vuetify）前端
• 许可证：AGPL-3.0
• 网络说明：本次查询时 GitHub 直连超时，数据经代理 192.168.1.72:7897 取得；192.168.1.62:7897 当时不可用

二、软件概述

Mealie 是一款开源的自托管食谱管理器，官方定位为"recipe manager, meal planner and shopping list"——食谱管理、膳食计划与购物清单三件套，附带 REST API 后端与 Vue 响应式前端，面向家庭全员使用。

它解决的核心痛点是：菜谱散落在下厨房、豆果、美食杰、各类博客与 YouTube 视频里，没有统一收藏、检索与量化的地方。Mealie 的解法是贴 URL 即入库：粘贴一个菜谱网页链接，内置的 recipe_scrapers 抓取器自动解析 schema.org 结构化数据生成食谱条目；没有结构化数据的页面再手工补录。入库后统一按自己的字段模型（食材、用量、单位、步骤、标签、分类、营养）管理，支持全文检索、按标签/分类筛选、生成购物清单和下周膳食计划。

关键身份信息（GitHub API 实查，2026-11-02）：

版本节奏（releases.atom 实查）：v3.30.0（2026-10-31）、v3.29.0（2026-10-17）、v3.28.0（2026-09-24）、v3.27.0（2026-09-17）、v3.26.0（2026-09-14）、v3.25.0（2026-09-02）、v3.24.0（2026-08-24）、v3.23.0（2026-08-18）——2026 年下半年保持约 2~4 周一个小版本的发布频率，minor 版本号即特性迭代。

💡 技术拓展：自托管食谱管理器赛道的主流选项与取舍——

项目	技术栈	许可证	特点
Mealie	Python/FastAPI + Vue	AGPL-3.0	URL 抓取导入体验最好，单容器一体化，API 完备
Tandoor Recipes	Python/Django + Vue	自定义（仓库未挂标准 LICENSE 文件）	功能最重（含单位换算/插件），部署链路更长
RecipeSage	TypeScript	MIT	书签栏一键抓取见长，云端/自托管双形态
Recipya	Go + HTMX	AGPL-3.0	单二进制轻量，功能面较窄

本文聚焦其中社区规模最大的 Mealie；同赛道另一新秀的实测对比可参考本批次 《Fork Recipes 介绍与选型指南》。

三、核心架构

Mealie v3 采用单容器前后端一体架构（v1 时代前端/后端分双容器的形态已在 v2 合并）：

1. 后端：Python 3.14 + FastAPI + Uvicorn，监听 9000 端口，同时提供 REST API（/api/*）与静态前端资源托管。API 文档由 FastAPI 自动生成，暴露于 /docs（Swagger UI）与 /redoc（ReDoc）。
2. 前端：Nuxt 3（Vue 3 + Vuetify 组件库）构建产物，由后端直接托管，浏览器访问 9000 端口即得完整 SPA，支持 PWA（manifest.webmanifest）。界面无需单独起 Node 服务。
3. 数据库：二选一。默认 SQLite（零配置单文件 data/mealie.db）；可选 PostgreSQL（配置 DB_ENGINE=postgres 及连接四件套）。官方明确：模糊搜索等部分特性仅在 PostgreSQL 下启用。
4. 数据模型三层：Group（家庭组）→ Household（家务单元，v2 引入的多人隔离层）→ User/Recipe/Ingredient 等实体。食材（foods）与单位（units）是独立的可复用字典库，食谱条目引用其 ID。
5. 抓取与解析管线：URL 导入走 recipe_scrapers（Python 社区抓取库，支持数百站点）；食材文本解析走内置 NLTK 模型（NLTK_DATA=/nltk_data/），能把"400 g firm tofu, cubed"拆成数量/单位/食材/备注四元组。
6. 扩展面：REST API（195 个路径的 OpenAPI 3.1 规格）、API Token（长期令牌）、膳食计划 Webhook、SMTP 邀请/找回密码、LDAP / OIDC / 反代头部三种认证外挂、AI 供应商接口（OpenAI 兼容，用于生成食谱与图像解析）。

四、功能特性

官方 README「Key Features」清单（v3.30.0，实查 2026-11-02）：

• Recipe imports：URL 导入或手工录入创建食谱；
• Meal Planner：周膳食计划视图；
• Shopping List：购物清单，按超市分区组织；
• Cookbooks：按自定义标准把食谱归入食谱集；
• Docker：官方主推 Docker 部署；
• Localisation：35+ 语言翻译（含 zh-CN/zh-TW，经 Crowdin 协作）。

在 README 之外，v3 实际能力面还包括：

• 食谱评分与"做过几次"时间线（timeline events）、评论（可关）；
• 标签/分类/工具/营养/备注等结构化字段，批量操作（打标签、归类、导出、删除）；
• 导出：单食谱/批量导出 zip、mealie-json、原始 JSON；全站备份 zip 一键生成并可从 UI 或 API 恢复；
• 分享链接（shared recipes token）与公共访问控制（Group/Household 私有开关）；
• 图片、附件（assets）管理；YouTube 等视频内嵌（受 ALLOWED_IFRAME_HOSTS 白名单控制）；
• 多用户协作：邀请制注册（ALLOW_SIGNUP 开关 + 家庭邀请 token）。

五、快速开始（最小可用示例）

以下 compose 片段摘自官方文档 SQLite 部署页（docs.mealie.io，查询日期 2026-11-02），仅作认知展示、未在本篇实测；完整实测部署流程见本专栏的 Docker Compose 部署篇。

services:
  mealie:
    image: ghcr.io/mealie-recipes/mealie:v3.30.0
    container_name: mealie
    restart: always
    ports:
      - "9925:9000"
    volumes:
      - mealie-data:/app/data/
    environment:
      BASE_URL: http://mealie.yourdomain.com
      ALLOW_SIGNUP: "false"
      PUID: 1000
      PGID: 1000
      TZ: America/Anchorage

volumes:
  mealie-data:

启动后访问 http://<宿主机>:9925，首次登录使用官方文档标注的默认凭据 changeme@example.com / MyPassword，登录后立即进入账号设置向导改名改密。官方安装清单同时提醒：单实例足够跑 1-20 用户规模，更高并发建议 PostgreSQL。

六、适用场景与限制

适合：

• 家庭/小团队自建菜谱库，重"从网页导入"工作流；
• 需要 PWA 移动端体验（加桌面、离线浏览）；
• 需要程序化接入（Home Assistant、n8n、iOS 快捷指令都有社区集成，官方文档收录了这些社区指南）；
• 单容器低运维诉求：不想要 Tandoor 那种前后端+worker+redis 多服务编排的用户。

限制与注意点（官方文档与仓库实查）：

• 模糊搜索等特性仅 PostgreSQL 可用，SQLite 形态搜索能力受限；
• 镜像体积不小（v3.30.0 解包约 1.47GB，含 NLTK 数据与前端产物），官方 compose 示例给内存限额 1000M；
• AGPL-3.0：自用无碍；若把 Mealie 改造后作为网络服务对外运营，需履行源码开放义务；
• 抓取成功率依赖目标站点反爬策略与 recipe_scrapers 适配度，无结构化数据的站点仍需手工录入；
• 首次启动即内置默认账号 changeme@example.com/MyPassword，公网部署必须第一时间修改（详见部署篇排障实录）。

七、同类选型对比

量化对比（GitHub API / shields.io / releases.atom 实查，2026-11-02）：

解读与选择建议：

• 社区规模与迭代速度：Mealie 星数约为第二名 Tandoor 的 1.6 倍，且发布节奏更快（24 周 vs 12 月），issue 存量更低（130 vs 394），维护健康度在同类中最好。
• 要"开箱即用 + 贴链接导入"：选 Mealie。Tandoor 功能更深（单位换算、插件生态）但部署链路长（gunicorn+worker+redis+db 四件套），适合重度玩家。
• 要极简资源占用：Recipya（Go 单二进制）或 RecipeSage；两者功能面与生态显著小于 Mealie。
• 前后端分离架构偏好：可看同批次的 《Fork Recipes 介绍与选型指南》，但其社区规模（69 star）与 Mealie 差两个数量级。

八、参考链接

• 官方仓库：https://github.com/mealie-recipes/mealie （查询日期 2026-11-02）
• 官方文档：https://docs.mealie.io/ （查询日期 2026-11-02）
• 发布记录：https://github.com/mealie-recipes/mealie/releases.atom （查询日期 2026-11-02）
• 官方镜像：https://ghcr.io/mealie-recipes/mealie （查询日期 2026-11-02）
• 社区 Discord：https://discord.gg/QuStdQGSGK （README 收录）