这是「Docker 好项目」系列的第 29 期。前面 28 期写的几乎都是服务器自己的东西——监控、备份、认证、容器管理,全是「给机器用的」。这期换个方向:写个给家里用的。菜谱这事儿有个很典型的状态:收藏夹里躺着几十个链接、微信里存着一堆短视频、真到要做饭的时候一个也找不到。Mealie 干的就是这件事——把菜谱从「链接」变成「你自己数据库里的一条结构化记录」,顺便按周排菜单、自动生成采购清单。13.5k stars,AGPL 协议,官网文档也是在这两天还在更新的活跃项目。

Mealie 效果图

痛点开场

先看看菜谱到底是怎么丢的:

  • 链接会死。收藏的菜谱过半年再点开,要么 404、要么网站改版、要么跳到「登录/下载 App 查看完整菜谱」。你收藏的不是菜谱,是别人服务器上的一段 HTML
  • 视频菜谱没法用。做菜的时候手上有油有水,不可能举着手机拖进度条找「盐放多少来着」。短视频平台的内容天生不适合在厨房里消费
  • 改过的配比记不住。照着菜谱做过一次,糖减半、多加一勺醋,下次想复现全靠回忆
  • 采购清单要手抄。周末想做三道菜,得把三份配料表摊开,自己合并去重,再一条条写进备忘
  • 家里别人看不到。你收藏的东西在你手机上,家里做饭的另一个人完全不知道

Mealie 的答案很朴素:把菜谱从外面搬进自己的数据库——标题、配料(数量 + 单位 + 食材分开存)、步骤、图片、标签、分类,全是结构化字段;然后挂到一周七天的格子(Meal Planner)上,系统自动把这几天的配料合并成一张购物清单。数据在你自己服务器上,链接死不死跟你没关系了。

Mealie 菜谱页面

能力边界

能干什么(以下基于 v3.28.0 镜像、源码与官方文档逐项核实)

  • 网页抓菜谱:粘贴 URL 自动导入标题/配料/步骤/图片,基于 schema.org 的 JSON-LD 与 microdata 结构化数据(底层是 recipe_scrapers 库)。英文菜谱站命中率很高
  • 手动录入与编辑:富文本编辑器,配料逐行写,支持份数缩放(做四人份改成两人份,用量自动按比例换算)、公制/英制单位换算
  • 食材解析器:把「2 cups all-purpose flour」拆成 数量 2 / 单位 cups / 食材 flour 三段,这样才能参与购物清单的合并汇总

Mealie 食材解析器

  • 周菜单(Meal Planner):把菜谱拖进一周七天的早餐/午餐/晚餐格子,支持按天/按周视图
  • 购物清单:从菜单里自动汇总配料,同名食材自动合并累加(三道菜都要葱,清单里就一条「葱」)。清单项还能按食材分类归组、勾选划掉
  • 多人/多家庭:Group(组)+ Household(家庭)两级结构,一家人共用一个菜谱库,各自的购物清单分开
  • 完整 REST API:/docs 自带 Swagger 文档,能查菜谱、能写菜谱,可接 Home Assistant 之类的外部系统
  • 登录集成:内置账号、LDAP、OIDC 三种(OIDC 正好接第 20 期那个 Pocket ID)
  • Webhook:把当天菜单定时推给你指定的 URL(详见「告警/通知配置」)
  • 内置备份与恢复:/admin/backups 一键导出整库 zip,也支持上传恢复
  • AI 扩展(可选):接 OpenAI 兼容端点后可以自动整理导入的菜谱,配 yt-dlp 还能从做菜视频里转录出菜谱

不干什么

  • 不是万能的中文菜谱抓取器。抓菜谱靠的是站点自己声明的结构化数据,国内下厨房、豆果这类站点基本不写 JSON-LD,实测多数抓不全甚至抓不到。中文菜谱主要靠手动录,或者录一次以后一直复用
  • 不做营养计算。没有内置营养数据库,不会告诉你这顿多少卡路里
  • 不做社区和分享。它是自家的库,不是菜谱社区。想公开分享得自己另外搞
  • 不是笔记工具。随手记的碎片内容归第 7 期 Memos,Mealie 只认「菜谱」这个结构
  • 不做告警。它不会主动提醒你「今晚做什么」——那是下面通知那一节要自己接的活

部署前准备

项 说明
镜像 ghcr.io/mealie-recipes/mealie(官方 GitHub 容器仓库,文档统一推荐)。Docker Hub 上另有一个 hkotel/mealie(维护者个人命名空间的历史镜像),官方文档已不再推荐,认准 GHCR
tag 规则 没有滚动 tag。实测 tag 列表里 v3、v3.28 都不存在,只有完整版本号和 latest;且 latest 与 v3.28.0 的 manifest digest 完全相同。本期钉 v3.28.0,别用 latest——官方原话是「 consciously updating to newer versions when you have time to read the release notes」
平台 linux/amd64、linux/arm64。不支持 32 位 ARM(官方明确警告,构建依赖限制),树莓派要装 64 位系统
端口 容器内 9000(APP_PORT 预设 9000,HOST=0.0.0.0)。宿主侧官方示例用 9925,随便改
数据卷 /app/data/——SQLite 数据库、菜谱图片、备份包、.secret / .session_secret 全在这里,一个卷搞定
基础镜像 python:3.14-slim,有 shell、有 curl、自带 ffmpeg(处理菜谱视频用)。不像本系列某些 scratch 镜像那样 docker exec 进不去
内存 官方建议显式限制 1000M。Python 在内存大的机器上会预分配超出实际需要的量,不限制会白白占着
默认凭据 changeme@example.com / MyPassword(官方文档 Step 4 明确给出)
数据库 SQLite(默认,1~20 人够用)或 PostgreSQL(并发多、要模糊搜索时换)

docker run 一行版

docker volume create mealie-data

docker run -d \
  --name mealie \
  --restart unless-stopped \
  -p 9925:9000 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -e BASE_URL=http://192.168.31.193:9925 \
  -e ALLOW_SIGNUP=false \
  -v mealie-data:/app/data/ \
  --memory 1000m \
  ghcr.io/mealie-recipes/mealie:v3.28.0

几个选择的原因:-e TZ=Asia/Shanghai——默认是 UTC,不改的话菜单日期、每日任务时间全错位;BASE_URL——默认 http://localhost:8080,不改的话邮件邀请链接和 OIDC 回调会指向一个谁也访问不到的地址;ALLOW_SIGNUP=false——本来就是默认值(v1.4.0 之后改的),显式写出来是提醒自己别手滑开开;--memory 1000m——官方 compose 里用 deploy.resources.limits,docker run 没有对应参数,用 --memory 达到同样效果;PUID/PGID——默认 911,改成你宿主上实际的用户 ID,备份打包时权限好处理(用 id 你的用户名 查)。

国内拉 GHCR 慢的话,可以挂镜像加速前缀,但别改掉镜像名本身,否则以后升级会对不上。

docker-compose 推荐版

SQLite 版(一个人或一家人用,官方推荐的大多数场景):

services:
  mealie:
    image: ghcr.io/mealie-recipes/mealie:v3.28.0
    container_name: mealie
    restart: always
    ports:
      - "9925:9000"
    deploy:
      resources:
        limits:
          memory: 1000M
    volumes:
      - mealie-data:/app/data/
    environment:
      ALLOW_SIGNUP: "false"
      PUID: 1000
      PGID: 1000
      TZ: Asia/Shanghai
      BASE_URL: https://mealie.example.com

volumes:
  mealie-data:

PostgreSQL 版(多人共用、要模糊搜索、或者数据目录放在 NAS 上):

services:
  mealie:
    image: ghcr.io/mealie-recipes/mealie:v3.28.0
    container_name: mealie
    restart: always
    ports:
      - "9925:9000"
    deploy:
      resources:
        limits:
          memory: 1000M
    volumes:
      - mealie-data:/app/data/
    environment:
      ALLOW_SIGNUP: "false"
      PUID: 1000
      PGID: 1000
      TZ: Asia/Shanghai
      BASE_URL: https://mealie.example.com
      DB_ENGINE: postgres
      POSTGRES_USER: mealie
      POSTGRES_PASSWORD: 换成强密码
      POSTGRES_SERVER: postgres
      POSTGRES_PORT: 5432
      POSTGRES_DB: mealie
      SQLITE_MIGRATE_JOURNAL_WAL: "false"
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:17
    container_name: mealie-postgres
    restart: always
    volumes:
      - mealie-pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: 换成强密码
      POSTGRES_USER: mealie
      PGUSER: mealie
      POSTGRES_DB: mealie
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 30s
      timeout: 20s
      retries: 3

volumes:
  mealie-data:
  mealie-pgdata:

两处 POSTGRES_PASSWORD 必须一致(Mealie 连库的和 Postgres 自己的)。depends_on 配 service_healthy 是关键——不加的话 Mealie 可能在 Postgres 还没准备好时就冲上去连,启动失败。

配置项逐项解释

参数 默认值 为什么这么写
PUID / PGID 911 容器内进程的 uid/gid。入口脚本检测到以 root 启动时会把内部用户改成这两个 ID 并 chown -R /app,然后降权运行。不设就是 911,宿主上看到的备份文件属主会是 911,不方便。填你自己的 uid(id 命令查)
TZ UTC 必须改。影响菜单日期、每日任务时间(DAILY_SCHEDULE_TIME)、备份时间戳。国内填 Asia/Shanghai
BASE_URL http://localhost:8080 必须改。邮件邀请链接、密码重置链接、OIDC 回调地址都基于它。默认那个 localhost:8080 根本没人能访问
ALLOW_SIGNUP false 是否允许任何人自助注册。默认关,公网部署务必保持关——要加人用管理员发邀请链接
ALLOW_PASSWORD_LOGIN true 显示用户名密码输入框。只有完全切到 OIDC 登录时才关,否则把自己锁在外面
DB_ENGINE sqlite sqlite 或 postgres。装完之后不要随便切——官方是靠备份/恢复功能在两个引擎之间迁移的,直接改这个变量不会帮你搬数据
POSTGRES_* 见上 只有 DB_ENGINE=postgres 时才读。也可以用 POSTGRES_URL_OVERRIDE 直接给整条连接串
SQLITE_MIGRATE_JOURNAL_WAL false 把 SQLite 日志模式切成 WAL,提高并发读写能力。有并发冲突或存储后端特殊(比如 Ceph)时开
TOKEN_TIME 48 登录会话有效小时数,上限 9600(400 天)。家里用默认够了,公网部署建议缩短
DEFAULT_GROUP / DEFAULT_HOUSEHOLD Home / Family 初始化时创建的组和家庭名,可以改成中文
API_PORT 9000 Docker 部署不要动它(官方文档原话)。容器内监听端口,要改宿主端口改 ports 映射即可
API_DOCS true 是否开放 /docs 的 Swagger 文档页。公网部署建议关
DAILY_SCHEDULE_TIME 23:45 每日后台任务(含菜单 webhook 推送)的执行时间,按服务器本地时间算,不是 UTC
LOG_LEVEL info 排障时临时改 debug,看完改回来(debug 日志量大)
SECURITY_MAX_LOGIN_ATTEMPTS / SECURITY_USER_LOCKOUT_TIME 5 / 24 连续输错 5 次密码锁账号 24 小时。家里人记性差的话可以适当放宽
SMTP_HOST 等 6 项 全空 想用邮件邀请/密码重置就得配齐:SMTP_HOST、SMTP_PORT(默认 587)、SMTP_FROM_NAME、SMTP_FROM_EMAIL、SMTP_AUTH_STRATEGY(TLS/SSL/NONE)。缺任意一项邮件功能直接不可用
OIDC_AUTH_ENABLED 等 关闭 接第 20 期 Pocket ID 时开:OIDC_CONFIGURATION_URL + OIDC_CLIENT_ID + OIDC_CLIENT_SECRET 三项即可。同机部署还要看 HTTP_ALLOW_LIST(Mealie 默认禁止服务端请求内网地址,自家 IdP 在内网需要显式放行)
SCRAPER_PROXY_URL / SCRAPER_FLARESOLVERR_URL 空 抓菜谱被网站拦截时的进阶手段。默认不开:Mealie 本身已经会轮换浏览器的 TLS 指纹来伪装,多数站点够用
*_FILE 后缀变量 无 POSTGRES_*、SMTP_*、LDAP_*、OIDC_* 这几类都支持写 XXX_FILE=/run/secrets/xxx,从文件读值(Docker Secrets 玩法),避免密码出现在 docker inspect 里

1Panel 面板怎么搞

先说结论:1Panel 应用商店目前没有收录 Mealie(我核对过 1Panel 官方 appstore 仓库的应用清单,3859 个条目里没有它——同类的 Beszel、Portainer、Jellyfin 都在,Mealie 不在)。所以走自定义编排,步骤:

  1. 容器 → 编排 → 创建编排:名称填 mealie,把上面 SQLite 版(或 Postgres 版)的 compose 贴进去,BASE_URL 改成你实际的访问地址
  2. 端口冲突先改宿主端口:9925 被占了就把 ports 左边改成 9926 之类,容器内的 9000 不要动
  3. 防火墙放行:1Panel 的「主机 → 防火墙」放行对应的宿主端口;华为云 ECS 还要单独去云控制台的安全组里放行(这是最容易漏的一步,1Panel 放行不等于云安全组放行)
  4. 起容器后看日志:编排页面点进容器看日志,出现 Generating Default User 之后就是起来了
  5. 反向代理(可选):1Panel 的「网站 → 反向代理」建一条指向 127.0.0.1:9925,然后在「证书」页签申请 Let's Encrypt。配好之后回 compose 里把 BASE_URL 改成 https 域名并重启容器,否则邮件链接还是 http 的

1Panel 用户额外要注意一点:如果要把 /app/data 放到 1Panel 管理的数据盘上,务必同时把数据库切成 Postgres。SQLite 放在网络存储(NFS/SMB 挂载)上会锁库甚至损坏,这是官方明写的警告,不是玄学。

首次访问

浏览器打开 http://服务器IP:9925,用官方默认凭据登录:

用户名:changeme@example.com
密码:  MyPassword

登录后系统会判定这是「首次登录」(后台接口 /api/app/about/startup-info 会检测 changeme@example.com 这个账号是否还在),引导你改掉默认账号。这一步不是可选的:只要这个默认账号还在,系统就一直认为你没完成初始化。改法是进用户设置改邮箱和密码,或者干脆新建自己的管理员账号、把 changeme 那个删掉。

起来之后的界面:左侧是菜谱库(卡片墙 + 搜索/筛选),顶部有 Meal Planner(周菜单)和 Shopping List(购物清单)两个入口,右侧齿轮进设置。

这里有个坑必须提前说:网上大量老教程(v1/v2 时代)会让你在 compose 里写 DEFAULT_EMAIL=你的邮箱 和 DEFAULT_PASSWORD=你的密码 来预置管理员。在 v3.28.0 上这两个环境变量已经完全无效了——源码里它们叫 _DEFAULT_EMAIL / _DEFAULT_PASSWORD(mealie/core/settings/settings.py 第 283、288 行),带下划线前缀是 pydantic 的私有属性,根本不参与环境变量解析。官方文档的 checklist 那一页还留着这两行,是没跟着代码更新的过时内容。v3 的正确做法就是上面写的:默认凭据登录,然后在向导里改。

最小可用配置

装完能登进去就算可用,但要真正用起来,按顺序做这五件事:

  1. 改掉默认账号(上一节已说,这是第一位的)
  2. 确认 ALLOW_SIGNUP 是 false,要加家人就走「管理 → 邀请」生成邀请链接
  3. 导第一个菜谱:Recipe → Create → 选 Import by URL,粘一个英文菜谱站(比如 BBC Food、Serious Eats)的链接,看着它把配料和步骤自动填好——这一步是 Mealie 最爽的瞬间,先体验一次你就知道它值不值
  4. 手动录一个家常菜:中文菜谱基本都得这么来。配料一行一条(盐 3 克),步骤分行写。录一次以后就是永久资产
  5. 排一次周菜单:Meal Planner 里把菜谱拖进格子,然后去 Shopping List 看自动合出来的采购清单

日常最高频的三个页面就是菜谱库(找)、Meal Planner(排)、Shopping List(买)。移动端是响应式网页,手机上 Safari「添加到主屏幕」就近似一个 App,全家都能用同一个地址。

告警/通知配置

先把话说直:Mealie 没有告警系统——它不会提醒你「今晚的菜还没做」。它有的三类「往外推消息」的能力,按场景选:

需求 方案
每天把当天菜单推到手机 内置 Webhook:Household 设置 → Webhooks → 新建,类型目前只有 mealplan 一种,填 URL 和推送时间(按 UTC 填,这跟 DAILY_SCHEDULE_TIME 用本地时间是两回事,别搞混),页面上有 Test 按钮可以直接触发一次验证
菜单推到微信/钉钉/ntfy Webhook 接到第 19 期的 n8n,由 n8n 转成对应渠道;只要推手机推送的话,n8n 里一个 HTTP 节点打给第 13 期 ntfy 就行
邀请家人/重置密码要发邮件 配齐 6 个 SMTP_* 变量(见配置项表格)。不配的话只能靠管理员手动改密码,家里就两三个人可以忍,人多了会很烦
想知道 Mealie 自己挂没挂 第 1 期 Uptime Kuma 加一条 HTTP 探测 http://IP:9925/;容器挂了自动拉起靠 compose 里的 restart: always

Webhook 那个 Test 按钮值得单独提一句:配完一定按一次,看接收端有没有收到。它还能「Rerun」重放当天已排定的推送,排障时不用等到第二天。

反向代理与 HTTPS

Mealie 是普通的 HTTP 服务,没有 WebSocket 之类的特殊要求,反代配置很标准。以第 2 期 Nginx Proxy Manager 为例:Proxy Host 转发到 127.0.0.1:9925,SSL 页签申请 Let's Encrypt 证书并打开 Force SSL。

原生 nginx 配置:

server {
    listen 443 ssl;
    server_name mealie.example.com;
    # ssl_certificate / ssl_certificate_key 略

    # 传大图(菜谱照片)时放宽请求体限制
    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:9925;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

两件配套的事别忘了:

  • 改 BASE_URL:上 HTTPS 域名之后,回到 compose 把 BASE_URL 改成 https://mealie.example.com 并重启容器。不改的话邮件邀请链接还是老地址
  • client_max_body_size:菜谱照片上传走普通请求体,默认 1M 会不够用,20M 足够

如果只在家用、不上公网,那 BASE_URL 填 http://192.168.x.x:9925 就行,不必折腾证书。

踩坑清单

  1. 设了 DEFAULT_EMAIL / DEFAULT_PASSWORD 没生效——v3 起这两个是代码里的私有常量(_DEFAULT_EMAIL / _DEFAULT_PASSWORD),环境变量改不了。用默认凭据 changeme@example.com / MyPassword 登录后改(官方文档 checklist 那一页还写着这两个变量,是过时内容)
  2. 登录进去一直提示"首次登录"——只要 changeme@example.com 这个账号还存在于库里,/api/app/about/startup-info 就一直返回 is_first_login: true。要么改掉这个账号的邮箱,要么新建管理员后删掉它
  3. SQLite 数据目录放在 NAS 上,用着用着报 locked / 数据损坏——官方原话:SQLite 不是为网络存储设计的。放 NAS 就换 Postgres,或者把数据放本地盘再用备份工具同步
  4. 邮件邀请/重置密码发出去的链接点开是 localhost:8080——BASE_URL 没改。改完要重启容器才生效
  5. 抓中文菜谱站抓出来是空的——Mealie 靠站点声明的 schema.org 结构化数据抓取,国内站点普遍不写。中文菜谱手动录,或者用它的 OpenAI 兼容接口辅助整理
  6. 升级后登录态全掉了——容器启动时会生成 SECRET / SESSION_SECRET 并写进 /app/data/.secret 和 .session_secret。只要 /app/data 这个卷还在就不会变;卷重新建了就会全掉(所有人重新登录)
  7. 内存占得莫名的高——Python 在大内存机器上会预分配。按官方建议加 memory: 1000M 限制
  8. 菜单日期/每日任务时间对不上——TZ 默认 UTC。设 Asia/Shanghai。注意 DAILY_SCHEDULE_TIME 是本地时间,而 Webhook 的推送时间是 UTC,两者不是一套
  9. 32 位 ARM 装不起来——官方不支持。树莓派装 64 位系统(Raspberry Pi OS 64-bit)再装
  10. 把 9925 直接暴露公网还没改默认密码——默认凭据是公开的,扫描器盯着这类端口。至少做到:改密码 + 反代 HTTPS + ALLOW_SIGNUP=false;更稳的是只走内网/VPN
  11. 想从 SQLite 换 Postgres,改了 DB_ENGINE 结果数据没了——引擎切换不是改变量就完事。正确路径是导出备份 → 改配置 → 恢复备份(备份包格式与引擎无关,官方专门做了这件事)

备份

方案一:内置导出(推荐日常用)

Settings → Admin Settings → Backups,或者直接访问 /admin/backups。页面能新建备份、下载、上传、恢复。导出的是一个 zip,里面含数据库内容和菜谱图片。

恢复前必须知道三件事:这是破坏性操作,会清空现有数据库;不可撤销;恢复成功后会被登出,重新登录才算完成。另外跨大版本恢复可能失败,出错时日志会告诉你是哪一段(比如 shopping-list),可以下载 zip 改 database.json 把那一段删掉再恢复。

方案二:整卷打包(官方称为「best way」)

SQLite 部署下所有数据都在 /app/data/ 里,停容器打包最干净:

docker stop mealie
docker run --rm -v mealie-data:/app/data -v $PWD:/backup alpine \
  tar czf /backup/mealie_data_$(date +%F).tar.gz -C /app/data .
docker start mealie

这个包里连 .secret / .session_secret 都在,恢复到新机器上登录态都能保住。

Postgres 部署的额外一步:用内置恢复功能时需要临时给 Mealie 的库账号提权,恢复完再收回来:

ALTER USER mealie WITH SUPERUSER;
-- 在网页里执行恢复
ALTER USER mealie WITH NOSUPERUSER;

原因是恢复过程会做大量删除并临时切换角色。忘了这步会看到恢复失败。

不管哪种方案,备份文件别只留在同一台机器上——接第 21 期 Kopia 同步一份到对象存储,才叫备份。

小结

适合谁:家里做饭、菜谱散落在收藏夹和短视频里的人;想按周排菜单并自动出采购清单的;一家人要共用同一个菜谱库的;喜欢「数据在自己手里」这件事的自托管玩家(菜谱这种东西一旦录进去就是长期资产,放在别人的服务器上风险太大)。

不适合谁:主要吃中文菜谱站、指望粘贴链接就自动导入的(结构化数据缺失,得手动录,会失望);想要营养计算、卡路里统计的(没有这个能力);只是想找个地方记两笔做菜心得的(第 7 期 Memos 更轻);一个人吃饭、一周也做不了两顿的(杀鸡用牛刀)。

一句话定位:它是「家里的菜谱数据库」,不是「菜谱收藏夹」也不是「美食社区」——把菜谱从别人服务器上的一段 HTML,变成你自己能查、能改、能排、能算采购的结构化数据,这就是它的全部价值。

项目地址

  • GitHub:https://github.com/mealie-recipes/mealie(AGPL-3.0,13.5k stars,最新 release v3.28.0,2026-09-24 发布,仓库每天都在 push)
  • 官网与文档:https://docs.mealie.io(安装文档里的 SQLite / Postgres 两份 compose 可直接抄)
  • 镜像:ghcr.io/mealie-recipes/mealie:v3.28.0
  • 1Panel:应用商店未收录,走「容器 → 编排」贴 compose 自建