grocy 4.7.1 介绍与选型指南

目标：全面介绍自托管家庭库存与杂货管理系统 grocy（「ERP beyond your fridge」）的定位、架构、功能与选型结论，并给出与 Homebox、Firefly III 的量化对比。本文数据均于 2026-10-23 联网溯源自官方渠道（官网 grocy.info、GitHub 仓库 grocy/grocy v4.7.1 tag、releases.atom 订阅、shields.io 徽章接口、LinuxServer.io 镜像仓库），检索环境为 Ubuntu 22.04（x86_64）+ 代理出口，来源在正文逐项标注。

一、环境信息

• 信息检索日期：2026-10-23（本文所有版本号、星数、发布日期的取证时点）
• 检索对象：grocy/grocy（官方仓库）、grocy.info（官网）、linuxserver/grocy（官方 README 推荐的 Docker 形态）
• 检索工具：GitHub Releases Atom 订阅（https://github.com/grocy/grocy/releases.atom）、shields.io 徽章 JSON 接口（https://img.shields.io/github/stars/grocy/grocy.json 等）、官方 release 包（https://releases.grocy.info/latest）
• 溯源说明：A1 属认知篇，本文不含本地实测结论；凡引用官方数据处均标注来源与查询日期。部署与配置的逐条实测见《Ubuntu 22.04 安装 grocy 4.7.1 指南》与《grocy 4.7.1 Docker Compose 部署指南》。

二、软件概述

2.1 项目身份

grocy 的官方自我定位是「ERP beyond your fridge」（冰箱之外的 ERP），作者是德国开发者 Bernd Bestel（berrnd.de），自 2017 年持续维护至今（LICENSE.md 版权声明 2017-2026，2026-10-23 实查 release 包内 LICENSE.md）。它是一个单进程的 Web 应用：跑在自家服务器/NAS 上，通过浏览器或手机浏览器使用，用来管理「家庭这个最小单位的进销存」——食材库存、购物清单、食谱、家务排班、任务、电池更换周期、设备档案等。

• 官网：https://grocy.info
• 官方仓库：https://github.com/grocy/grocy（MIT License，2026-10-23 经 shields.io license 徽章与 release 包 LICENSE.md 双重核实）
• 在线演示（最新稳定版）：https://demo.grocy.info；开发版演示：https://demo-prerelease.grocy.info（来源：仓库 README，2026-10-23 查询）
• 星数：9.6k（shields.io github/stars/grocy/grocy.json 徽章返回值 9.6k，2026-10-23 查询；GitHub API 限流，星数统一以 shields.io 为准）

2.2 版本与发布节奏

2026-10-23 通过 releases.atom 订阅实查最近 9 个稳定版（Atom 更新时间为准）：

关键解读：grocy 发布节奏约为每年 3–4 个稳定版（上表 9 个版本横跨 2024-03 至 2026-09，约 30 个月），属于「低频但持续」的家庭项目维护模式；4.6.0 起将运行时硬性收敛到 PHP 8.5 + SQLite 3.40+（v4.6.0 Release Notes 原文：「PHP 8.5 (with SQLite 3.40+) is from now on the only supported runtime version」，2026-10-23 实查），这对老旧系统（如 Ubuntu 20.04/22.04 自带 PHP 8.0/8.1）意味着必须升级运行时或改用容器部署，选型时要预估这一成本。

2.3 技术栈与运行要求（v4.7.1 tag 源码实查）

• 语言/框架：PHP 8.5（composer.json require.php: "8.5.*"）+ Slim 4 微框架 + Blade 模板（webman/blade）
• 数据库：SQLite（3.40+）；v4.7.1 源码 services/DatabaseService.php 仅有 new \PDO\Sqlite('sqlite:...') 一种连接实现，config-dist.php 亦无任何数据库类型配置键（2026-10-23 对 release 包逐文件核实的结论）
• 必需 PHP 扩展：fileinfo、pdo_sqlite、gd、ctype、intl、zlib、mbstring（另有 filter、iconv、tokenizer、json 四个核心内置扩展被显式校验；来源：v4.7.1 helpers/PrerequisiteChecker.php 常量 REQUIRED_PHP_EXTENSIONS）
• 启动前置校验：PHP ≥ 8.5.0、SQLite ≥ 3.40.0、data/config.php 存在、packages/autoload.php（Composer 产物）存在，任一不满足即抛 ERequirementNotMet 拒绝启动（同上源码文件，2026-10-23 实查）
• 前端：原生 JavaScript + 各类前端包（public/packages/），无 Node 运行时依赖；移动端浏览器自适应 + 摄像头条码扫描（Browser API）

三、核心架构

3.1 部署形态

2026-10-23 官方 README（v4.7.1 tag）给出的三种形态：

1. Release 包 + 自备 Web 服务器（经典形态）：从 https://releases.grocy.info/latest 下载 zip，解压后把 config-dist.php 复制为 data/config.php，将 Web 服务器站点根目录指向 public/ 子目录（nginx 需在 location 块中加 try_files $uri /index.php$is_args$query_string;，或用配置项 DISABLE_URL_REWRITING 关闭 URL 重写）。
2. Docker（官方 README 指定形态）：README 的「How to run using Docker」一节直接指向 https://hub.docker.com/r/linuxserver/grocy，即由 LinuxServer.io 维护的镜像 lscr.io/linuxserver/grocy。⚠️ 官方 GitHub 曾经提供的 ghcr.io/grocy/grocy 镜像包页已不存在（2026-10-23 实查该包页返回 404，GHCR registry API 对 tag 列表返回 403），当前应使用 LinuxServer.io 镜像，其 4.7.1/latest 标签于 2026-10-21 更新（Docker Hub API 实查）。
3. grocy-desktop（Windows 桌面形态）：面向不想管 Web 服务器的 Windows 用户，从 https://releases.grocy.info/latest-desktop 下载安装（README 原文：「run Grocy without having to manage a webserver just like a normal (Windows) desktop application」，亦可经 Microsoft Store 安装）。

3.2 运行时结构

以 release 包解压结果为据（4.7.1 zip 结构，2026-10-23 实查）：

• public/：唯一对外的站点根目录，仅含 index.php、静态资源（css/js/img）与 .htaccess（URL 重写规则）；应用主体不在 Web 根下，敏感文件不直接暴露
• app.php、routes.php、controllers/、services/、middleware/、helpers/、views/：Slim 4 应用的路由、控制器、服务与中间件分层
• migrations/：数据库迁移脚本（0001.sql ~ 0257.sql + 8888.php），首次访问时自动执行到位（迁移计数 257，实测见部署篇）
• data/：运行时数据目录——config.php（实例配置）、grocy.db（SQLite 数据库）、plugins/（条码查询等插件）、viewcache/、settingoverrides/（配置覆盖文件）、backups/（update.sh 升级时自动打包的备份）
• packages/：Composer 依赖产物（随 release 包分发，无需自行执行 Composer）
• grocy.openapi.json：REST API 的 OpenAPI 3.1.0 规范，共 74 个路径；内建 Swagger UI 挂在 /api（README 与规范文件双证）

3.3 认证与扩展机制

• 默认本地账号体系：首次初始化自动创建 admin/admin（迁移脚本 0027.php 明文注释「Create default user "admin" with password "admin"」，源码实查），支持基于角色的权限（DEFAULT_PERMISSIONS 默认 ['ADMIN']）
• LDAP 认证：LDAP_ADDRESS、LDAP_BASE_DN、LDAP_BIND_DN 等配置键接入 Windows AD / OpenLDAP（config-dist.php 内含示例值）
• 反向代理认证：AUTH_CLASS 可切换为 ReverseProxyAuthMiddleware，经 REVERSE_PROXY_AUTH_HEADER（默认 REMOTE_USER）透传用户名
• 插件：data/plugins/ 目录 + STOCK_BARCODE_LOOKUP_PLUGIN 默认 OpenFoodFactsBarcodeLookupPlugin（扫码自动补全商品信息）

四、功能特性

功能域以 config-dist.php 的 FEATURE_FLAG_* 开关清单为准（v4.7.1 源码实查，2026-10-23），全部默认开启、可逐项关闭：

其他横切能力：

• GROCYCODE 条码：为商品/库存件/电池生成内部条码（GROCYCODE_TYPE 默认 2D），配合扫码枪或手机摄像头（Browser API 扫码，可用 FEATURE_FLAG_DISABLE_BROWSER_BARCODE_CAMERA_SCANNING 关闭）实现「扫一下完成入库/消耗」
• REST API + Swagger UI：74 个端点（OpenAPI 3.1.0 规范实查），API Key 鉴权，是手机快捷方式、自动化脚本与第三方集成的官方途径
• 多语言：官方本地化目录含 30+ 语言，含简体中文 zh_CN 与繁体 zh_TW（release 包 localization/ 目录实查），可经 Transifex 参与翻译（README）
• 升级工具：Linux 下自带 update.sh——覆盖最新 release 并保留 data/ 目录，升级前自动把当前安装打包成 .tgz 备份到 data/backups/，自动清理 60 天前的旧备份（README 原文实查）

五、快速开始（最小可用示例）

以下为官方 README（v4.7.1 tag，2026-10-23 查询）给出的最小路径，完整逐条实测命令与回显见本专栏部署两篇：

1. 环境要求：PHP 8.5（含 SQLite 3.40+）与 Web 服务器（Apache/nginx），或直接用 LinuxServer.io 的 Docker 镜像（内含打包好的运行时）
2. 下载并解压 release 包（官方源码指引原文）：

wget https://releases.grocy.info/latest    # 官方固定「最新稳定版」下载地址
unzip latest -d /var/www/grocy
cp /var/www/grocy/config-dist.php /var/www/grocy/data/config.php

3. 将站点根指向 /var/www/grocy/public（Apache 记得 AllowOverride All 以启用随包 .htaccess 的 URL 重写；nginx 参考 README：location 块加 try_files $uri /index.php$is_args$query_string;）
4. 浏览器访问站点：首次访问自动执行数据库迁移并创建默认账号 admin/admin（迁移脚本 0027.php 实查），登录后立即在用户设置中改密
5. 容器形态最小示例（LinuxServer.io 官方镜像，README 指定）：

docker run -d --name=grocy -p 8150:80 \
  -v /opt/grocy/config:/config \
  --restart unless-stopped \
  lscr.io/linuxserver/grocy:4.7.1

💡 说明：上面第 5 步镜像 tag 4.7.1 于 2026-10-23 经 Docker Hub API 实查存在（2026-10-21 构建）；PUID/PGID/TZ 等环境变量与 compose 完整写法见《grocy 4.7.1 Docker Compose 部署指南》。

六、适用场景与限制

6.1 适合的场景

• 家庭/小型合租的食材库存管理：保质期提醒、临期清单（/api/stock/volatile 返回 due/overdue/expired/missing 四类）、购物清单与食谱联动
• 「家庭小仓库」数字化：日用品、工具、耗材的出入库与库位管理，扫码枪/手机扫码进出
• 家务与家庭事务排班：家务周期、成员轮值、任务、电池更换、设备档案，一个入口全覆盖
• 隐私优先的自托管用户：数据落在自己服务器上的单个 SQLite 文件（data/grocy.db），备份=复制一个目录

6.2 限制与边界（均为官方源码/文档实查，2026-10-23）

• 运行时门槛高：PHP 8.5 + SQLite 3.40+ 是硬校验（PrerequisiteChecker 源码），Ubuntu 22.04 自带的 PHP 8.1/SQLite 3.37.2 均不达标，需 PPA + 自编译 SQLite 或容器化
• 仅 SQLite 单库：无外部数据库选项（见 3.1 节源码实查），不适合多实例共享数据的场景；单文件数据库决定了它面向家庭级并发（个位数用户），不是团队/企业级库存系统
• 无官方移动 App：移动端体验靠自适应 Web 页 + PWA 式使用方式；第三方方案见官网 Addons 页（https://grocy.info/addons）
• 个人项目维护节奏：单人维护（作者 Bernd Bestel），版本低频但持续；重大依赖升级（如 4.6.0 的 PHP 8.5 收敛）会给自装用户带来一次性升级成本
• Docker 官方镜像依赖第三方：官方仓库不再发布 ghcr 镜像（404 实查），镜像形态依赖 LinuxServer.io 社区构建

七、同类选型对比

家庭自托管领域常与 grocy 混谈的两个项目是 Homebox（物品盘点）与 Firefly III（个人记账）。三者定位互补而非替代，2026-10-23 shields.io 徽章与各自仓库 Release 实查如下：

关键解读：库存逻辑决定选型——同一盒牛奶「2 件、每件不同保质期、喝掉 1 件」这类数量流水只有 grocy 的消耗型库存模型能自然表达；Homebox 回答的是「我有什么、放在哪、保修到何时」的资产档案问题；Firefly III 回答的是「钱去哪了」的记账问题。

选型建议（「如果…则…」）：

• 如果要管的是会过期的消耗品（食材、药品、日用品），要保质期提醒和购物清单联动 → grocy
• 如果要管的是不会消耗的资产（电器、收藏、工具箱、保修单），重点是「找到了就行」 → Homebox
• 如果要管的是钱（账户、预算、账单） → Firefly III
• 三者并不互斥：grocy + Firefly III 是家庭自托管常见的「库存+记账」组合；若只想要最轻量的物品清单，Homebox 单二进制部署成本最低
• 若目标机器只有老运行时（PHP < 8.5）且不愿自编译依赖 → 优先容器化部署 grocy，或改用 Homebox（Go 静态二进制，无语言运行时依赖）

八、参考链接

• 官网与功能/插件：https://grocy.info 、https://grocy.info/addons
• 官方仓库（v4.7.1 tag README、composer.json、PrerequisiteChecker.php、config-dist.php、grocy.openapi.json）：https://github.com/grocy/grocy
• Release 订阅：https://github.com/grocy/grocy/releases.atom（2026-10-23 拉取）
• 星数/License 徽章取证：https://img.shields.io/github/stars/grocy/grocy.json 等（2026-10-23）
• Docker 镜像（官方 README 指定）：https://hub.docker.com/r/linuxserver/grocy
• 在线演示：https://demo.grocy.info
• Windows 桌面版：https://github.com/grocy/grocy-desktop
• 本专栏实测篇：《Ubuntu 22.04 安装 grocy 4.7.1 指南》、《grocy 4.7.1 Docker Compose 部署指南》、《grocy 4.7.1 配置参数详解》、《grocy 4.7.1 API 使用详解》