Fork Recipes 介绍与选型指南

目标：面向需要在自有服务器上搭建家庭/个人食谱管理（recipe manager）的用户，梳理 Fork Recipes（mikebgrep/fork.recipes 前端 + mikebgrep/forkapi 后端）的项目定位、前后端分离架构、功能特性与官方部署形态，并与同类开源方案 Mealie、Tandoor、Recipya 做量化选型对比。本文为认知篇，项目事实来自官方仓库源码、GitHub API、官方文档站与 Docker Hub 的联网实查（查询日期均为 2026-11-01），并已在本机 Ubuntu 24.04 + Docker Compose 环境完成部署实测（详见本专栏部署篇）。

一、环境信息

本文为「联网溯源 + 本地实测」混合认知篇，取证信息源与关键环境如下：

取证日期：2026-11-01
前端仓库：https://github.com/mikebgrep/fork.recipes（HTML/Python，创建于 2024-11-21，最近推送 2026-08-17，星数 69，BSD-3-Clause）
后端仓库：https://github.com/mikebgrep/forkapi（Python，创建于 2024-09-08，最近推送 2026-08-13，星数 14，BSD-3-Clause）
版本信息：GitHub Releases API 实查——前端最新 v.4.1.1-Hot-fix（2025-04-28），后端最新 v.6.1.1.Hot-fix（2025-04-28）
官方文档站：https://mikebgrep.github.io/forkapi/latest/（Installation / Clients / REST references）
交付形态：后端官方 Docker 镜像 mikebgrep/forkapi（Docker Hub，amd64 约 2.96 GB、另有 arm64 变体）；前端镜像 forkrecipes:latest 由仓库 Dockerfile 本地构建；官方提供 4 份 docker-compose 文件（postgres / postgres-ssl / sqlite / sqlite-ssl）
本地实测环境：Ubuntu 24.04 宿主机 + Docker Compose v2，前端 8146、API 8148、PostgreSQL 17（127.0.0.1:5434），fork.recipes v.4.1.1-Hot-fix + forkapi v.6.1.1.Hot-fix 镜像

二、软件概述

Fork Recipes 是一个开源的自托管食谱管理 Web 应用，官方 README 的一句话定位是 "Manage your food recipes with simplicity"——把散落在收藏夹、截图、纸质卡片里的菜谱集中到一个可搜索、可分类、可计划、可购物的私有库里（来源：mikebgrep/fork.recipes README，查询日期 2026-11-01）。

它由两个仓库组成、以「前后端分离」方式交付：

forkapi（后端）：Python Django + Django REST Framework 构建的 REST API 服务，自带一个基于 django-jazzmin 美化的管理后台（Admin Panel），负责食谱/分类/标签/用户/计划/购物单的全部数据与业务逻辑；
fork.recipes（前端）：另一个独立的 Django 应用（服务端渲染 Web UI），登录后通过 REST API 调用 forkapi，面向日常浏览器使用；官方文档明确它是「可与 API 无缝配合的现成 Web 客户端」（来源：forkapi 仓库 README 与 forkapi-docs/docs/clients.md，查询日期 2026-11-01）。

⚠️ 名称辨析（易混淆，选型前先认清）：本项目与商业闭源 App **Fork（forkrecipes.com）**没有代码或组织关系，只是名字与图标（餐叉）撞车；也与 PHP 内容管理系统 **Fork CMS（forkcms/forkcms）**无关。Fork Recipes 是 mikebgrep 个人发起的 BSD-3-Clause 项目，技术栈为 Python/Django——网上部分自托管目录把三者混为一谈，检索资料时注意以仓库地址为准。

💡 技术拓展：「食谱数据入库方式」不止抓取一种，常见四类对比——

方式原理代表/取舍
手工录入表单逐项填食材/步骤全系统支持，最慢但最干净
URL 结构化解析抓网页解析 schema.org Recipe JSON-LD/微数据 Mealie、Tandoor、Recipya 内置，免费但依赖站点标注质量
LLM 抓取把网页原文交给大模型抽取成结构化食谱 Fork Recipes 的路线（需 OpenAI API Key），对无标注的网页也有效，按 token 计费
批量导入从 Paprika/Chowdown/JSON 等既有系统迁移 Mealie/Tandoor 支持广，Fork Recipes 靠备份快照

本文主角 Fork Recipes 的抓取走 LLM 路线（api/recipe/scrape 由 OpenAI 模型完成），这是它与 Mealie/Tandoor 最大的机制差异，详见第七章选型对比。

方式	原理	代表/取舍
手工录入	表单逐项填食材/步骤	全系统支持，最慢但最干净
URL 结构化解析	抓网页解析 schema.org Recipe JSON-LD/微数据	Mealie、Tandoor、Recipya 内置，免费但依赖站点标注质量
LLM 抓取	把网页原文交给大模型抽取成结构化食谱	Fork Recipes 的路线（需 OpenAI API Key），对无标注的网页也有效，按 token 计费
批量导入	从 Paprika/Chowdown/JSON 等既有系统迁移	Mealie/Tandoor 支持广，Fork Recipes 靠备份快照

项目关键事实（均为 2026-11-01 实查）：

许可证：前后端均 BSD-3-Clause——宽松许可，无 AGPL/GPL 的网络传染性，商用二开无开源义务；
维护形态：单人维护（作者 mikebgrep），发布节奏集中在 2025 年 2—4 月（前端 v0.3.2→v.4.1.1 共 10 个 release，后端 v4.1.0→v.6.1.1 共 5 个 release），2025-04-28 后无新版本但 master 分支 2026-08 仍有推送，处于「活跃维护、低频发版」状态；
社区规模：前端 69★/4 fork/1 open issue，后端 14★/0 fork/0 open issue——相对 Mealie（13.7k★）、Tandoor（8.7k★）是小众项目，选型需把「社区兜底能力」计入风险（见第六章）。

三、核心架构

从两仓库源码与官方 compose 文件归纳（源码实查日期 2026-11-01），完整形态由 4 个进程 + 2 个数据库组成：

组成部分	说明	载体
nginx 入口	官方 nginx/Dockerfile 构建，双 server 块：80 端口走前端 socket、81 端口走 API socket（本地无域名部署时把 81 映射出去即 API/管理后台入口）	镜像 `nginx:fork-recipes`（基于 nginx:latest）
forkapi 后端	Django 5.x + DRF，uwsgi 以 unix socket `/tmp/uwsgi/uwsgi.sock` 暴露；启动时先跑 `scripts/migration.sh`（makemigrations/migrate/collectstatic，可选 seed）	官方镜像 `mikebgrep/forkapi:latest`
fork.recipes 前端	独立 Django 应用（SSR 模板 + 静态资源），uwsgi socket `/tmp/uwsgi/uwsgi_recipes.sock`；服务端用 requests 库把 `SERVICE_BASE_URL` 拼成 API 调用	由前端仓库根 Dockerfile 构建 `forkrecipes:latest`（python:3.12-slim）
数据层	后端二选一：SQLite（`DEPLOYMENT_TYPE=sqlite`，零外部依赖）或 PostgreSQL（`postgres://user:pass@ip:port/forkrecipes` 连接串，经 dj-database-url 解析）；前端另有自己的小 SQLite 只存会话与用户镜像	后端库 + `sql/db.sqlite3`

架构要点与推论：

认证链路是「代理式」的：浏览器 → 前端 Django 会话（SESSION_COOKIE_AGE 24 小时）→ 前端持 DRF Token 调后端。登录页提交邮箱/密码，前端调 POST api/auth/token 换取 token 存入 session（源码 fork_recipes/recipes/views.py 与 ws/api_request.py，实查 2026-11-01）。此外后端还有一类只读端点可用环境变量 X_AUTH_HEADER 定义的自定义请求头直接访问（供第三方脚本免登录读取，来源：forkapi README）。
前后端通过 unix socket + 共享卷衔接：三容器间不暴露 TCP 端口，nginx 靠 uwsgi_data 共享卷里的两个 .sock 文件转发；be/web 用 network_mode: "host"，API 出口即宿主机网络——这意味着 SERVICE_BASE_URL 必须写成宿主机可达地址（如 http://192.168.x.x:8148），这是部署最容易踩的接线坑。
管理后台与 Web UI 是两个界面：forkapi 自带 jazzmin 管理面板（用户、分类、食谱全量 CRUD 与备份快照管理），前端 Web UI 面向日常浏览；官方明确前端没有注册入口，新增用户要在后端管理面板操作（来源：forkapi-docs/docs/clients.md 第 4 步说明，查询日期 2026-11-01）。
AI 能力是外挂的：URL 抓取、按食材生成食谱、翻译、语音朗读全部经后端 background_jobs_app 调 OpenAI API（OPENAI_API_KEY/OPENAI_MODEL/OPEN_AI_TTS_MODEL_VOICE 三个变量控制），不配 Key 时核心食谱管理不受影响。
镜像体积偏大：mikebgrep/forkapi 镜像约 2.96 GB（Docker Hub 实查），大头是内置的 Playwright 浏览器依赖（官方文档注明镜像已含抓取依赖、无需手工安装）；对家庭 NAS 场景这是显著的磁盘成本。

💡 技术拓展：「前后端分离」在自托管食谱系统里有三种落地形态对比——

形态代表特点
单体全栈 Recipya（Go+HTMX）一个二进制/容器，运维最简
单服务 + SPA Mealie（FastAPI+Vue）后端一个容器带静态资源，API 与 UI 同源
双服务分离 Fork Recipes（前端 Django + 后端 Django）两套独立代码库与进程，API 可单独复用给移动端，代价是部署件数多、接线复杂

Fork Recipes 选择双服务分离，是为了让 REST API 独立演进（官方文档有专门的 first-request/REST references 章节），但自托管用户要为此多维护一个前端容器与一条 SERVICE_BASE_URL 接线。

形态	代表	特点
单体全栈	Recipya（Go+HTMX）	一个二进制/容器，运维最简
单服务 + SPA	Mealie（FastAPI+Vue）	后端一个容器带静态资源，API 与 UI 同源
双服务分离	Fork Recipes（前端 Django + 后端 Django）	两套独立代码库与进程，API 可单独复用给移动端，代价是部署件数多、接线复杂

四、功能特性

以下特性来自前后端 README、源码路由表（api/auth|recipe|schedule|shopping|backupper 五大域）与官方文档实查（2026-11-01）：

食谱全要素管理：图片/视频两类食谱、食材与步骤分表建模、收藏、分类（category）与标签（tag）双维度组织、随机推荐（api/recipe/random）、趋势（api/recipe/trending）、分页搜索；
打印布局：紧凑/扩展两种打印版式（前端 README 明示，适合贴厨房）；
膳食计划（Meal Plan）：内置排期器，把食谱安排到日期（api/schedule 域）；
购物清单：从食谱食材一键加入购物清单（api/shopping 域）；
AI 四件套（需 OpenAI Key）：URL 抓取成谱、按现有食材生成食谱、多语言翻译（含同一食谱的多语言变体管理 api/recipe/<pk>/variations）、英文语音朗读（TTS，10 种音色可选）；
备份快照：api/backupper 域支持整库快照导出/导入/应用（含媒体文件），是官方给的迁移与容灾通道；
多用户：后端有注册接口（api/auth/signup）与管理面板用户管理，前端登录入口只走已有账号；密码找回走 SMTP（EMAIL_* 变量，非硬依赖，不用找回功能可不配）；
REST API 开放：token 认证写操作 + X_AUTH_HEADER 头认证只读，便于脚本批量导入导出；
ARM 支持：官方提供 mikebgrep/forkapi:arm64 镜像，README 明确面向 Raspberry Pi。

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

官方推荐路径是 fork.recipes 仓库的 compose.sh 一键起三服务（nginx + 后端 + 前端），数据库用 SQLite 时零外部依赖。官方最小步骤（来源：forkapi-docs/docs/Installation.md 与 compose.sh 源码，实查 2026-11-01）：

git clone --branch v.4.1.1-Hot-fix https://github.com/mikebgrep/fork.recipes.git
cd fork.recipes
cp .env.example .env        # 填 DJANGO_SECRET / X_AUTH_HEADER / SERVICE_BASE_URL
chmod +x compose.sh
./compose.sh up             # 按 DEPLOYMENT_TYPE 选 compose 文件；sqlite 分支有 bug，见下方提示

⚠️ 本地实测坑（2026-11-01 复现）：compose.sh 的 sqlite 分支引用 docker-compose-sqlite.yaml（.yaml 后缀），而仓库实际文件是 docker-compose-sqlite.yml（.yml 后缀），直接执行报 open /opt/data/quzuo/tmp/fork-recipes/deploy/fork.recipes/docker-compose-sqlite.yaml: no such file or directory；脚本的版本检测只匹配 version v2，对本机 Docker Compose v5.6.1 会误判回退到已不存在的 docker-compose 命令。稳妥做法是绕过脚本、直接 docker compose -f docker-compose-postgres.yml up -d（详见本专栏排错 FAQ 篇）。

实测记录（本机 Ubuntu 24.04，2026-11-01，PostgreSQL 形态，前端 8146 / API 8148）：

启动后四容器稳态（docker ps 回显）：

nginx            Up   0.0.0.0:8146->80/tcp, 0.0.0.0:8148->81/tcp
recipes          Up
forkapi          Up
fork-recipes-db  Up   127.0.0.1:5434->5432/tcp

后端启动时自动跑迁移与种子数据（scripts/migration.sh + SEED_DEFAULT_DATA=true），日志回显 Admin user created: admin@example.com，并写入 3 个演示分类（Greek🌮 / Italian🍝 / Mexican🌶️）；
浏览器打开 http://192.168.1.172:8146 出现 Fork Recipes 登录页，用种子账号 admin@example.com / ChangeMe 登录成功（302 → 主页正常渲染）；
API 链路验证：POST http://192.168.1.172:8148/api/auth/token（必须带 X-Auth-Header 自定义头）换取 DRF token；用 token 读回 3 个种子分类，新建「中式」分类（pk=4）、创建「西红柿炒蛋」食谱（pk=1，multipart 带图片）、挂 2 条食材与步骤并关联分类，全部成功；PostgreSQL 侧核对计数 recipe_recipe=1、ingredient=2、分类 4 个，图片经 http://127.0.0.1:8148/media/images/..._tomato.png 返回 HTTP 200；
备份快照实测：POST api/backupper/ 返回 201 ["Successfully created backup file: backups/fork_recipes_2026.11.01_14.50.35.zip"]，zip 内含 data.json 与食谱图片，PATCH 恢复返回 204——官方备份/迁移通道可用；
后端管理面板 http://192.168.1.172:8148/admin（django-jazzmin）同源可达，未登录访问 302 跳转 /login/?next=/admin/，同一账号可管理用户、分类与备份快照。

完整部署流程（compose 自加 PostgreSQL 服务、nginx 监听改造、前端镜像构建的 Debian 版本坑与网络降级）见本专栏《Fork Recipes Docker Compose 部署指南》。

六、适用场景与限制

适用场景：

家庭私有食谱库 + 愿意用 AI 抓取：LLM 抓取对无结构化标注的菜谱网页成功率高，配一个 OpenAI Key 即获得「贴 URL 成谱」体验，这是 Mealie/Tandoor 传统解析之外的差异化能力；
想要独立 REST API 的二次开发：前后端分离 + 完整 API 文档，适合自写移动端/小程序对接（官方 first-request 文档即为此准备）；
Raspberry Pi / ARM 家庭服务器：官方 arm64 镜像 + compose 一键部署；
对许可证敏感的闭源集成：BSD-3-Clause 无传染性，二开商用无开源义务。

限制与短板（实查依据：官方文档、源码与仓库数据，2026-11-01）：

社区极小：合计 83★、单人维护、最新 release 停在 2025-04-28——遇到 issue 大概率只能自救，长期维护风险显著高于 Mealie/Tandoor；
无批量导入通道：不支持从 Paprika/Chowdown/Tandoor/Mealie 等既有系统迁移（官方仅有自家 backupper 快照），从别的系统搬家只能走 API 脚本重写；
抓取/生成/翻译/朗读全部依赖 OpenAI：无内置 schema.org 解析器，不配 Key 时「URL 导入」功能整条不可用；
镜像重：后端镜像约 2.96 GB（Playwright 内置），NAS 小磁盘场景要掂量；
前端无注册、无移动端官方 App：多用户添加必须进后端管理面板；
官方 compose 的接线细节多：network_mode: host、双 uwsgi socket、SERVICE_BASE_URL 必须用宿主机可达地址、本地无域名需手改 nginx 监听端口——官方文档自己都标注了「这是本地部署才需要的改法」（clients.md「Read for local deploy without domain name」一节），上手门槛高于单容器方案；
已知工程瑕疵：仓库 compose.sh 对 sqlite 类型引用 docker-compose-sqlite.yaml（.yaml 后缀），而仓库实际文件是 .yml 后缀，直接执行会报文件不存在（本地实测复现，见本专栏排错 FAQ 篇）。

七、同类选型对比

量化数据均为 GitHub API 于 2026-11-01 实查：

维度	Fork Recipes	Mealie	Tandoor	Recipya
仓库	mikebgrep/fork.recipes + forkapi	mealie-recipes/mealie	TandoorRecipes/recipes	reaper47/recipya
技术栈	Python Django 双服务 + uWSGI/nginx	Python FastAPI + Vue	Python Django + Angular	Go + HTMX 单体
星数	69 + 14	13,761	8,707	412
fork / open issues	4 + 0 / 1 + 0	1,624 / 131	893 / 394	24 / 68
许可证	BSD-3-Clause	AGPL-3.0	自定义（LICENSE.md，API 标 NOASSERTION）	GPL-3.0
创建时间	2024-09 / 2024-11	2020-12	2019-11	2021-05
最新 release	v.4.1.1-Hot-fix（2025-04-28）	v3.30.0（2026-10-31）	2.7.2（2026-10-27）	v1.2.2（2024-12-20）
发版节奏	集中 2025 上半年，此后静默	高频（近乎周更）	高频	2024 年底后停更
URL 抓取	需 OpenAI Key（LLM 抽取）	内置（schema.org 解析）	内置 + 浏览器插件剪藏	内置
数据库	SQLite / PostgreSQL	SQLite / PostgreSQL	PostgreSQL	SQLite
部署件数	3 容器（nginx+BE+FE）±外部 PG	1 容器 ±外部 DB	2 容器 + 外部 PG	1 容器/二进制
特色	AI 生成/翻译/TTS、独立 REST API、arm64	最全能：多租户/组权限/OIDC SSO	购物清单生态、插件、模板导入	极轻量单二进制

上表关键差异解读：Mealie/Tandoor 的星数与发版频率代表「社区兜底 + 长期维护」优势，且抓取零外部依赖；Fork Recipes 的独占价值在 BSD 许可 + 独立 API + LLM 抓取/生成/TTS，代价是社区规模小两个数量级、镜像大、抓取要烧 OpenAI token；Recipya 轻量但已停更，不建议新项目采用。

「如果…则…」选型建议：

如果追求功能全、生态大、长期维护，选 Mealie（接受 AGPL）或 Tandoor（接受自定义许可 + 必须 PostgreSQL）；
如果你的菜谱网页大量无结构化标注、且已有 OpenAI Key，愿意用 LLM 换抓取成功率，Fork Recipes 是少数原生方案；
如果你要给自研 App 找食谱后端（API 优先、许可宽松），Fork Recipes 的双仓库分离架构与 BSD 许可比 AGPL 的 Mealie 更适合闭源集成；
如果是树莓派 + 家庭局域网的轻量场景且不想折腾接线，Fork Recipes（arm64 官方镜像）或 Recipya 都比 Tandoor 省资源，但 Recipya 停更风险需自担。

八、参考链接

前端仓库：https://github.com/mikebgrep/fork.recipes
后端仓库：https://github.com/mikebgrep/forkapi
官方文档站（Installation/Clients/REST）：https://mikebgrep.github.io/forkapi/latest/
Docker Hub 镜像：https://hub.docker.com/r/mikebgrep/forkapi
同类项目：Mealie https://github.com/mealie-recipes/mealie ；Tandoor https://github.com/TandoorRecipes/recipes ；Recipya https://github.com/reaper47/recipya
自托管目录条目（星数/资源画像参考）：https://selfhostindex.com/app/fork-recipes/