ChowTime · 今天吃啥

面向家庭使用的自托管点菜 Web App：维护菜谱和冰箱库存，一起选菜下单，并留下每一餐的记录。

功能

• 菜谱：分类、搜索、新增、编辑、图片上传和下单计数
• 冰箱：食材分类、保质期、临期/过期提醒和关联菜谱推荐
• 点单：购物车、按时间自动选择餐次、备注、订单状态流转、加减菜和评价
• 记录：按订单回看菜单、修改餐次日期与类型、调整菜品数量、成品图、评分、完成时间和删除订单
• AI：兼容 OpenAI API 的菜品/食材识别、菜品介绍补全、视觉建议和菜品配图；未配置时自动回退
• 自托管：单容器运行，SQLite、上传文件和前端静态资源统一交付

界面预览

菜谱	点单	厨房记录

添加菜谱	冰箱	订单详情	AI 设置

Docker Compose 部署

要求：Docker Engine 24+ 和 Docker Compose v2。

1. 准备配置：

   cp .env.example .env
   openssl rand -hex 32
   openssl rand -base64 24

   将两个随机值分别写入 .env 的 JWT_SECRET 和 ADMIN_PASSWORD。不要直接使用示例值。

2. 拉取镜像并启动：

   docker compose pull
   docker compose up -d

3. 检查服务：

   curl http://localhost:8080/healthz
   docker compose ps

浏览器打开 http://localhost:8080，使用 .env 中的 ADMIN_USERNAME / ADMIN_PASSWORD 登录。首次启动会创建家庭账号并加载示例菜谱。Compose 默认只监听本机回环地址；需要从可信局域网访问时，将 CHOWTIME_HOST 改为 0.0.0.0。

升级时运行：

docker compose pull
docker compose up -d

配置

变量	默认值	说明
CHOWTIME_IMAGE	docker.cnb.cool/arbing/chowtime:latest	要运行的镜像标签
CHOWTIME_HOST	127.0.0.1	宿主机绑定地址；局域网访问可显式改为 0.0.0.0
CHOWTIME_PORT	8080	宿主机监听端口
JWT_SECRET	无	必填，至少使用 32 字节随机值
AUTH_BOOTSTRAP_ENABLED	false	是否允许匿名自动登录；只建议本地开发或隔离测试使用
ADMIN_USERNAME	admin	管理员登录名
ADMIN_PASSWORD	无	bootstrap 关闭时必填，至少 12 个字符
MAX_UPLOAD_MB	5	单个上传文件大小上限
AI_BASE_URL	无	OpenAI 兼容 API 基地址，例如 https://api.openai.com/v1
AI_API_KEY	无	Chat/Vision Provider 密钥
AI_CHAT_MODEL	无	支持图像输入的 Chat/Vision 模型
AI_IMAGE_BASE_URL	AI_BASE_URL	可选的图片生成 Provider 基地址
AI_IMAGE_API_KEY	AI_API_KEY	可选的图片生成 Provider 密钥
AI_IMAGE_MODEL	无	图片生成模型；不配置时隐藏配图能力

AI 密钥只保存在服务端环境变量中，不会发送到浏览器。修改 .env 后执行 docker compose up -d 使配置生效。

上传图片使用不可预测 URL 供浏览器直接显示，读取 URL 本身不再校验登录态。若实例需要经公网反向代理访问，请在代理层增加访问控制，不要公开 /uploads/。

数据与备份

SQLite 数据库和上传文件都保存在宿主机 ./data/。做一致性备份时先暂停服务：

docker compose stop
cp -a data data.backup-YYYYMMDD
docker compose start

恢复时停止服务，将备份目录完整替换回 data/，再重新启动。请把备份复制到另一块磁盘或远端存储。

本地开发

要求：Node.js 24、pnpm 10、Go 1.25。

pnpm install
pnpm gen
JWT_SECRET="$(openssl rand -hex 32)" pnpm dev:server

另开终端启动前端：

pnpm dev:web

常用验证命令：

pnpm lint
pnpm test
pnpm build
pnpm test:e2e

pnpm test:e2e 会构建并启动真实生产镜像，执行完整浏览器旅程后自动清理容器和测试数据。

技术栈与结构

• Web：React 19、TypeScript、Vite、TanStack Query、Tailwind CSS
• API：Go、Gin、GORM、SQLite、JWT
• 契约：OpenAPI 3.0，同时生成 Go Server 类型和 TypeScript Client 类型
• 测试：Vitest、Testing Library、MSW、Playwright、Go testing
• 交付：Docker 单镜像、CNB CI/CD 与制品库、GitHub Actions 与 GHCR

api/             # OpenAPI 契约与生成配置
apps/web/        # 正式 Web 应用
apps/server/     # Go API、数据库与静态资源服务
docker/          # 容器入口脚本
e2e/             # 生产真栈测试编排与假 Provider
design/          # 只读视觉参照工程

向 CNB 推送版本 tag 会并行构建 linux/amd64、linux/arm64 镜像，发布到 docker.cnb.cool/arbing/chowtime，并在镜像成功后创建对应 CNB Release。GitHub 上的 v* tag 仍由 GitHub Actions 发布到 GHCR 和 GitHub Release。