一、HomeLists

1.1 HomeLists简介

HomeLists 是一款开源自托管的家庭耗材统计软件，通过智能提醒和集中化管理功能，帮助用户高效追踪家庭消耗品的使用情况，避免浪费与短缺，实现更便捷的生活物资管理。

1.2 HomeLists主要特点

1. 自托管部署：可独立部署在个人服务器或云端，保障数据隐私与安全。
2. 智能提醒机制：自动监测库存量，及时提醒补货或处理即将过期的物品。
3. 多类别管理：支持分类管理食品、日用品、清洁用品等不同类型耗材。
4. 实时库存追踪：记录物品数量变化，清晰展示当前库存与消耗趋势。
5. 过期日期管理：支持设置保质期，自动预警即将过期物品，减少浪费。
6. 直观仪表盘：可视化统计图表与报表，快速掌握家庭消耗品整体情况。
7. 开源与社区驱动：代码开放，支持自定义扩展，社区持续优化功能与体验。
8. 跨平台兼容：支持网页端访问，适配多种设备，随时随地管理家庭物资。

二、本次实践规划

2.1 本地环境规划

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

2.2 本次实践介绍

1.本次实践部署环境为个人测试环境，生产环境请谨慎；
2.在Docker环境下部署HomeLists家庭库存管理工具。

三、本地环境检查

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 Wed 2026-05-27 12:43:32 CST; 3 days ago
TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 962 (dockerd)
      Tasks: 190
     Memory: 435.4M (peak: 447.2M)
        CPU: 6min 22.405s
     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

四、拉取HomeLists镜像

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

root@jeven:~# docker pull aceberg/homelists:1.0.3
1.0.3: Pulling from aceberg/homelists
1177228156b6: Pull complete
fb56c12947cc: Pull complete
96ee7a1168cc: Pull complete
Digest: sha256:bf0a5d62069ada46d5e378a595cfc8cbe3ed139ed245c967a2bbd8548e7bc5d8
Status: Downloaded newer image for aceberg/homelists:1.0.3
docker.io/aceberg/homelists:1.0.3

五、部署HomeLists服务

5.1 创建部署目录

创建部署目录，执行以下命令：

mkdir -p /data/homelists/data  && cd /data/homelists/

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

 chmod -R 777 /data/homelists/

5.2 创建HomeLists容器

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

docker run -d \
   --restart unless-stopped \
   --name homelists \
   -p 8842:8842 \
   -v $(pwd)/data:/data/homelists \
   -e TZ=Asia/Shanghai \   
   aceberg/homelists:1.0.3

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

vim docker-compose.yaml

version: '3'

services:
  homelists:
    image: aceberg/homelists:1.0.3
    container_name: homelists
    restart: always
    ports:
      - 8842:8842 
    volumes:
      - /data/homelists/data:/data/homelists
    environment:  
      - TZ=Asia/Shanghai 

5.3 创建HomeLists容器

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

docker compose up -d

5.4 查看HomeLists容器状态

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

root@jeven:/data/homelists#  docker compose ps
WARN[0000] /data/homelists/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
homelists   aceberg/homelists:1.0.3   "./HomeLists"   homelists   38 seconds ago   Up 37 seconds   0.0.0.0:8842->8842/tcp, [::]:8842->8842/tcp

5.5 检查HomeLists容器日志

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

docker compose logs

六、访问HomeLists服务

6.1 访问HomeLists初始页

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

6.2 添加存放位置

我们可以点击“New table”，新建物品的存放位置，例如逼向，书房书柜等。

6.3 添加物品

选择物品存放位置，点击新增物品。

填写物品名称和数量，点击“OK”即可。

七、总结

本次实践成功利用 Docker 完成了 HomeLists 的极速部署，为家庭物资管理搭建了高效且私有的自托管平台。通过直观的可视化看板与智能库存警戒功能，日常消耗品的采购周期与余量监控变得一目了然。这种数据自主掌控的极简方案，彻底解决了传统家庭记账中容易遗漏补货的痛点。开源工具与容器化技术的巧妙结合，让琐碎的生活物资管理迈向了精准化与智能化的新台阶。