一、Koffan介绍

1.1 Koffan简介

Koffan 是一款极速且极简的购物清单管理应用，专为多人协作设计。它具备超轻量级的架构、完善的离线模式以及实时同步功能，能够帮助用户轻松创建并管理跨设备、多场景的购物清单。

1.2 Koffan主要特点

• 极致轻量高效：占用空间极小（约 16 MB），内存消耗低（约 2.5 MB RAM），运行流畅不卡顿。
• 多清单灵活管理：支持为不同商店或用途创建独立清单，并可自定义专属图标以便区分。
• 类原生 PWA 体验：作为渐进式网络应用（PWA），可直接安装在手机上，获得如同原生 App 般的使用体验。
• 强大的离线模式：无网络环境下依然可以自由增删改查，联网后自动同步数据，确保信息无缝衔接。
• 智能自动补全：基于历史记录提供模糊搜索建议，并能智能记忆商品所属的分类区域。
• 清晰的商品分区：支持将商品归类到不同板块（如乳制品、蔬菜、清洁用品等），让购物更有条理。
• 便捷的状态标记：不仅可以标记商品为“已购买”，还能标记为“不确定”以应对找不到商品的状况。
• WebSocket 实时同步：采用 WebSocket 技术，确保所有更改在团队成员之间实现毫秒级的实时更新。
• 移动端优先设计：界面高度响应式，专为移动设备优化，同时完美适配各种屏幕尺寸。
• 智能深色模式：能够根据操作系统的偏好设置，自动切换浅色或深色主题，保护视力。
• 广泛的多语言支持：内置波兰语、英语、德语、中文等十余种语言，满足全球用户的使用需求。
• 安全简便的登录：提供简单直观的登录系统，并配备防暴力破解的速率限制保护，保障账户安全。
• 开放的 REST API：提供完整的程序化访问接口，方便开发者进行第三方集成或数据迁移。

二、本次实践规划

2.1 本地环境规划

本次实践为个人测试环境，操作系统版本为 Ubuntu 24.04.2 LTS。

2.2 本次实践介绍

1.本次实践部署环境为个人测试环境，生产环境请谨慎；
2.在Docker环境下部署Koffan购物清单管理工具。

2.3 注意事项

1. 本项目更新频繁，请根据实际需求选择不同版本的镜像或最新镜像，具体版本信息请参考项目官网。
2. 项目 GitHub 地址：https://github.com/PanSalut/Koffan
3. 数据库文件位于容器内的 /data/shopping.db（对应宿主机挂载目录 ./data/shopping.db），建议定期进行备份。
4. 本次实践基于个人测试环境，若用于生产环境，请务必进行充分评估和测试。

三、本地环境检查

3.1 检查Docker服务状态

检查Docker服务是否正常运行，确保Docker正常运行。

root@jeven:~# systemctl status docker
● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-02-05 00:27:40 CST; 1s ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 841698 (dockerd)
      Tasks: 65
     Memory: 73.5M (peak: 77.1M)
        CPU: 975ms
     CGroup: /system.slice/docker.service

3.2 检查Docker版本

检查Docker版本

root@jeven:~# docker -v
Docker version 28.5.0, build 887030f

3.3 检查docker compose 版本

检查Docker compose版本，确保2.0以上版本。

root@jeven:~# docker compose version
Docker Compose version v2.39.4

四、拉取Koffas镜像

下载Koffa镜像，执行以下命令：

root@jeven:~# docker pull  ghcr.io/pansalut/koffan:v2.11.0
v2.11.0: Pulling from pansalut/koffan
17a39c0ba978: Already exists
25d60d97146d: Pull complete
a7f79ba92770: Pull complete
612f453ee77d: Pull complete
1e15bd78aad8: Pull complete
Digest: sha256:891987ce244c80d4b1b49e98335be1b5b5c803a5f9bb3eff3407c108558386c6
Status: Downloaded newer image for ghcr.io/pansalut/koffan:v2.11.0
ghcr.io/pansalut/koffan:v2.11.0

五、部署Koffan服务

5.1 创建部署目录

• 创建部署目录

mkdir -p /data/koffans/data  && cd /data/koffans

• 在测试环境中，为了方便操作，我们直接为挂载目录设置了完全权限。但在生产环境中，请务必根据实际安全需求，配置更精细、严格的权限控制方案。

 chmod -R 777  /data/koffans

5.2 docker-cli方式部署（可选）

如果想要使用docker-cli方式部署，可参考以下命令部署。（可选）

docker run -d \
   --restart unless-stopped \
   --name koffan \
   -p 7450:8080 \
   -v $(pwd)/data:/data \
   -e APP_PASSWORD=admin \
  ghcr.io/pansalut/koffan:v2.11.0

5.3 创建Koffan容器

本次实践我们采用 Docker Compose 方式进行部署，这也是我推荐的方式。首先我们需要创建并编辑 docker-compose.yaml 文件，请注意宿主机映射端口可根据您的实际情况自行设置，务必避免端口冲突。

vim docker-compose.yaml

version: '3'

services:
  koffan:
    image: ghcr.io/pansalut/koffan:v2.11.0
    container_name: koffan
    restart: always
    ports:
      - 7660:8080
    volumes:
      - /data/koffans/data:/data
    environment:
      - APP_PASSWORD=admin

执行以下命令，创建Koffan容器。

docker compose up -d

5.4 查看Koffan容器状态

检查Koffan容器运行状态，确保Koffan容器正常启动。

root@jeven:/data/koffans# docker compose ps
WARN[0000] /data/koffans/docker-compose.yaml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
NAME      IMAGE                             COMMAND             SERVICE   CREATED          STATUS                   PORTS
koffan    ghcr.io/pansalut/koffan:v2.11.0   "./shopping-list"   koffan    10 seconds ago   Up 9 seconds (healthy)   0.0.0.0:7660->8080/tcp, [::]:7660->8080/tcp

5.5 检查Koffan容器日志

检查容器运行日志，确保Koffan服务正常运行。

docker compose logs

六、访问Koffan服务

6.1 访问Koffan初始页

浏览器地址： http://<个人的服务器IP>:7660，访问Koffan初始页。如果无法访问，请确保宿主机的防火墙已关闭或已放行相关端口，对于云服务器还需配置相应的安全组规则。

6.2 登录Koffan

我们设置的访问密码为admin，输入admin后进入Koffan首页。

6.3 基本使用

可自行编辑购物清单，如下所示：

七、总结

通过本次实践，我们成功在 Docker 环境下部署了 Koffan 这款轻量高效的购物清单管理工具。整个部署过程涵盖了从环境检查、镜像拉取、容器创建到服务验证的完整流程。Koffan 凭借其极简设计、离线可用、实时同步等特性，为个人或团队管理购物清单提供了极大便利。