chomptron

Chomptron

由 AI 驱动的食谱生成器，使用 Google Gemini AI 将食材转化为美味食谱。部署在 Google Cloud Run，网址为 chomptron.com。

功能介绍

输入厨房里现有的食材，Chomptron 就会生成创意又实用的食谱，包含用量、操作步骤、烹饪时间和份量。

本地开发

npm install
export GEMINI_API_KEY="your-api-key-here"
export GEMINI_MODEL="gemini-3.1-flash-lite"  # Optional, defaults to gemini-3.1-flash-lite
npm start

访问 http://localhost:8080

获取 API 密钥：https://makersuite.google.com/app/apikey

环境变量

• GEMINI_API_KEY（必需）- 你的 Google Gemini API 密钥
• GEMINI_MODEL（可选）- 要使用的模型，默认为 gemini-3.1-flash-lite
• PORT（可选）- 服务端口，默认为 8080

模型配置

可以通过 GEMINI_MODEL 环境变量配置 Gemini 模型：

推荐模型（截至 2025 年 12 月）：

• gemini-3.1-flash-lite（默认）- 免费层级额度最高：每分钟 15 次请求，每日 1,000 次请求
• gemini-2.5-flash - 每分钟 10 次请求，每日 250 次请求
• gemini-2.0-flash - 每分钟 10 次请求，每日 200 次请求（⚠️ 配额不稳定，常显示 limit: 0）
• gemini-1.5-flash - 旧版模型，额度可能比 2.0 更高

2025 年 12 月配额调整：

Google 于 2025 年 12 月全面调整了免费层级配额：

• gemini-2.0-flash 已从完全免验证的免费层级中移除
• 许多账号在未启用结算功能时，使用较新的模型会遇到 limit: 0 错误
• 免费层级配额不会每月自动重置

解决“Limit: 0”错误：

如果你遇到 limit: 0 配额错误：

1. 切换到 gemini-2.5-flash-lite - 目前可用的最佳免费层级模型
2. 启用结算（按使用量付费） - 关联信用卡（即使不消费）即可从“受限免费”升级到“第 1 层级”，并解锁承诺的免费配额
3. 检查所在地区 - 欧洲经济区、英国和瑞士的免费层级访问受限
4. 监控用量 - 访问 /api/usage 端点或 https://ai.dev/usage

免费层级额度（截至 2025 年 12 月）：

模型	每分钟请求数	每日请求数	适用场景
gemini-2.5-flash-lite	15	1,000	高请求量应用
gemini-2.5-flash	10	250	通用用途
gemini-2.0-flash	10	200	旧版（不稳定）
gemini-2.5-pro	2	50	复杂推理

测试

npm test

测试验证以下内容：

• 模块化文件结构：验证外部 styles.css 和 app.js 的链接
• CI/CD 与 DevOps：Docker 和 Cloud Build 配置
• API 完整性：健康检查端点（/health、/ready）和食谱生成
• 功能可靠性：食谱历史记录、份量缩放逻辑和收藏功能

API 端点

• GET /health - 存活检查，返回服务状态

• GET /ready - 就绪检查，验证 AI 配置并显示当前模型

• GET /api/usage - 使用统计信息（请求总数、配额错误、模型信息）

• POST /api/generate-recipe - 主要的食谱生成端点

  • 请求正文：

    {
      "ingredients": "chicken, tomatoes, garlic",
      "dietaryPreferences": {
        "vegan": false,
        "vegetarian": false,
        "glutenFree": false,
        "dairyFree": false,
        "nutFree": false,
        "shellfishFree": false,
        "eggFree": false,
        "soyFree": false
      }
    }
    

  • 响应：

    {
      "success": true,
      "recipe": "**Recipe Name:** ...",
      "cached": false
    }
    

• POST /mcp — MCP Streamable HTTP。工具 generate_recipe（食材 + 可选的饮食标记）。无需身份验证。每日上限为 MCP_DAILY_RECIPE_LIMIT（默认值为 20），并持久化到 MCP_BUDGET_FILE，因此同一实例上的进程重启不会重置上限。

架构

Chomptron 在 Google Cloud Run 上构建为无服务器应用，以提高成本效益并实现自动扩缩。

技术栈：

• 后端： Node.js 24 + Express
• AI： Google Gemini（可配置模型，默认为 gemini-3.1-flash-lite）
• 前端： 模块化原生 HTML/CSS/JavaScript（关注点清晰分离）
• 存储： 使用浏览器 localStorage 存储食谱历史记录
• 平台： Google Cloud Run（无服务器）
• CI/CD： Cloud Build
• 域名： chomptron.com

为什么选择无服务器？

• 空闲时自动缩至零 → 成本为 0 美元（而传统托管每月需 5–50 美元）
• 根据流量自动扩缩，实例数可从 0 增至 1000+
• 无需维护——无需管理、修补或配置服务器
• 非常适合 AI 工作负载——可高效处理突发流量和计算密集型食谱生成

性能优化：

• 内存缓存： 每个实例的食谱缓存（TTL 为 24 小时，最多缓存 100 个食谱）
• 结构化食谱解析： 提取食谱组成部分，便于更好地展示和扩展
• 客户端速率限制： 防止过多的 API 调用
• 智能重试逻辑： 通过指数退避机制妥善处理配额错误

使用指南

生成食谱

1. 在文本区域输入食材
2. （可选）选择饮食偏好／过敏项
3. 点击“生成食谱 ✨”
4. 查看结构化食谱，其中包括：
   • 食谱名称和元数据
   • 可调整份量的食材列表
   • 分步说明
   • 烹饪技巧

食谱功能

• 调整份量： 使用 +/- 按钮调整份量（0.25x 至 4x）
• 评价食谱： 点击星星为食谱评分（1–5 星）
• 添加备注： 在备注栏中输入个人备注
• 收藏： 点击星形按钮收藏食谱
• 打印： 点击打印按钮，查看适合打印的页面
• 分享： 点击分享按钮，生成可分享的 URL

食谱历史记录

• 点击 📚 按钮（右上角）打开食谱历史记录
• 按名称、食材或内容搜索食谱
• 按收藏状态筛选
• 将所有食谱导出为 JSON 或文本
• 点击任意食谱即可重新加载

深色模式

• 点击 🌙 按钮（左上角）切换深色／浅色模式
• 偏好设置会自动保存

监控

健康检查：

curl https://chomptron.com/health
curl https://chomptron.com/ready
curl https://chomptron.com/api/usage  # View usage statistics

查看日志：

# Recent logs
gcloud run logs read chomptron --region us-central1 --limit 50

# Live stream
gcloud run logs tail chomptron --region us-central1

控制台仪表板：

• Cloud Run 服务
• Cloud Build 历史记录
• Artifact Registry

功能

核心功能

• ✨ 使用 Google Gemini 生成 AI 驱动的食谱
• 🍳 富有创意的食谱名称和说明
• 📏 精确的用量和份量
• ⏱️ 烹饪时间估算（准备、烹饪、总时间）
• 🎨 现代视觉美感：采用玻璃拟态设计，并搭配错落的入场动画
• 🔠 优质字体：使用 Outfit 和 Inter 字体，营造现代感
• ⚡ 在 Google Cloud Run 上运行的无服务器自动扩缩基础设施

食谱管理

• 📚 食谱历史记录，使用 localStorage 持久化保存（最多 100 道食谱）
• ⭐ 收藏系统，可标记和筛选喜爱的食谱
• 🔍 搜索和筛选已保存的食谱
• 💾 将食谱导出为 JSON 或文本格式
• 📋 通过侧边栏面板快速访问以前的食谱
• 📝 为每道食谱添加个人备注
• ⭐ 使用 5 星评分系统为食谱评分

食谱自定义

• 🥗 饮食偏好和过敏原：纯素、素食、无麸质、无乳制品、无坚果、无贝类、无蛋、无大豆
• 📊 食谱缩放：将份量调整为 0.25x 至 4x，并自动缩放食材用量
• 🖨️ 适合打印的视图：简洁的打印布局，针对食谱打印进行了优化
• 🔗 可分享的 URL：为食谱生成可分享的链接（支持 Web Share API）

食谱展示

• 📋 结构化食谱格式：解析并按条理展示各个部分：
  • 食谱名称
  • 份量和时间信息
  • 食材列表
  • 分步说明
  • 烹饪技巧
• 🎨 深色／浅色模式：切换主题，并持久保存偏好设置

性能与优化

• 💾 食谱缓存：内存缓存可减少相似食材组合的 API 调用
• 🔄 智能重试逻辑：遇到配额错误时自动采用指数退避策略重试
• ⚡ 速率限制：客户端速率限制可防止过多的 API 调用

技术特性

• 🔍 健康监控和就绪检查
• 🔎 针对 SEO 进行了优化，包含元标签、Open Graph、Twitter Cards 和结构化数据
• 📱 支持 PWA，包含 manifest.json
• 🤖 提供 robots.txt 和 sitemap.xml，供搜索引擎编入索引

食谱数据结构

食谱存储在浏览器的 localStorage 中，结构如下：

{
  "id": "timestamp",
  "ingredients": "chicken, tomatoes, garlic",
  "recipe": "Full recipe text...",
  "recipeName": "Extracted recipe name",
  "timestamp": "2025-01-01T00:00:00.000Z",
  "favorite": false,
  "rating": 0,
  "notes": "",
  "servingSize": 4,
  "dietaryPreferences": {
    "vegan": false,
    "vegetarian": false,
    "glutenFree": false,
    "dairyFree": false,
    "nutFree": false,
    "shellfishFree": false,
    "eggFree": false,
    "soyFree": false
  }
}

缓存策略

应用在服务端使用内存缓存：

• 缓存键：标准化食材 + 饮食偏好
• TTL：24 小时
• 最大容量：每个实例 100 道食谱
• 范围：按实例划分（无服务器实例是临时的）
• 优势：减少命中同一实例的相似请求所产生的 API 调用

SEO 功能

通过元标签、Open Graph、Twitter Cards、结构化数据（JSON-LD）、sitemap、robots.txt 和 PWA 支持，针对搜索引擎和社交分享进行了优化。

Buildkite 流水线

此仓库包含位于 .buildkite/pipeline.yml 的 Buildkite 流水线，该流水线在由 buildkite-gcp-agent 配置的可自托管 GCP Agent 上运行。

流水线结构

Push / PR
  └── Three steps dispatched in parallel:
        ├── :prettier: Format check   (npm run format -- --check)
        ├── :eslint:   Lint           (npm run lint)
        └── :nodejs:   Tests          (npm test)
  └── Annotate — consolidated pass/fail surfaced in the Buildkite UI

与 GitHub Actions 工作流按顺序在单个作业中运行 format → lint → test 不同，这三个步骤彼此没有依赖关系，会同时运行。在 Agent 池中，这种方式可以分散工作；即使只有一个 Agent，明确的依赖关系图也能清晰表达意图，并让流水线轻松扩展。

此处有意省略部署阶段——Cloud Run 部署由现有的 GHA 工作流处理，该工作流持有生产环境的 GCP 凭据。CI（快速反馈）和 CD（生产环境访问）分属不同系统，以此作为安全边界。

流水线设置

通过 Buildkite → New Pipeline 连接仓库，并指向 github.com/swantron/chomptron。Buildkite 会在每次推送时自动读取 .buildkite/pipeline.yml。

Agent 目标队列

所有步骤都在 gcp 队列上运行：

agents:
  queue: gcp

贡献

这是一个个人项目，但欢迎提出建议和改进！

许可证

MIT