ManageMeals 介绍与选型指南

目标：回答「ManageMeals 是什么、架构长什么样、能干什么、适合谁、和同类菜谱管理方案怎么选」。本文为纯联网溯源文档，全部事实来自官方网站、GitHub 官方仓库、发布订阅源与公开徽章数据，查询日期 2026-11-02；不含本地实测内容（部署与配置实测见本专栏其余篇目）。

一、环境信息（信息源与查询日期）

本文所有结论均来自以下公开渠道，查询日期统一为 2026-11-02（北京时间）：

• 官方网站（功能自述与托管版入口）：https://managemeals.com/
• 前端源码仓库：https://github.com/managemeals/manage-meals-web（SvelteKit）
• 后端源码仓库：https://github.com/managemeals/manage-meals-api（Fastify）
• 发布记录：两仓库各自的 releases.atom（Atom 订阅源实查）
• 官方自托管文档：https://github.com/managemeals/manage-meals-api/wiki/Self‐hosting（含完整 docker-compose 样例）
• 社区活跃度徽章：img.shields.io 的 stars / contributors / last-commit 徽章（GitHub API 限流时的替代取证渠道）
• 同类对比组件仓库：mealie-recipes/mealie、TandoorRecipes/recipes、julianpoy/recipesage、reaper47/recipya、mikebgrep/fork.recipes

⚠️ 甄别纠偏：发现阶段注记仅登记了前端仓库 manage-meals-web 且语言字段为空。实查确认 ManageMeals 是多仓库套件：manage-meals-web（SvelteKit 前端）+ manage-meals-api（Fastify/Node.js 后端），另有 ghcr.io 上的 manage-meals-scraper（Python 菜谱抓取器）与 manage-meals-search-sync（搜索同步器）两个独立镜像，技术栈为 Node.js + Python 全栈。本文以实测信息源为准。

二、软件概述

ManageMeals 是一个开源（GPL-3.0）的自托管菜谱管理与膳食计划平台，官方自述定位为「Manage recipes, import recipes by URL and organize them without any ads or unnecessary text」——通过 URL 一键导入菜谱、去除广告与无关内容、纯净阅读并组织自己的菜谱库。它提供两种使用形态：

1. 官方托管版：https://managemeals.com/ 免费注册使用，无需信用卡；
2. 自托管版：官方 Wiki 提供完整 docker-compose 部署方案，镜像发布于 GitHub Container Registry（ghcr.io/managemeals/），数据完全由用户自己持有。

关键身份信息（均取自官方仓库与徽章，查询日期 2026-11-02）：

💡 技术拓展：菜谱「URL 导入」的技术路线不止一种。常见方案对比——

路线	原理	优点	局限
结构化数据抽取	解析网页内 schema.org/Recipe JSON-LD 微数据	准确、字段完整	站点未标注则失效
通用 HTML 启发式	按标题/列表/步骤等 DOM 模式猜测	覆盖面广	解析易出错需人工修正
LLM/AI 辅助抽取	把页面内容交给大模型整理成菜谱结构	冷门站点也能导入	依赖外部 API、有费用与隐私成本
手动录入/Recipe Card 文件	用户手填或导入 .recipe-card/JSON 文件	100% 可控	费时

ManageMeals 采用「自建 Python 抓取器（启发式+结构化）为主、可选 Perplexity AI 兜底」的组合：抓取器 recipe-scraper 内置数百站点支持，配置 PPLX_API_KEY 后可用 Perplexity API 解析最冷门的菜谱站。

三、核心架构

依据官方两仓库 README、自托管 Wiki 与 compose 样例（均为公开可查内容，查询日期 2026-11-02）：

1. 前端（manage-meals-web，SvelteKit）：SSR 应用，构建后经 Node adapter 监听 3000 端口（官方镜像内），通过环境变量注入 PUBLIC_MAIN_TITLE、API_URL（后端地址，如 http://manage-meals-api:3000/v1）、Cookie 令牌名与有效期、ORIGIN、PASSWORD_MIN_LENGTH 等；登录态用 HttpOnly Cookie（access/refresh 双令牌）维持。
2. 后端（manage-meals-api，Fastify）：REST API，路由前缀 /v1；JWT 双令牌认证（ACCESS_JWT_SECRET/REFRESH_JWT_SECRET，过期时间 AUTH_ACCESS_TOKEN_EXPIRE_SEC 默认 600 秒、AUTH_REFRESH_TOKEN_EXPIRE_SEC 默认 2629746 秒≈一个月）；注册开关 USER_REGISTER_ENABLED。
3. 数据存储（MongoDB 7）：菜谱、标签、用户、膳食计划、购物清单等全部落 Mongo（库名 manage_meals，集合如 tags 需建 uuid 唯一索引与 slug+createdByUuid 复合唯一索引，官方 Wiki 给出 mongosh 命令）；备份用 mongodump --gzip --archive 定时 cron，恢复用 mongorestore --nsInclude。
4. 缓存（Valkey 8）：Redis 兼容键值存储（REDIS_URL: redis://valkey:6379），供 API 会话/缓存使用；开发形态中亦称 redis。
5. 搜索（Typesense 28.0 + search-sync）：菜谱全文检索由 Typesense 承担（容错拼写、毫秒级）；独立组件 manage-meals-search-sync 持续把 MongoDB 数据同步进 Typesense 索引（MONGO_URL+TYPESENSE_HOST/PORT/API_KEY）。
6. 菜谱抓取器（manage-meals-scraper，Python/Flask）：独立服务监听 8000 端口，API 通过 RECIPE_SCRAPER_URL 调用；负责 URL→菜谱结构化解析，可选 PPLX_API_KEY（Perplexity）、DEFAULT_RECIPE_IMG（默认封面图）、缓存 Redis 参数等。
7. 异步任务（开发形态）：后端仓库的开发 compose（docker-compose.infra.yaml）含 RabbitMQ + consumer（队列）/handler（webhook）进程；自托管 Wiki 的生产最小 compose 未要求 RabbitMQ，由 search-sync 常驻替代。
8. 部署拓扑：生产最小形态 7 个服务（api、web、mongo、mongo-express、valkey、recipe-scraper、typesense、search-sync）；官方仓库另有「app-01/app-02 + nginx LB」「scraper-01/scraper-02 + LB」的多实例 compose 模板（经 override 文件暴露 8201/8202/8209、8101/8102/8109 等端口），说明应用层无状态、可水平扩展，但官方未提供高可用承诺文档。

四、功能特性

摘自官网 Features 页（查询日期 2026-11-02）：

• URL 导入菜谱：支持数百个主流及长尾菜谱网站；不支持的站点官方承诺补充；失败站点可邮件反馈。
• 无广告纯净阅读：去除菜谱页广告与无关文本，详情页只保留相关信息。
• 快速容错搜索：Typesense 驱动，接近即时返回，可容忍拼写错误。
• 膳食计划（Meal Plans）：单日或整周计划；Meal Types 支持一天多餐次；可按条件自动生成或手动挑选菜谱。
• 购物清单（Shopping Lists）：从菜谱或膳食计划一键生成，自动汇总食材。
• 分享链接：任何人凭链接可查看菜谱，无需注册。
• 烹饪模式（Cooking Mode）：详情页勾选后阻止屏幕休眠，厨房场景免频繁触屏。
• 打印友好：Ctrl+P/CMD+P 输出无图无色的紧凑打印版菜谱。
• 深色模式与响应式：明暗主题切换；手机/平板/桌面自适应，食材与步骤在小屏上保持就近排版。
• Bookmarklet：拖拽小书签到浏览器书签栏，浏览菜谱站时一键把 URL 填入导入表单；浏览器扩展官方标注 coming soon。
• 免费与开源：托管版免费；全部代码在 GitHub 可查，GPL-3.0。

五、快速开始（最小可用示例，官方文档口径）

以下为官方自托管 Wiki 给出的最小部署路径（原文摘录，非本地实测；逐条实测命令与回显见本专栏《ManageMeals Docker Compose 部署指南》）：

# 1. 编写 docker-compose.yaml：manage-meals-api + manage-meals-web + mongo:7
#    + mongo-express + valkey/valkey:8 + manage-meals-scraper
#    + typesense/typesense:28.0 + manage-meals-search-sync 共 8 个服务
# 2. 编写 docker-compose.override.yaml 暴露端口：
#    api 3000:3000、web 3001:3000、mongo 27017、mongo-express 8081、
#    valkey 6379、scraper 8000、typesense 8008:8108
# 3. 启动
docker compose up
# 4. 浏览器打开 http://localhost:3001 注册账号（USER_REGISTER_ENABLED="true"）

关键环境变量（官方样例值）：API 侧 MONGO_URL、REDIS_URL、TYPESENSE_*、ACCESS_JWT_SECRET/REFRESH_JWT_SECRET、RECIPE_SCRAPER_URL；Web 侧 API_URL、ORIGIN、Cookie 令牌配置。升级路径官方口径为 docker compose pull && docker compose up，维护者声明镜像保持向后兼容。

六、适用场景与限制

适合：

• 个人/家庭想自建菜谱库 + 膳食计划 + 购物清单闭环，且痛恨菜谱网站广告干扰的读者；
• 重视数据主权：MongoDB 自持数据，mongodump 备份路径官方有文档；
• 已有 Docker/Compose 运维能力、能接受多组件依赖链的自托管玩家；
• 想先用托管版（managemeals.com 免费）验证使用习惯、再平滑迁移自托管的用户。

限制（官方信息与社区评价可证，查询日期 2026-11-02）：

• 依赖链重：完整自托管需要 API、Web、MongoDB、Valkey、Typesense、scraper、search-sync 七类服务，内存占用与运维面比单二进制方案大；
• 单人维护：两仓库 contributors 均为 1，最后提交 2026-09；问题响应依赖维护者个人节奏；
• 社区规模小：web 63★ + api 13★（2026-11-02 徽章），生态、插件与第三方教程几乎为零；
• 无官方移动端：响应式 Web 为主，原生 App 与浏览器扩展均标注 coming soon；
• 抓取成功率非 100%：冷门站点解析可能失败需手动修正；AI 兜底依赖 Perplexity API Key（有费用与隐私成本）；
• 无高可用/集群官方文档：多实例 compose 模板存在于开发仓库，但官方未给出生产 HA 拓扑与一致性保证；
• 功能面聚焦：无营养分析、无多用户权限分级（家庭共享为主）、无菜谱评分社区等 Mealie/Tandoor 生态特性。

七、同类选型对比

对比维度量化数据均来自 shields.io 徽章与 GitHub releases.atom 实查，查询日期 2026-11-02：

版本节奏与兼容矩阵：ManageMeals API 2026 年内 v1.8.0（3 月）→v1.9.0（5 月）→v1.9.1（6 月）→v1.9.2（8 月）→v1.9.3（9 月），约 1~3 个月一版，前后端版本号独立但同日发版；维护者声明自托管镜像向后兼容、升级即 pull+up。Mealie/Tandoor 发版更密（月级）、兼容矩阵覆盖 PostgreSQL/MySQL 等更多数据库选项；ManageMeals 数据库锁定 MongoDB、搜索锁定 Typesense，无替换方言案。

选型建议（如果…则…）：

• 如果你核心诉求就是「URL 导入 + 无广告纯净阅读 + 周膳食计划」、能接受多服务 compose 运维 → ManageMeals 的搜索体验与纯净阅读是同类中最贴合的；
• 如果你要功能大而全、社区保障与多语言界面 → 选 Mealie（14k★，本组旗舰）；
• 如果你需要营养计算与单位换算 → 选 Tandoor；
• 如果你服务器资源紧张、想要单二进制极简部署 → 选 Recipya（Go+SQLite）；
• 如果你不想自托管、接受付费同步服务 → RecipeSage 官方托管；
• 如果你要原生手机 App → ManageMeals 当前无官方 App，考虑 Fork Recipes 或 Mealie 的 PWA/第三方客户端。
• 同组已交付的菜谱类选型参考：《Fork Recipes 介绍与选型指南》。

八、参考链接

• ManageMeals 官网（功能自述与托管版）：https://managemeals.com/ （查询日期 2026-11-02）
• 前端仓库：https://github.com/managemeals/manage-meals-web （查询日期 2026-11-02）
• 后端仓库：https://github.com/managemeals/manage-meals-api （查询日期 2026-11-02）
• API Releases（v1.9.3）：https://github.com/managemeals/manage-meals-api/releases （查询日期 2026-11-02）
• Web Releases（v1.7.3）：https://github.com/managemeals/manage-meals-web/releases （查询日期 2026-11-02）
• 官方自托管 Wiki：https://github.com/managemeals/manage-meals-api/wiki/Self%E2%80%90hosting （查询日期 2026-11-02）
• Mealie：https://github.com/mealie-recipes/mealie （查询日期 2026-11-02）
• Tandoor Recipes：https://github.com/TandoorRecipes/recipes （查询日期 2026-11-02）
• RecipeSage：https://github.com/julianpoy/recipesage （查询日期 2026-11-02）
• Recipya：https://github.com/reaper47/recipya （查询日期 2026-11-02）
• Fork Recipes：https://github.com/mikebgrep/fork.recipes （查询日期 2026-11-02）