轻量级购物清单管理应用Koffan

简介

什么是 Koffan ？

Koffan是一个免费的开源购物清单应用，专为家庭和情侣设计。它允许多个设备之间实时同步，让多人实时共享同一个购物清单，让每个人都知道该买什么，购物车里已经有哪些。解决了「谁去买」「买了没」「还要买什么」的家庭协作难题。

Koffan的名字来自波兰语kochanie（亲爱的），发音为KOF-fan。

主要特点

• 超轻量：仅16 MB磁盘占用，~2.5 MB内存占用
• 多清单：支持创建多个购物清单（如不同超市、不同用途），可自定义图标
• PWA 应用：可像原生应用一样安装到手机桌面
• 离线模式：无网络时也能添加和编辑商品，自动同步
• 智能补全：基于历史记录的模糊搜索提醒
• 商品分类：按类别组织（如生鲜、日化、冷藏）
• 已购标记：标记已购买的商品
• 不确定模式：标记暂时找不到的商品
• 实时同步：WebSocket实时同步，多设备同时可见
• 响应式界面：移动端优先设计
• 深色模式：跟随系统自动切换
• 多语言支持：支持PL、EN、DE、ES、FR、PT、UK、NO、LT、EL、SK、RU等语言
• 简单登录：只需一个密码，无需复杂注册
• REST API：支持程序化访问和集成
• 开源免费：基于MIT License + Commons Clause开源

应用场景

• 家庭购物：夫妻或家人共用一个清单，一人选购，其他人实时看到进度
• 情侣共享：两个人分工购物，避免重复购买
• ** roommates **：合租人员共同管理生活用品采购
• 春节采购：大家庭春节采购时多人分工

Koffan是一个简单好用的家庭购物协作工具，特别适合不想安装复杂应用只想快速分享清单的用户。

安装

在群晖上以 Docker 方式安装。

Koffan镜托管在ghcr.io，群晖Docker套件无法直接搜索，需要使用命令行安装。

本文写作时，latest版本对应为v2.6.1；

docker cli 安装

如果你熟悉命令行，可能用docker cli更快捷

# 新建文件夹 koffan 和 子目录mkdir-p/volume1/docker/koffan/data# 进入 koffan 目录cd/volume1/docker/koffan# 运行容器dockerrun-d\--restartunless-stopped\--namekoffan\-p3852:80\-v$(pwd)/data:/data\-eAPP_PASSWORD=yourpassword\ghcr.io/pansalut/koffan:latest

环境变量说明：

• APP_PASSWORD：登录密码，默认值为yourpassword，建议修改

• 更多的环境变量请参考官方文档： https://github.com/PanSalut/Koffan#environment-variables

docker-compose 安装

也可以用docker-compose安装，将下面的内容保存为docker-compose.yml文件

version:'3'services:koffan:image:ghcr.io/pansalut/koffan:latestcontainer_name:koffanrestart:unless-stoppedports:-3852:80volumes:-./data:/dataenvironment:-APP_PASSWORD=yourpassword

然后通过SSH登录到您的群晖，执行下面的命令：

# 新建文件夹 koffan 和 子目录mkdir-p/volume1/docker/koffan/data# 进入 koffan 目录cd/volume1/docker/koffan# 将 docker-compose.yml 放入当前目录# 一键启动docker-composeup-d

运行

在浏览器中输入http://群晖IP:3852就能看到登录界面，密码为APP_PASSWORD中设定的值

登录成功后的主界面

点Create shopping list

创建购物清单

进入购物清单

点Add first section开始添加Sections

现在可以开始添加需要购买的物品了

点Add继续添加

老苏随便加了几个

注意事项

1. 修改密码：默认密码过于简单，务必在环境变量中设置强密码
2. 数据备份：数据库文件位于/data/shopping.db，定期备份
3. 多设备同步：添加商品后，其他设备会自动同步，无需手动刷新
4. 隐私安全：数据存储在本地NAS，仅家人可见
5. 密码错误锁定：连续5次密码错误会锁定30分钟，防止暴力破解

参考文档

Koffan: Free shopping assistant - A fast and simple app for managing your shopping list together
地址：https://github.com/PanSalut/Koffan

Koffan Docker Image
地址：https://ghcr.io/pansalut/koffan

Koffan REST API Documentation
地址：https://github.com/PanSalut/Koffan/wiki/REST-API