买菜时最常见的重复，不一定是忘了清单，而是两个人各自以为对方没买。清单在聊天里滚动，菜谱里的材料又没补进去，回家才发现多买了几袋、漏了一样。KitchenOwl 可以把购物清单、菜谱、餐单和家庭成员放在同一个入口，适合先解决一家人如何共同维护清单。
开始不用把全部菜谱都导入。先建一个家庭和一张常用清单，让两台设备分别添加和勾选项目，验证同步与断网后的处理。项目支持部分离线使用，但“部分”很重要，不能假设每个操作在没有网络时都和在线一样。
官方手机图展示清单的使用方式，实际应用版本和翻译可能不同。本文采用自托管服务器，自己的客户端仍需要连接到正确地址，不会因为安装了同名手机应用就自动使用这台 VPS。
部署前先确认 VPS 的磁盘、内存和公网访问条件，也可以查看雨云云服务器；注册时填写优惠码 KuZhuJi。
从官方合并镜像开始
官方提供前后端分开部署，也提供合并镜像。一个小家庭实例先用合并方案，持久数据挂载到 /data。不用为了完成第一张清单就加入外部数据库和更多组件。
mkdir -p ~/services/kitchenowl/data
cd ~/services/kitchenowl
umask 077
printf 'JWT_SECRET_KEY=%s\n' "$(openssl rand -hex 32)" > .env
chmod 600 .env
保存 compose.yaml：
services:
kitchenowl:
image: tombursch/kitchenowl:latest
env_file:
- .env
environment:
OPEN_REGISTRATION: "false"
ports:
- "127.0.0.1:8097:8080"
volumes:
- ./data:/data
restart: unless-stopped
JWT_SECRET_KEY 保存自己的随机值，不照抄 PLEASE_CHANGE_ME。OPEN_REGISTRATION=false 关闭自由注册，首次引导与添加家庭成员按当前版本流程完成。项目仍在开发，正式长期使用前核对版本状态，完成小范围验收后再保存重要资料。
docker compose config --quiet
docker compose up -d
docker compose logs --tail=100 kitchenowl
ssh -L 18097:127.0.0.1:8097 user@your-server
本机打开 http://127.0.0.1:18097，先在私人入口建立首个账号和家庭。完成引导后退出登录，检查注册和未授权访问的实际行为，不只看 .env 里有一个关闭开关。
正式地址同时满足网页和手机
长期使用配置 HTTPS 域名，代理接到宿主机 8097。官方提示代理应支持 WebSocket，并正确设置相关响应头；清单同步和客户端请求都要从实际入口测试。HSTS 在确认 HTTPS 正常后按自己的域名策略设置，避免证书未就绪便使访问受阻。
手机应用填写自己的服务器地址，再登录相应账号。用浏览器与手机分别添加不同名称的测试项目，核对它们出现在同一张清单。两个客户端都能登录，不一定代表连接的是同一实例。
后台仅监听回环地址，域名开放后仍需保护账号。家庭成员使用各自账号，不共享管理员密码；私人清单、饮食习惯与费用信息不适合随意公开截图。
多个设备共同编辑一份服务器数据，原始菜谱和独立备份另存。实时同步会传播删除和修改，不能把手机上也看得到内容称为历史备份。
准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 KuZhuJi。配置按实际任务选择，数据库和附件另做备份。
两个人先约定清单里的名称
同一种食材有几种叫法，容易变成几行重复内容。先选择家里常用的名称与单位，例如按实际采购习惯记录数量，备注里放规格或用途。不要为了统一名称把本来不同的品种合并。
新项目先少量添加，看看搜索与建议是否符合自己的语言习惯。菜谱材料和采购包装不一定相同：需要少量某种调料，不代表必须每次重新买一整瓶。加入清单前检查家里的库存，软件里的建议不自动知道柜子里还剩什么。
勾选项目的含义也要一致。它可以代表已经放进购物车，或者已经买完回家，两种约定会影响对方是否继续购买。清单负责沟通，具体约定由成员先说清楚。
同步要用两台设备走完整过程
设备 A 添加测试项目，设备 B 查看并修改备注，再回到 A 检查。接着用 A 勾选、B 撤销，观察最终状态。测试简单而可辨认的内容，不用真实采购记录练习删除。
弱网下暂时看不见变化时，先确认客户端连接和服务器日志。连续点击可能产生更多操作，反而不好判断最后一项是谁改的。记录客户端版本，应用升级后再做一次同样的小测试。
部分离线能力需要单独验证。让一台设备断网后尝试自己常用的操作，再恢复网络，检查内容是否同步、有没有冲突或丢失。离线浏览可用，不代表新增、编辑和登录全部可用，不据此承诺超市里所有动作都能完成。
需要增加服务器时，可以打开雨云选购页面，填写优惠码 KuZhuJi；迁移前保留数据与原有部署配置。
菜谱导入后核对材料与份数
准备一份自己熟悉的菜谱，尝试当前支持的添加或导入方式，核对名称、材料、步骤和份数。网页来源的格式不同，导入成功也可能遗漏单位或某一段步骤。原网址或自有原稿保留在自己的资料里，便于对照。
把菜谱材料加入清单后，看数量和单位是否符合预期。份数变化影响需求量，但有些材料不能简单按倍数推算采购包装；小样本检查清楚后，再为一周餐单批量添加。
费用与家庭余额功能可以按需使用，不要求首次部署就录入全部财务信息。录入金额时统一币种和口径，支出由原票据对照。功能放在同一软件里，不代表它可以替代正式对账或个人财务系统。
数据和登录密钥一起保存
暂停应用后保存持久数据、环境配置和部署文件：
mkdir -p backups
docker compose stop kitchenowl
tar -czf "backups/kitchenowl-$(date +%F-%H%M%S).tar.gz" data .env compose.yaml
docker compose start kitchenowl
备份转移到服务器之外，保护其中的账号和密钥。恢复采用独立目录与原版本，先核对家庭、清单、菜谱和成员，再用测试设备验证一次同步。原版本升级前保存配套副本，测试客户端不要无意连到正式地址修改真实清单。