开源饮品库存管理系统BarKeep部署与使用全攻略

December 1, 2025

今天我们来聊聊一个能显著提升酒类爱好者与饮品收藏家生活品质的小工具：BarKeep。它是一个开源的酒柜与库存管理系统，旨在帮助您高效管理家庭酒窖、私人吧台乃至小型店铺的库存。

BarKeep项目简介

BarKeep 是一款基于 Ruby on Rails 框架开发的开源库存管理解决方案。其定位非常清晰：作为一个轻量级且功能恰到好处的饮品管家，它能够帮助您轻松打理家中酒柜、吧台或小型商业场所的各类库存。

核心功能一览

分类与搜索：支持按照酒类、原料、饮品等多种维度进行分类，并提供了高效的搜索功能，帮助您快速定位目标物品。
图片上传：可以为每一瓶酒或每一种原料添加对应的照片，让库存列表更加直观、生动。
库存提醒：系统能够自动识别并标记库存量偏低甚至已经缺货的物品，有效避免在需要时才发现朗姆酒已用完的尴尬。
补货仪表盘：集中展示所有需要补充的物品清单，省去逐一翻查的麻烦。
用户登录与认证：默认提供管理员账户，同时也支持进一步扩展多用户体系。
Docker 部署：官方直接提供了容器镜像，通常只需一条命令即可快速启动服务。

有了它，您再也不必担心忘记自己究竟购买了多少瓶二锅头或精酿啤酒，也无需在聚会前匆忙赶往超市采购。只需打开网页，所有库存情况便一目了然。

详细部署步骤：以威联通NAS为例

我们将以威联通（QNAP）NAS设备为例，演示如何通过 Docker Compose 方式部署 BarKeep。

第一步：生成安全密钥（SECRET_KEY_BASE）

通过SSH连接到您的NAS，输入以下命令来生成密钥：

docker run --rm ghcr.io/nckslvrmn/bar_keep:latest rails secret

执行后，终端会显示一长串随机字符。如果您尚未下载相关镜像，系统会自动拉取并执行命令。请务必复制这串密钥并妥善保存备用。

官方提供的 docker run 命令行如下（未作改动），但个人更倾向于使用 Docker Compose 进行管理：

docker run -d \
  --name barkeep-dev \
  -p 3000:3000 \
  -v $(pwd)/storage:/app/storage \
  -e SECRET_KEY_BASE=YOUR_GENERATED_SECRET_KEY_HERE \
  -e ALLOWED_HOST=localhost \
  -e FORCE_SSL=false \
  bar_keep:latest

第二步：使用 Docker Compose 部署（已适配威联通环境）

建议采用 Docker Compose 进行部署，以下配置代码已经针对威联通 NAS 的环境进行了适配：

services:
  barkeep:
    image: ghcr.io/nckslvrmn/bar_keep:latest
    container_name: barkeep-dev
    restart: always
    ports:
      - "2929:3000" # 冒号左侧的端口号可以根据需要修改
    volumes:
      - /share/Container/barkeep/storage:/app/storage # 左侧的目录路径请根据实际情况修改
    environment:
      - SECRET_KEY_BASE=46aa127ab464dbd7272e41484cfb478c3603da85f20fb007d1ac2c4c9d522a5dfb54e03d11078922409c59fac2cdf71b7f79f2e75842f97e5d81931d80109583 # 请替换为您第一步生成的KEY
      - ALLOWED_HOST=192.168.50.20 # 如果计划通过反向代理使用域名访问，此处应填写域名
      - FORCE_SSL=false # 强制SSL，此项通常保持默认即可，SSL可在反向代理工具中设置
      - SEED_DATABASE=true # 初始化数据库

此外，您还可以通过 RAILS_ENV 环境变量来配置部署环境（生产环境或开发环境）。BarKeep 默认使用 SQLite 数据库，所有数据文件将存储在映射的 storage 目录中。

一个重要的注意事项：如果您后续配置了反向代理（如 Nginx Proxy Manager），请务必确保代理转发的 Host 头与 ALLOWED_HOST 环境变量的值完全一致。原项目 README 也特别强调了这一点：“当使用反向代理时，Host 必须匹配代理所转发的值”。与某些应用不同的是，此处无需在 ALLOWED_HOST 中补齐端口号。

请根据您的实际网络环境和存储规划修改上述配置。然后，打开威联通的 Container Station，创建一个新的应用程序并将配置粘贴进去。

上手体验与操作指南

部署完成后，即可通过 NAS的IP地址:2929 来访问 BarKeep 服务。这里我们使用了威联通自带的 Browser Station 进行远程操作。系统默认的管理员账户和密码为：admin / changeme123。后续演示将基于配置了反向代理并启用 HTTPS 的环境进行。

在实际测试中，发现仅通过内网IP访问登录界面时，输入默认账密可能会卡在登录页面无法成功进入。此问题原因尚未明确。

在通过HTTPS反向代理访问并成功登录后，界面如下图所示。接下来，我们可以开始添加第一件商品。

在添加商品页面，逐一填写名称、分类、库存数量、图片等信息，然后点击创建。

商品创建成功后，会在库存列表中显示，如下图所示。

当添加了多种饮品和原料后，库存管理界面效果如下，所有物品井然有序。

总结与评价

BarKeep 是一个相对较新的开源项目，如果恰好有库存管理的需求，它值得一试。其界面简洁，核心功能实用，整体体验令人满意。

附录：饮品分类说明

BarKeep 内置了清晰的分类体系，有助于您高效管理：

Alcohol (酒精饮品)：指所有基础烈酒和含酒精饮品的统称，例如：啤酒、葡萄酒、伏特加、威士忌、朗姆酒、龙舌兰、白兰地等。它是调制鸡尾酒的主要酒精基底。
Liqueur (利口酒)：指“利口酒”或“甜酒”，通常在烈酒中加入糖、果汁、香草、香料或奶油调味。例如：百利甜（Baileys）、君度橙酒（Cointreau）、咖啡甜酒（Kahlúa）、杏仁甜酒（Amaretto）。它们多用于调味和增加风味层次。
Juice (果汁)：果汁类原料，例如：橙汁、菠萝汁、柠檬汁、蔓越莓汁。一般用于平衡酒精口感或增加清爽感。
Syrup (糖浆)：糖浆类原料，通常是高浓度糖水或加入风味的糖浆。例如：单糖浆（Simple Syrup）、红石榴糖浆（Grenadine）、蜂蜜糖浆、枫糖浆。主要用于增加甜度和丰富口感。
Ingredient (其他原料)：范围更广的原料类别，不一定是液体，可能包括：薄荷叶、盐、胡椒、奶油、蛋清、椰奶、香草等。用于丰富鸡尾酒的风味和口感层次。
Other (其他)：无法归类到上述任何分类的特殊原料。例如：苏打水、汤力水、能量饮料、椰子水、茶、咖啡，甚至某些独特的调味品。