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

发表于 分类于 Waline： 阅读次数： 本文字数： 2.1k 阅读时长 ≈ 2 分钟
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 更快捷

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 新建文件夹 koffan 和 子目录
mkdir -p /volume1/docker/koffan/data

# 进入 koffan 目录
cd /volume1/docker/koffan

# 运行容器
docker run -d \
   --restart unless-stopped \
   --name koffan \
   -p 3852:80 \
   -v $(pwd)/data:/data \
   -e APP_PASSWORD=yourpassword \
   ghcr.io/pansalut/koffan:latest

环境变量说明：

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

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

docker-compose 安装

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

1
2
3
4
5
6
7
8
9
10
11
12
13
version: '3'

services:
  koffan:
    image: ghcr.io/pansalut/koffan:latest
    container_name: koffan
    restart: unless-stopped
    ports:
      - 3852:80
    volumes:
      - ./data:/data
    environment:
      - APP_PASSWORD=yourpassword

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

1
2
3
4
5
6
7
8
9
10
# 新建文件夹 koffan 和 子目录
mkdir -p /volume1/docker/koffan/data

# 进入 koffan 目录
cd /volume1/docker/koffan

# 将 docker-compose.yml 放入当前目录

# 一键启动
docker-compose up -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