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

痛点开场
先看看菜谱到底是怎么丢的:
- 链接会死。收藏的菜谱过半年再点开,要么 404、要么网站改版、要么跳到「登录/下载 App 查看完整菜谱」。你收藏的不是菜谱,是别人服务器上的一段 HTML
- 视频菜谱没法用。做菜的时候手上有油有水,不可能举着手机拖进度条找「盐放多少来着」。短视频平台的内容天生不适合在厨房里消费
- 改过的配比记不住。照着菜谱做过一次,糖减半、多加一勺醋,下次想复现全靠回忆
- 采购清单要手抄。周末想做三道菜,得把三份配料表摊开,自己合并去重,再一条条写进备忘
- 家里别人看不到。你收藏的东西在你手机上,家里做饭的另一个人完全不知道
Mealie 的答案很朴素:把菜谱从外面搬进自己的数据库——标题、配料(数量 + 单位 + 食材分开存)、步骤、图片、标签、分类,全是结构化字段;然后挂到一周七天的格子(Meal Planner)上,系统自动把这几天的配料合并成一张购物清单。数据在你自己服务器上,链接死不死跟你没关系了。

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

- 周菜单(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 不在)。所以走自定义编排,步骤:
- 容器 → 编排 → 创建编排:名称填
mealie,把上面 SQLite 版(或 Postgres 版)的 compose 贴进去,BASE_URL改成你实际的访问地址 - 端口冲突先改宿主端口:9925 被占了就把
ports左边改成 9926 之类,容器内的 9000 不要动 - 防火墙放行:1Panel 的「主机 → 防火墙」放行对应的宿主端口;华为云 ECS 还要单独去云控制台的安全组里放行(这是最容易漏的一步,1Panel 放行不等于云安全组放行)
- 起容器后看日志:编排页面点进容器看日志,出现
Generating Default User之后就是起来了 - 反向代理(可选):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 的正确做法就是上面写的:默认凭据登录,然后在向导里改。
最小可用配置
装完能登进去就算可用,但要真正用起来,按顺序做这五件事:
- 改掉默认账号(上一节已说,这是第一位的)
- 确认
ALLOW_SIGNUP是 false,要加家人就走「管理 → 邀请」生成邀请链接 - 导第一个菜谱:Recipe → Create → 选 Import by URL,粘一个英文菜谱站(比如 BBC Food、Serious Eats)的链接,看着它把配料和步骤自动填好——这一步是 Mealie 最爽的瞬间,先体验一次你就知道它值不值
- 手动录一个家常菜:中文菜谱基本都得这么来。配料一行一条(
盐 3 克),步骤分行写。录一次以后就是永久资产 - 排一次周菜单: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 就行,不必折腾证书。
踩坑清单
- 设了
DEFAULT_EMAIL/DEFAULT_PASSWORD没生效——v3 起这两个是代码里的私有常量(_DEFAULT_EMAIL/_DEFAULT_PASSWORD),环境变量改不了。用默认凭据changeme@example.com/MyPassword登录后改(官方文档 checklist 那一页还写着这两个变量,是过时内容) - 登录进去一直提示"首次登录"——只要
changeme@example.com这个账号还存在于库里,/api/app/about/startup-info就一直返回is_first_login: true。要么改掉这个账号的邮箱,要么新建管理员后删掉它 - SQLite 数据目录放在 NAS 上,用着用着报 locked / 数据损坏——官方原话:SQLite 不是为网络存储设计的。放 NAS 就换 Postgres,或者把数据放本地盘再用备份工具同步
- 邮件邀请/重置密码发出去的链接点开是 localhost:8080——
BASE_URL没改。改完要重启容器才生效 - 抓中文菜谱站抓出来是空的——Mealie 靠站点声明的 schema.org 结构化数据抓取,国内站点普遍不写。中文菜谱手动录,或者用它的 OpenAI 兼容接口辅助整理
- 升级后登录态全掉了——容器启动时会生成
SECRET/SESSION_SECRET并写进/app/data/.secret和.session_secret。只要/app/data这个卷还在就不会变;卷重新建了就会全掉(所有人重新登录) - 内存占得莫名的高——Python 在大内存机器上会预分配。按官方建议加
memory: 1000M限制 - 菜单日期/每日任务时间对不上——
TZ默认 UTC。设Asia/Shanghai。注意DAILY_SCHEDULE_TIME是本地时间,而 Webhook 的推送时间是 UTC,两者不是一套 - 32 位 ARM 装不起来——官方不支持。树莓派装 64 位系统(Raspberry Pi OS 64-bit)再装
- 把 9925 直接暴露公网还没改默认密码——默认凭据是公开的,扫描器盯着这类端口。至少做到:改密码 + 反代 HTTPS +
ALLOW_SIGNUP=false;更稳的是只走内网/VPN - 想从 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 自建