RecipeSage 4.1.1 配置参数详解

目标：把 RecipeSage 4.1.1 selfhost 形态的配置面一次讲透——配置的唯一权威载体是 compose 文件的 x-common-env 锚点段（无 .env、无挂载配置文件），本文按"必改 / 可选改 / 勿改"三层给出全量参数语义、生效方式与实测闭环。所有参数名与默认值逐字取自 2026-10-29 版官方 compose 与实测环境（Ubuntu 24.04.5 / Docker 29.9.2 / RecipeSage v4.1.1，宿主端口 8162，实测日期 2026-11-02）。部署步骤见站内文章 《RecipeSage Docker Compose 部署指南》。

一、环境信息

二、前置条件

1. 已按《RecipeSage Docker Compose 部署指南》跑通六服务栈（docker compose -p recipesage ps 六行 Up）。
2. 对 compose 文件有编辑权限；改参前建议 cp docker-compose.yml docker-compose.yml.bak。
3. 本文实测闭环均在 api 服务上演示（docker compose -p recipesage up -d api 重建约 20–30 秒，含迁移与索引步骤，api 就绪前访问会短暂 502，属正常）。

三、参数查看与修改方式

3.1 配置面全景（三层）

3.2 查看当前生效值

grep -n 'API_PUBLIC_BASE_URL' docker-compose.yml

实测回显：

6:  API_PUBLIC_BASE_URL: http://127.0.0.1:8162/api # Local evidence deployment: host+port with /api suffix

运行时侧可用欢迎页反查（见 3.3）。⚠️ 无 docker compose config 之外的图形化配置界面——Web 管理后台的设置项（如账户偏好）存数据库，属用户数据而非部署配置。

3.3 改参 → 重建 → 验证闭环（实测）

selfhost 没有热加载：改 compose 后须重建对应服务。以 API_PUBLIC_BASE_URL 为例，欢迎页的 openapi 链接由该变量渲染，是现成的"配置生效探针"。

第一步，改参（127.0.0.1 → localhost）：

sed -i 's#API_PUBLIC_BASE_URL: http://127.0.0.1:8162/api#API_PUBLIC_BASE_URL: http://localhost:8162/api#' docker-compose.yml
docker compose -p recipesage up -d api

实测回显（compose 检测到 api 配置变化，仅重建 api）：

 Container recipesage_postgres Healthy 
 Container recipesage_api Starting 
 Container recipesage_api Started 

第二步，验证欢迎页联动（等待约 25 秒 api 就绪后）：

curl -s http://127.0.0.1:8162/api/ | grep -o 'href="[^"]*"'

改参前实测回显：

href="/stylesheets/style.css"
href="http://127.0.0.1:8162/api/openapi.json"
href="https://docs.recipesage.com/api/"

改参后实测回显（openapi 链接随变量变为 localhost）：

href="/stylesheets/style.css"
href="http://localhost:8162/api/openapi.json"
href="https://docs.recipesage.com/api/"

第三步，回滚验证：把 compose 改回原值再 up -d api，欢迎页恢复 href="http://127.0.0.1:8162/api/openapi.json"（实测通过）。

💡 技术拓展：selfhost 配置注入不止"compose 内联"一种——

形态	特点	适用
compose 内联 x-common-env（本文）	单一文件、版本可控、无隐藏状态	官方推荐，多数场景
.env 文件 + ${VAR} 插值	敏感值与 compose 分离，可 gitignore	需保密 DB 密码/AI key
secrets/外部 KMS	运行时注入，不落盘	生产多节点

RecipeSage 官方选了最简的内联形态；若你要隐藏密钥，compose 原生支持 KEY: ${KEY} 插值读取宿主环境变量或同目录 .env，语义等价。

四、参数总览

x-common-env 全量 19 键（默认值即 2026-10-29 版 compose 原文）：

api 服务注入层 21 键（勿改清单）：ENVIRONMENT/NODE_ENV=selfhost、VERSION=selfhost、NODE_OPTIONS=--max-old-space-size=400、MALLOC_ARENA_MAX=2、FILESYSTEM_STORAGE_PATH=/rs-media、STORAGE_TYPE=filesystem、VERBOSE=false、POSTGRES_HOST=postgres、POSTGRES_PORT=5432、POSTGRES_SSL=false、POSTGRES_LOGGING=false、DATABASE_SSL=false、GRIP_URL=http://pushpin:5561/、JOB_QUEUE_REDIS_HOST=valkey、STRIPE_SK/GCM_KEYPAIR/SENTRY_DSN/STRIPE_WEBHOOK_SECRET 置空。

总览解读：selfhost 把"能改的"全部收进锚点段 19 键，其余以注入层锁死——真正需要运维介入的只有 API_PUBLIC_BASE_URL、DB 四件套与 AI 组；NODE_OPTIONS 是唯一的内存调节旋钮（见 5.7 的注意事项）。

五、核心参数分类详解

5.1 对外基址（唯一必改项）

API_PUBLIC_BASE_URL：实例对外 API 基址，必须以 /api 结尾（compose 原注释："Do not remove the '/api' suffix"）。它决定欢迎页/openapi 链接、前端请求基址与导出下载 URL 的拼接前缀。

• 本机验证：http://127.0.0.1:8162/api（本实测值，3.3 节闭环验证）
• 生产域名：https://recipesage.example.com/api（外部反代指向 proxy 容器 80，路径 /api/ 透传）

实测踩坑：漏 /api 后缀或端口与实际访问地址不一致时，注册/建谱等 API 全通但前端功能异常、图片 404（见部署篇 FAQ Q2）。

5.2 数据库组（四件套联动）

POSTGRES_DB/POSTGRES_USER/POSTGRES_PASSWORD 同时被三处消费：postgres 服务初始化、DATABASE_URL 连接串、以及 postgres healthcheck（compose 里写死 pg_isready -d recipesage_selfhost -U recipesage_selfhost）。

⚠️ 改这三项必须同步手改两处：DATABASE_URL（锚点段注释明示）与 healthcheck 的 -d/-U 参数——漏改 healthcheck 会导致 postgres 永远不 healthy、api 永不启动。另外已建库后改 DB 名/用户不会迁移旧数据（postgres 镜像只在全新数据卷执行 initdb），改后等于换了一个空库。

POSTGRES_HOST/PORT/SSL、DATABASE_SSL 等在注入层，selfhost 网络内固定 false/5432，勿动。

5.3 实时推送组

GRIP_KEY：api 与 pushpin 的共享签名密钥。pushpin 容器 entrypoint 用 sed 把 /etc/pushpin/pushpin.conf 的 sig_key=changeme 替换为该值（compose 原文可见）。pushpin 只在 docker 内网暴露，官方注释"可以不改"；若要改，api 与 pushpin 两个服务都要重建（同锚点，up -d api pushpin 即可）。GRIP_URL=http://pushpin:5561/ 在注入层勿改；浏览器侧 WS 入口是 nginx 的 /grip/ws。

5.4 队列/缓存组

JOB_QUEUE_REDIS_HOST=valkey（注入层）：导出 job、AI 解析任务等异步队列指向 valkey 服务（BullMQ 风格）。实测导出闭环时 api 日志出现 Starting processing job 2 with EXPORT.jsonld → Finished processing job 2 → Job queue has drained（见部署篇 6.5）。valkey 镜像官方未钉 tag，生产建议显式钉版本（如 valkey/valkey:8）。

5.5 AI 组（决定 selfhost 功能面）

系统级密钥不落 compose 明文的做法（compose 原生插值）：

x-common-env: &common-env
  AI_API_KEY: ${OPENROUTER_API_KEY}

export OPENROUTER_API_KEY=<你的key>   # 放宿主环境或 systemd 环境文件，勿提交进 git
docker compose -p recipesage up -d api

实测提醒：AI 组只影响抓取/解析类功能，手动建谱、购物清单、协作、导出等核心链路零 AI 依赖（部署篇 6.2–6.5 全程未配 key 跑通）。

5.6 购物清单分类器

GROCERY_CATEGORIZER_URL：条目自动分类服务地址，默认走 RecipeSage 公有 API。compose 底部注释提供本地替代服务 julianpoy/grocery-categorizer:f9d9562——资源密集且 CPU 需 AVX 指令集，启用时取消注释并把本值改为 http://grocery-categorizer:8000/。CLI categorizeShoppingListItems 即调用此服务（实测回显 Categorization complete!，见 CLI 篇）。

5.7 资源与存储（注入层，知其所以然）

• NODE_OPTIONS=--max-old-space-size=400：api 进程 V8 堆上限 400MB，实测 api 常驻 516.7MiB（堆+外部内存）。小内存机器想调低可以改此值，但官方标注勿改——调过低会导致大食谱批量导出 OOM；
• MALLOC_ARENA_MAX=2：限制 glibc malloc arena，压 RSS；
• STORAGE_TYPE=filesystem + FILESYSTEM_STORAGE_PATH=/rs-media：图片/导出产物落 named volume；S3/MinIO 形态需改注入层并启用 nginx /minio/ 路由，selfhost 不建议动。

六、生产配置模板

场景 A：家庭 NAS/2GB 内存小机器（HTTP 本机访问）——官方默认值即可跑（实测 616MiB 常驻），仅改两处：

x-common-env: &common-env
  API_PUBLIC_BASE_URL: http://192.168.1.20:8162/api
  POSTGRES_PASSWORD: <强随机密码>
  DATABASE_URL: postgresql://recipesage_selfhost:<强随机密码>@postgres:5432/recipesage_selfhost
  # 同步改 postgres healthcheck: pg_isready -d recipesage_selfhost -U <新用户名>

场景 B：公网域名 + TLS + AI 抓取（4GB+ 内存、≥20GB 磁盘含 3.5GB 镜像）：

x-common-env: &common-env
  API_PUBLIC_BASE_URL: https://recipesage.example.com/api
  GRIP_KEY: <随机 32 位>
  POSTGRES_DB: recipesage
  POSTGRES_USER: recipesage
  POSTGRES_PASSWORD: ${RS_PG_PASSWORD}
  DATABASE_URL: postgresql://recipesage:${RS_PG_PASSWORD}@postgres:5432/recipesage
  AI_PROVIDER: "openrouter"
  AI_API_KEY: ${OPENROUTER_API_KEY}
  SCRAPFLY_API_KEY: ${SCRAPFLY_API_KEY}

外部 nginx 只需转发 recipesage_proxy:80（含 /grip/ws 的 WS Upgrade）；RS_PG_PASSWORD/OPENROUTER_API_KEY/SCRAPFLY_API_KEY 由宿主环境注入（export 或 systemd EnvironmentFile=/etc/recipesage/env，文件权限 600），compose 不落明文。磁盘占用大头是 api 镜像 3.21GB + apimedia 卷增长。

七、常见问题（FAQ）

Q1： 改了 POSTGRES_PASSWORD 后 api 连不上库？ A： DATABASE_URL 内嵌了同一密码，必须同步改；只改一处会出现"库起来了、api 认证失败"。

Q2： 改 DB 名/用户后 postgres 一直不 healthy、api 不启动？ A： healthcheck 的 pg_isready -d/-U 参数写死旧值，需同步改（见 5.2）。

Q3： 改完 compose 没生效？ A： selfhost 无热加载，必须 docker compose -p recipesage up -d <受影响服务> 重建；锚点变量被 api/pushpin/postgres 三方共享，拿不准就 up -d 全栈（数据在卷里，重建不丢数据）。

Q4： 欢迎页 openapi 链接还是旧地址？ A： 说明 api 未重建成功，docker compose -p recipesage logs api 看是否卡在迁移；用 3.3 节的 grep 探针命令核对。

Q5： 配了 AI_API_KEY 后 clip 仍 400？ A： 确认 AI_PROVIDER 与 key 的渠道匹配（默认 openrouter 格式模型名）；Cloudflare 保护的站点还需 SCRAPFLY_API_KEY，最稳路径仍是浏览器扩展（见 5.5）。

Q6： example.env 里的 AWS_/STRIPE_ 要不要配？ A： 不要。那是源码仓库开发环境配置；selfhost 的 STRIPE/Sentry/GCM 在注入层显式置空（compose 注释 "Value should not be set."）。

Q7： 想换 redis 替代 valkey？ A： 队列走纯 Redis 协议，把 valkey 服务镜像换成 redis:7.2 即可（JOB_QUEUE_REDIS_HOST 是服务名不用动）；但官方默认 Valkey 是许可证考虑（见部署篇第二节拓展）。

八、参考链接

• 官方 compose 与注释（配置权威来源）：https://github.com/julianpoy/RecipeSage-selfhost
• 配置与 AI key 指引：https://docs.recipesage.com
• 源码仓库（example.env、packages/*）：https://github.com/julianpoy/RecipeSage
• 同专栏：部署见 《RecipeSage Docker Compose 部署指南》，CLI 见《RecipeSage 4.1.1 常用 CLI 命令与工具详解》

取证说明：本文参数名/默认值逐字核对自 RecipeSage-selfhost 2026-10-29 版 compose 与 v4.1.1 实测环境；改参→重建→验证→回滚闭环于 2026-11-02 实测（宿主端口 8162）。