Recipya v1.2.2 常用 CLI 命令与工具详解
Recipya v1.2.2（Go 版）命令与工具链实测：recipya 二进制仅 serve 无 --version、compose 运维与升级、三层备份（自动 cron zip/卷 tar/SQLite 冷拷+WAL 陷阱）、恢复删 -shm/-wal、URL/文件/远程集成/书签四条导入通道与 JSON/PDF 导出（WS type:file 下发）、Reports 审计与 curl 无头自动化速查。
Recipya v1.2.2 常用 CLI 命令与工具详解
目标：给 Recipya v1.2.2（Go 版，reaper47/recipya）的命令行与工具链建立完整操作手册——
recipya二进制 CLI、compose 运维命令、卷级/应用级备份恢复、SQLite 数据文件操作、导入导出工具链（URL/文件/远程集成/JSON-PDF 导出）的实测用法。全部命令在/opt/data/quzuo/tmp/recipya/的 8163 端口容器上实测（取证记录evidence.md）。
一、recipya 二进制 CLI：一个命令的极简界面
Recipya 基于 urfave/cli v2，但只注册了一个业务命令。容器内实测：
docker exec recipya-1.2.2-evidence /app/recipya --help
NAME:
recipya - the ultimate recipes manager for you and your family
USAGE:
recipya [global options] command [command options]
COMMANDS:
serve, s starts the web server
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--help, -h show help
docker exec recipya-1.2.2-evidence /app/recipya serve --help
# USAGE: recipya serve [command options]
# OPTIONS: --help, -h show help ← 无任何配置 flag
要点（v1.2.2 源码 main.go 实查）：
| 事实 | 说明 |
|---|---|
仅 serve/s 一个命令 | 镜像 ENTRYPOINT 即 /app/recipya s，容器启动=serve |
无 --version | 全局选项只有 --help；查版本看镜像 tag（注意 v1.2.2 镜像内部自报 1.3.0 的不一致，见配置篇注记） |
| 无子命令做数据操作 | 没有 migrate/backup/import 之类 CLI——一切运维走 HTTP API（UI 背后那组路由）或文件操作 |
| 配置零 flag 化 | 参数只来自 config.json / RECIPYA_* env（见配置篇） |
结论：Recipya 的"CLI 篇"实际是 compose + HTTP API + 卷文件三套工具的组合，二进制本身只提供 serve。
二、compose 运维命令集
cd /opt/data/quzuo/tmp/recipya
# 启停
docker compose up -d # 启动/重建
docker compose stop / start # 停止/启动容器（不改配置）
docker compose restart # 改 config.json 后生效用这个
docker compose down # 移除容器与网络（命名卷数据保留）
# 观察
docker compose logs -f recipya # stdout：启动校验、goose 迁移、"Serving HTTP server at address ..."
docker ps --filter name=recipya # 端口映射核对：0.0.0.0:8163->8078/tcp
docker exec -it recipya-1.2.2-evidence sh # alpine shell，进卷看数据
启动日志判读（实测）：
Fetching the FDC database (62.6 MB) ← 首启下载营养库（仅一次）
Environment variables ok ← env 校验通过
OK FFmpeg is installed ← 视频功能可用（镜像内置 6.1.2）
Recipya is properly set up
File locations: ... ← 五个数据目录
2026/11/01 21:07:33 OK 20221227180503_init.sql ... ← goose 迁移 21 个
Serving HTTP server at address http://0.0.0.0:8078
升级
官方文档路径（compose）：
docker compose pull # 先备份卷！（§三）
docker compose up -d # 用新镜像重建容器
官方另推荐 Watchtower 单发更新（实测环境未装，命令存档）：
docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock \
containrrr/watchtower --run-once recipya
Go 版现实：稳定版停在 v1.2.2（2024-12），升级选项实际是 v1.2.2 → nightly 或按官方指南迁 Rust 版（recipya-rs，支持 PostgreSQL），迁移前务必全量备份。
三、备份：三层工具链
3.1 应用自动备份（内置 cron）
源码 internal/jobs/jobs.go：每 3 天两类备份，各留 10 份（约一个月滚动）。实测首启即生成全局备份：
docker exec recipya-1.2.2-evidence ls /root/.config/Recipya/Backup/global/
# recipya.2026-11-01.zip
docker exec recipya-1.2.2-evidence sh -c 'cd /tmp && cp /root/.config/Recipya/Backup/global/recipya.2026-11-01.zip . && unzip -l recipya.2026-11-01.zip'
# Recipya/Database/recipya.db
# Recipya/Images/<uuid>.webp
# Recipya/Images/Thumbnails/<uuid>.webp
# Recipya/Logs/recipya.log
# Recipya/Videos/
# Recipya/config.json
用户级备份在 Backup/users/{userID}/：recipes.zip + backup-inserts.sql + backup-deletes.sql（SQL 为该用户食谱的删/插语句，可人工审计）。UI 恢复入口：Settings→Data→Restore from backup 选日期。
3.2 卷级 tar 备份（官方文档命令，跨机迁移首选）
# 备份（宿主机当前目录得到 tar）
docker run --rm --volumes-from recipya-1.2.2-evidence -v $(pwd):/backup \
ubuntu tar cvf /backup/recipya-volume-backup.tar /root/.config/Recipya
# 恢复到同名 volume 的容器
docker run --rm --volumes-from recipya-1.2.2-evidence -v $(pwd):/backup \
ubuntu bash -c "cd /root && tar xvf /backup/recipya-volume-backup.tar --strip 1"
3.3 SQLite 冷备份（手工）
docker compose stop
# 卷名 = <project>_<volume>，实测为 recipya_recipya-data（docker volume inspect 可确认挂载点）
cp -a /var/lib/docker/volumes/recipya_recipya-data/_data /backup/recipya-$(date +%F)
docker compose start
注意：运行中的 recipya.db 是 WAL 模式（实测卷内同时存在 recipya.db、recipya.db-wal 1.2MB、recipya.db-shm），热拷主库文件会丢 WAL 中未落盘事务，务必停容器后拷，或直接取 3.1 的自动备份 zip（应用自己打的快照）。
容器内无 sqlite3 CLI（实测 which sqlite3 → 未安装）；需要查询时宿主装 sqlite3 指向卷文件，或临时 docker run --rm -v recipya_recipya-data:/data alpine sh -c 'apk add sqlite; sqlite3 /data/Database/recipya.db ".tables"'。
3.4 全局备份恢复（官方步骤 + 实测注记）
- 停应用：
docker compose stop - 解压目标备份：
unzip recipya.{Y-M-D}.zip - 用解压出的
Recipya/*覆盖卷内/root/.config/Recipya/ - 删除
Database/recipya.db-shm与recipya.db-wal（陈旧 WAL 与新主库不匹配会导致异常） docker compose start，登录验证食谱数
四、导入工具链（四条路）
所有"重"导入都走 HTTP API 且要求该用户有活动 /ws WebSocket（源码 s.Brokers.Has(userID) 检查，无 WS 一律 400 "Connection lost"）。API 自动化脚本样例见部署篇 §6.3。
| 通道 | 端点/入口 | 输入 | 实测 |
|---|---|---|---|
| URL 抓取 | POST /recipes/add/website（表单 urls，多行） | 396 个优化站点 + 任意 schema.org Recipe JSON-LD 页面 | ✅ recipetineats 单 URL → 202 → toast → /recipes/2（图/料/步骤全量） |
| 文件导入 | POST /recipes/add/import（multipart files，≤512MB） | 10 款 App 导出格式（AccuChef/ChefTap/Crouton/Easy Recipe Deluxe/Kalorio/MasterCook/Paprika/Recipe Keeper/RecipeSage/Saffron）+ Recipya 自家 JSON zip | ✅ 重灌导出 zip → "Imported 0 recipes. 2 skipped"（去重幂等） |
| 远程拉取 | POST /integrations/import（integration/url/username/password） | Mealie / Tandoor / Nextcloud Cookbook 实例直连迁移 | 端点与字段源码实查 |
| 浏览器书签 | Bookmarklet（UI 提供拖拽安装） | 任意食谱页一键剪藏 | UI 级，未做自动化 |
导入结果统一落 Reports（GET /reports，200 实测）：每条 URL/文件的成败与错误原因可审计，批量迁移看这里。
五、导出工具链
5.1 全库导出（Settings→Data 或 API）
GET /settings/export/recipes?type=json|pdf （需 WS；type 非法值 → toast "Invalid export file format"）
实测 JSON 导出闭环：202 受理 → WS 进度帧 Preparing...→Exporting recipes... → 结果以 {"type":"file","fileName":"recipes_json.zip","data":"<base64>"} 帧直接下发（不是下载链接，客户端解码 base64 落盘）。zip 结构：每食谱一个目录 {名称}/recipe.json，内容为 schema.org Recipe 标准 JSON：
{
"@context": "https://schema.org",
"@type": "Recipe",
"recipeCategory": "dinner",
"dateCreated": "2026-11-01",
...
}
这个格式与 Recipya 文件导入、Rust 版迁移双向兼容——跨版本迁移就用它当中间态。PDF 导出为每食谱一个 {名称}.pdf 的 zip（打印排版同源）。
单个 cookbook 下载：GET /cookbooks/{id}/download。
5.2 图片/视频资产
原图在 Images/<uuid>.webp、缩略图 Images/Thumbnails/、视频 Videos/*.webm（FFmpeg 转码，未装 FFmpeg 则视频功能自动禁用）。URL 导入时已实测自动抓取站点图片转 webp 落卷。
六、日志与观测工具
| 源 | 位置/格式 | 说明 |
|---|---|---|
| stdout | docker compose logs | 启动校验/迁移/监听地址，一次性 |
| 应用日志 | 卷内 Logs/recipya.log | slog JSON 行，lumberjack 轮转：500MB×3 份、28 天、gzip 压缩（源码 server.go） |
| 抓取报告 | /reports、/reports/{id} | 导入成败明细（含错误原文） |
| 管理面板 | /admin（首个注册用户即 admin） | 用户增删（POST/DELETE /admin/users）、报告入口 |
排障套路：URL 导入失败先查 /reports?view=latest；反代后 WS 断连（"Connection lost"）查 Upgrade 头透传；配置不生效查 config.json 是否吃掉了 env（配置篇 §一）。
七、无头自动化速查（curl 版）
BASE=http://127.0.0.1:8163
# 1. 登录拿 cookie
curl -s -c cj -X POST -d 'email=admin@recipya.test' -d 'password=Recipya#2026' $BASE/auth/login
# 2. 查食谱列表/搜索
curl -s -b cj "$BASE/recipes/search?q=bolognese" | grep -c Bolognese
# 3. 建 cookbook（注意 HX-Prompt 头）
curl -s -b cj -X POST -H 'HX-Prompt: 我的册子' $BASE/cookbooks
# 4. 导入/导出类操作：必须先开 ws://$BASE/ws（带 session cookie），参考取证脚本 forensics/ws_*.py
八、小结
Recipya 的 CLI 表面"贫瘠"（一个 serve），换来的是运维模型的简单：compose 五板斧 + 每 3 天自动备份 + schema.org JSON 导出导入闭环 + Reports 审计。数据安全的三个硬知识点：WAL 模式别热拷、恢复时删 -shm/-wal、卷 /root/.config/Recipya 就是全部。跨系统迁移路径清晰：Mealie/Tandoor/Nextcloud 走远程拉取，RecipeSage/Paprika 等 10 款走文件导入，出去则用 JSON zip 或 PDF——食谱数据永不锁死在 Recipya 里。