grocy 4.7.1 配置参数详解
grocy 4.7.1 配置参数详解：config-dist.php 全部 55 个 Setting 键逐项说明，配置三级覆盖链（settingoverrides > GROCY_* 环境变量 > config.php）实测验证，含 /api/system/config 自检。
grocy 4.7.1 配置参数详解
目标：逐项讲解 grocy 4.7.1 全部 55 个配置键（官方
config-dist.php全量清单）的含义、默认值与实测效果，并实测验证配置的三级覆盖链（settingoverrides覆盖文件 >GROCY_*环境变量 >data/config.php）。实测环境为 Ubuntu 22.04 + PHP 8.5.12 部署形态（release 包 + Apache）与镜像部署形态（lscr.io/linuxserver/grocy:4.7.1）各一套，实测时点 2026-10-23。
一、环境信息
- grocy 版本：4.7.1（config-dist.php 取自官方 release 包与 v4.7.1 tag 源码，两者一致）
- 部署形态 A：Ubuntu 22.04（x86_64）+ Apache 2.4 + PHP 8.5.12 + SQLite 3.54.1，站点
/var/www/grocy，配置文件/var/www/grocy/data/config.php（部署过程见《Ubuntu 22.04 安装 grocy 4.7.1 指南》） - 部署形态 B：镜像
lscr.io/linuxserver/grocy:4.7.1（PHP 8.5.12 + SQLite 3.53.4），数据目录/opt/grocy/config，配置文件/opt/grocy/config/data/config.php（部署过程见《grocy 4.7.1 Docker Compose 部署指南》） - 验证手段：grocy 内建
/api/system/config端点（登录会话或 API Key 鉴权）可回读全部生效配置，本文所有「实测回读」均经该端点取证
二、前置条件
已按部署篇完成安装并能登录（默认账号 admin/admin，改密流程见部署篇）；如需用 API 回读配置，先在网页「用户设置 → API 密钥」创建一个 Key（或按《grocy 4.7.1 API 使用详解》用会话创建）。确认配置文件位置：
ls /var/www/grocy/data/config.php
实测回显：
/var/www/grocy/data/config.php
三、参数查看与修改方式
3.1 三级覆盖链（优先级从高到低）
config-dist.php 文件头注释（v4.7.1 源码实查）明确了配置的三个来源与优先级：
// First priority:
// A .txt file with the same name as the setting in /data/settingoverrides
// the content of the file is used as the setting value
//
// Second priority:
// An environment variable with the same name as the setting and prefix "GROCY_"
// so for example "GROCY_BASE_URL"
//
// Third priority:
// The settings defined here below
即：data/settingoverrides/<键名>.txt 覆盖文件 > GROCY_ 前缀环境变量 > data/config.php 中的 Setting() 值。三级实测验证如下（以 CURRENCY 键为例，默认 USD）。
第 3 级：data/config.php（形态 A 实测）——直接编辑 config.php：
sudo sed -i "s/Setting('CURRENCY', 'USD');/Setting('CURRENCY', 'CNY');/" /var/www/grocy/data/config.php
回读验证（下一次请求即生效，无需重启 PHP）：
curl -s -b /tmp/grocy-session.txt http://127.0.0.1/api/system/config | grep -o '"CURRENCY":"[^"]*"'
实测回显：
"CURRENCY":"CNY"
第 2 级：GROCY_* 环境变量（形态 B 实测）——compose 的 environment 段加入 GROCY_CURRENCY=CNY 与 GROCY_ENTRY_PAGE=shoppinglist 后 docker compose up -d 重建，回读：
"CURRENCY":"CNY"
"ENTRY_PAGE":"shoppinglist"
环境变量覆盖了 config.php 的默认值（USD/stock），且环境变量属于容器定义，必须重建（up -d）而非 restart 才生效。
第 1 级：settingoverrides 覆盖文件（形态 B 实测，叠在上述 env 之上）——在数据目录建同名 .txt，文件内容即参数值：
mkdir -p /opt/grocy/config/data/settingoverrides
echo -n "EUR" > /opt/grocy/config/data/settingoverrides/CURRENCY.txt
docker compose restart grocy
回读验证：
CURRENCY (期望 EUR, settingoverrides 优先于 env): EUR
ENTRY_PAGE (仍为 env 覆盖值): shoppinglist
实测结论：settingoverrides/CURRENCY.txt=EUR 胜过环境变量 GROCY_CURRENCY=CNY（同键只生效一个，级别高者赢）；删除该文件后 CURRENCY 回落到环境变量值，再移除环境变量则回到 config.php 默认 USD（实测回读 "CURRENCY":"USD"）。
⚠️ 注意：覆盖文件名就是配置键名加
.txt（如CURRENCY.txt），内容不带引号、不带换行（用echo -n写入）；修改覆盖文件后需重启服务（reload/重启容器）才会重读。
3.2 用 /api/system/config 自检生效配置
curl -s -H "GROCY-API-KEY: <你的APIKey>" http://localhost:8150/api/system/config
实测回显（节选，共 48 个键）：
{"MODE":"production","DEFAULT_LOCALE":"en","CURRENCY":"USD","ENTRY_PAGE":"stock","DISABLE_AUTH":false,"AUTH_CLASS":"Grocy\\Middleware\\Auth\\DefaultAuthMiddleware","GROCYCODE_TYPE":"2D","FEATURE_FLAG_STOCK":true,"FEATURE_FLAG_SHOPPINGLIST":true,...}
实测键数对照：config-dist.php 共 55 个 Setting() 键，/api/system/config 只暴露 48 个——未暴露的 7 个键全部是认证敏感项：LDAP_ADDRESS、LDAP_BASE_DN、LDAP_BIND_DN、LDAP_BIND_PW、LDAP_USER_FILTER、LDAP_UID_ATTR、REVERSE_PROXY_AUTH_HEADER、REVERSE_PROXY_AUTH_USE_ENV（实测集合差运算结论，含绑定密码 LDAP_BIND_PW 被刻意隐藏）。排查 LDAP/反代认证问题时不能依赖该端点，直接看 config.php。
四、参数总览
55 个配置键按功能分 6 类（键名、默认值均照抄 config-dist.php）：
| 分类 | 键（默认值） | 数量 |
|---|---|---|
| 运行模式与入口 | MODE(production)、BASE_PATH('')、BASE_URL('/')、DISABLE_URL_REWRITING(false)、ENTRY_PAGE(stock) | 5 |
| 本地化与显示 | DEFAULT_LOCALE(en)、CALENDAR_FIRST_DAY_OF_WEEK('')、CALENDAR_SHOW_WEEK_OF_YEAR(true)、MEAL_PLAN_FIRST_DAY_OF_WEEK('')、CURRENCY(USD)、ENERGY_UNIT(kcal) | 6 |
| 认证与权限 | DISABLE_AUTH(false)、AUTH_CLASS(DefaultAuthMiddleware)、REVERSE_PROXY_AUTH_HEADER(REMOTE_USER)、REVERSE_PROXY_AUTH_USE_ENV(false)、LDAP_ADDRESS('')、LDAP_BASE_DN('')、LDAP_BIND_DN('')、LDAP_BIND_PW('')、LDAP_USER_FILTER('')、LDAP_UID_ATTR('')、DEFAULT_PERMISSIONS(['ADMIN']) | 11 |
| 条码与标签打印 | STOCK_BARCODE_LOOKUP_PLUGIN(OpenFoodFactsBarcodeLookupPlugin)、GROCYCODE_TYPE(2D)、LABEL_PRINTER_WEBHOOK('')、LABEL_PRINTER_RUN_SERVER(true)、LABEL_PRINTER_PARAMS(['font_family'=>'Source Sans Pro (Regular)'])、LABEL_PRINTER_HOOK_JSON(true) | 6 |
| 热敏打印机 | TPRINTER_IS_NETWORK_PRINTER(false)、TPRINTER_PRINT_QUANTITY_NAME(true)、TPRINTER_PRINT_NOTES(true)、TPRINTER_IP(127.0.0.1)、TPRINTER_PORT(9100)、TPRINTER_CONNECTOR(/dev/usb/lp0) | 6 |
| 功能开关 | FEATURE_FLAG_* 共 21 个（见 5.5 节总表） | 21 |
关键解读：grocy 没有数据库连接类配置——v4.7.1 源码 services/DatabaseService.php 仅有 new \PDO\Sqlite('sqlite:...') 一种实现，数据存储固定为 data/grocy.db 单文件 SQLite（详见 5.6 节），这是评估「能否多实例共享数据」时的决定性约束。
五、核心参数分类详解
5.1 运行模式与入口
| 键 | 默认 | 说明 |
|---|---|---|
MODE | production | 运行模式，可选 production/dev/demo/prerelease。非 production 会进入演示模式：关闭认证并生成演示数据（官方注释原文：authentication is disabled and some demo data will be generated）。生产必须保持 production，实测本部署回读 MODE=production |
BASE_PATH | '' | 子目录部署时设为 document root 之后的路径：支持 URL 重写时如 /grocy；不支持时如 /grocy/public/index.php（注释原文示例） |
BASE_URL | '/' | 站点对外基础 URL：根路径部署填 /，子目录部署填完整前缀如 https://example.com/grocy。影响生成的绝对链接 |
DISABLE_URL_REWRITING | false | Web 服务器不支持 URL 重写时设 true，改用带 index.php 的 URL 形态（Apache 用户通常不需要——release 包自带 public/.htaccess 重写规则） |
ENTRY_PAGE | stock | 登录后默认首页，可选值：stock, shoppinglist, recipes, chores, tasks, batteries, equipment, calendar, mealplan（注释原文枚举）。实测：env 设 GROCY_ENTRY_PAGE=shoppinglist 后回读 ENTRY_PAGE=shoppinglist |
5.2 本地化与显示
| 键 | 默认 | 说明 |
|---|---|---|
DEFAULT_LOCALE | en | 界面默认语言。取值为 localization/ 目录下的目录名，grocy 按「浏览器偏好 → 用户设置 → 此处默认值」顺序生效。简体中文填 zh_CN（官方本地化包实测存在） |
CALENDAR_FIRST_DAY_OF_WEEK | '' | 日历每周首日，空=按 locale 默认；数字 0=周日、1=周一（注释原文） |
CALENDAR_SHOW_WEEK_OF_YEAR | true | 日历是否显示周数 |
MEAL_PLAN_FIRST_DAY_OF_WEEK | '' | 膳食计划周首日，可设 -1 表示从「今天」动态起算（注释原文） |
CURRENCY | USD | 全站货币的 ISO 4217 代码，只影响显示格式，grocy 不做汇率换算（注释原文：doesn't really matter, but needs to be the ISO 4217 code）。中国使用环境改 CNY，三级覆盖链实测均以此键演示 |
ENERGY_UNIT | kcal | 能量单位显示（kcal/kJ），纯显示用途 |
5.3 认证与权限
| 键 | 默认 | 说明 |
|---|---|---|
DISABLE_AUTH | false | 设 true 将完全关闭登录，所有请求以第一个用户身份执行。仅限完全隔离的内网玩具场景，公网部署严禁开启 |
AUTH_CLASS | Grocy\Middleware\Auth\DefaultAuthMiddleware | 认证中间件类名，三选一：DefaultAuthMiddleware（grocy 本地用户）、ReverseProxyAuthMiddleware（反代认证，配合下两键）、LdapAuthMiddleware（LDAP，配合 5 个 LDAP 键）。⚠️ 4.7.0 重构了认证中间件，升级老实例时官方提示需复核此项（Release Notes 实查） |
REVERSE_PROXY_AUTH_HEADER | REMOTE_USER | 反代认证时传递用户名的 HTTP 头名 |
REVERSE_PROXY_AUTH_USE_ENV | false | 用户名以环境变量（FastCGI/CGI 场景）而非 Header 传递时设 true |
LDAP_ADDRESS | '' | LDAP 服务器地址，示例 ldap://dc01.corp.local（注释示例为 AD 域控） |
LDAP_BASE_DN | '' | 搜索基础 DN，示例 DC=local,DC=berrnd,DC=net |
LDAP_BIND_DN / LDAP_BIND_PW | '' | 绑定账号 DN 与密码（服务账号）。此密码是全表唯一明文口令类配置，注意 config.php 权限（本文部署中属主 www-data、权限 644，加固场景建议 640） |
LDAP_USER_FILTER | '' | 用户过滤条件，示例 (OU=grocy_users) |
LDAP_UID_ATTR | '' | 用户名属性：Windows AD 用 sAMAccountName、OpenLDAP 用 uid、GLAuth 用 cn（注释原文枚举） |
DEFAULT_PERMISSIONS | ['ADMIN'] | 新建用户的默认权限集，取值见 controllers/Users/User.php 常量。默认 ADMIN 意味着手工新建的普通用户也拿到全权限，多用户场景应改为最小权限集 |
5.4 条码与标签/热敏打印
| 键 | 默认 | 说明 |
|---|---|---|
STOCK_BARCODE_LOOKUP_PLUGIN | OpenFoodFactsBarcodeLookupPlugin | 外部条码查询插件（plugins/ 内置或 data/plugins/ 自定义，填不带 .php 的文件名）。扫码后经 OpenFoodFacts 自动补全商品信息；内网/离线环境建议留空禁用外呼，避免扫码时长时间等待（插件机制注释原文：Leave empty to disable external barcode lookups） |
GROCYCODE_TYPE | 2D | 内部条码类型：2D（DataMatrix）或 1D（Code128）。GROCYCODE 是 grocy 给商品/库存件生成的内部编码，扫码枪/手机摄像头识别后直接触发对应动作 |
LABEL_PRINTER_WEBHOOK | '' | 标签打印 Webhook 地址：grocy 以 POST 方式把打印任务推给它（默认关闭，见 FEATURE_FLAG_LABEL_PRINTER） |
LABEL_PRINTER_RUN_SERVER | true | true=服务端发起 Webhook；false=由浏览器客户端发起（打印机只在用户内网时用 false） |
LABEL_PRINTER_PARAMS | ['font_family' => 'Source Sans Pro (Regular)'] | 随 Webhook 附带的附加参数（如字体） |
LABEL_PRINTER_HOOK_JSON | true | Webhook 体用 JSON（true）或普通表单 POST（false） |
TPRINTER_IS_NETWORK_PRINTER | false | 热敏打印机为网络打印机时设 true（走 IP:9100），否则按本地设备文件连接 |
TPRINTER_PRINT_QUANTITY_NAME / TPRINTER_PRINT_NOTES | true / true | 购物清单小票是否打印数量名/备注 |
TPRINTER_IP / TPRINTER_PORT | 127.0.0.1 / 9100 | 网络热敏打印机地址与端口（9100 为 RAW/JetDirect 常用端口） |
TPRINTER_CONNECTOR | /dev/usb/lp0 | 本地打印机设备文件（USB 常见 /dev/usb/lp0，串口如 /dev/ttyS0）；注释提示需让 Web 服务用户具备写权限（如 usermod -a -G lp www-data）。热敏打印需打印机支持 ESC/POS 协议（底座为 escpos-php 库） |
5.5 功能开关（FEATURE_FLAG_*，21 个）
全部默认开启（true），用于裁剪不需要的功能模块，让界面更清爽（注释原文：disable the parts which you don't need to have a less cluttered UI）。关闭后对应导航入口即刻消失（实测见下）：
| 键 | 默认 | 控制的模块 |
|---|---|---|
FEATURE_FLAG_STOCK | true | 库存（核心域） |
FEATURE_FLAG_SHOPPINGLIST | true | 购物清单 |
FEATURE_FLAG_RECIPES | true | 食谱 |
FEATURE_FLAG_CHORES | true | 家务 |
FEATURE_FLAG_TASKS | true | 任务 |
FEATURE_FLAG_BATTERIES | true | 电池 |
FEATURE_FLAG_EQUIPMENT | true | 设备档案 |
FEATURE_FLAG_CALENDAR | true | 日历 |
FEATURE_FLAG_LABEL_PRINTER | false | 标签打印（唯一默认关闭的模块开关） |
FEATURE_FLAG_THERMAL_PRINTER | false | 热敏打印（默认关闭） |
FEATURE_FLAG_STOCK_PRICE_TRACKING | true | 库存价格跟踪 |
FEATURE_FLAG_STOCK_LOCATION_TRACKING | true | 多库位跟踪 |
FEATURE_FLAG_STOCK_BEST_BEFORE_DATE_TRACKING | true | 保质期跟踪 |
FEATURE_FLAG_STOCK_PRODUCT_OPENED_TRACKING | true | 已开封跟踪 |
FEATURE_FLAG_STOCK_PRODUCT_FREEZING | true | 冷冻/解冻跟踪 |
FEATURE_FLAG_STOCK_BEST_BEFORE_DATE_FIELD_NUMBER_PAD | true | 保质期输入数字键盘（移动端优化） |
FEATURE_FLAG_SHOPPINGLIST_MULTIPLE_LISTS | true | 多购物清单 |
FEATURE_FLAG_RECIPES_MEALPLAN | true | 膳食计划 |
FEATURE_FLAG_CHORES_ASSIGNMENTS | true | 家务指派成员 |
FEATURE_FLAG_DISABLE_BROWSER_BARCODE_CAMERA_SCANNING | false | 设为 true 禁用浏览器摄像头扫码 |
FEATURE_FLAG_AUTO_TORCH_ON_WITH_CAMERA | true | 扫码时自动开手电筒（移动端） |
实测：通过环境变量 GROCY_FEATURE_FLAG_SHOPPINGLIST=false 重建实例后——/api/system/config 回读 "FEATURE_FLAG_SHOPPINGLIST":false；登录后的首页 HTML 中 shoppinglist 导航入口出现次数为 0（关闭前存在）；直接访问 /shoppinglist 路径仍返回 200（模块仅从导航隐藏，URL 未被移除）。恢复默认后回读 "FEATURE_FLAG_SHOPPINGLIST":true、导航入口重现。
5.6 数据存储说明（没有数据库配置键）
55 个键中不存在任何数据库连接/类型配置。v4.7.1 源码实查：services/DatabaseService.php 仅实现 new \PDO\Sqlite('sqlite:' . $this->GetDbFilePath())，数据库文件固定为 data/grocy.db（data/.htaccess 拒绝 Web 直访）。历史资料提到的 MySQL 支持在当前版本代码中已不存在（全源码不含 mysql 连接字样，2026-10-23 对 release 包逐文件 grep 核实）。含义：
- 备份 = 备份
data/目录（重点是grocy.db） - 不支持多实例共享一个库，也不适合把库放到外部数据库服务器
- 并发模型按家庭规模设计（个位数用户），不要拿来做团队/企业级库存
六、生产配置模板（家庭 2–8 人、2C4G 级 NAS/小服务器场景）
适用：单机自托管、内网或家庭宽带 + 反代 HTTPS、中文使用环境、不需要电池/设备模块。以下为 data/config.php 中建议显式写入的键（未列出的保持 config-dist 默认）：
// 基础：反代/子目录部署时改 BASE_URL/BASE_PATH，根路径保持默认
Setting('MODE', 'production');
Setting('DEFAULT_LOCALE', 'zh_CN'); // 简体中文界面（官方本地化包内置）
Setting('CURRENCY', 'CNY'); // 人民币显示
Setting('ENTRY_PAGE', 'stock'); // 登录后落在库存总览
// 认证：保持本地账号认证；LDAP/反代认证按需切换 AUTH_CLASS
Setting('DISABLE_AUTH', false);
Setting('DEFAULT_PERMISSIONS', ['USERS']); // 多用户时新用户给普通权限而非 ADMIN
// 条码：可直连外网时保留 OpenFoodFacts 插件，纯内网置空
Setting('STOCK_BARCODE_LOOKUP_PLUGIN', 'OpenFoodFactsBarcodeLookupPlugin');
// 裁剪不需要的模块（示例：关闭电池与设备档案）
Setting('FEATURE_FLAG_BATTERIES', false);
Setting('FEATURE_FLAG_EQUIPMENT', false);
// 打印：默认关闭，需要时再开
Setting('FEATURE_FLAG_LABEL_PRINTER', false);
Setting('FEATURE_FLAG_THERMAL_PRINTER', false);
逐项说明：MODE=production 是安全底线（其他模式会关认证+灌演示数据）；DEFAULT_PERMISSIONS 从默认 ['ADMIN'] 收紧为普通用户集，避免随手建号即管理员；两个 FEATURE_FLAG 关闭示例演示界面裁剪；其余键默认值已适合家庭场景。配置修改保存即生效（下一请求生效），敏感运维环境可叠加 settingoverrides/ 覆盖文件管理临时改动（优先级最高，见 3.1 节实测）。
七、常见问题（FAQ）
Q1：改了 data/config.php 为什么不生效？
按 3.1 节三级覆盖链排查：先看 data/settingoverrides/ 有没有同名 .txt（最高优先级），再确认部署形态是否注入了 GROCY_ 前缀环境变量（容器形态常见），最后才是 config.php 本身。用 /api/system/config 回读当前生效值可快速定位在哪一级被覆盖。
Q2：容器里改了环境变量但不生效？
环境变量属于容器定义，docker compose restart 不重建实例、不会重读，必须 docker compose up -d 重建（本文 3.1 节实测即用重建方式生效）。
Q3：/api/system/config 里看不到我配的 LDAP 参数？
正常。LDAP_（5 键）与 REVERSE_PROXY_（2 键）共 7 个认证敏感键被该端点刻意隐藏（实测集合差），直接查看 config.php 确认。
Q4：MODE 改成 demo 会怎样？
认证被禁用并自动生成演示数据（官方注释原文），页面任何人不登录即可操作。仅用于临时体验，演示数据可通过访问首页时附 ?nodemodata 参数跳过生成；生产环境务必回到 production。
Q5：内网服务器扫码商品时卡住没反应？
STOCK_BARCODE_LOOKUP_PLUGIN 默认走 OpenFoodFacts 外网查询，内网不可达时表现为扫码长时间无响应。将该键置空禁用外呼即可。
Q6：想临时给某个键做试验又不想污染 config.php？
用 data/settingoverrides/<键名>.txt 覆盖（优先级最高），试验完删文件重启即回到原值——这正是该机制的设计用途，本文 3.1 节以此方式完成了 EUR 覆盖实验。
八、参考链接
- 官方配置文件全量注释（v4.7.1 config-dist.php）：https://github.com/grocy/grocy/blob/v4.7.1/config-dist.php
- 前置校验逻辑（PrerequisiteChecker.php）：https://github.com/grocy/grocy/blob/v4.7.1/helpers/PrerequisiteChecker.php
- 本专栏部署篇：《Ubuntu 22.04 安装 grocy 4.7.1 指南》、《grocy 4.7.1 Docker Compose 部署指南》
- API 回读配置的鉴权细节：《grocy 4.7.1 API 使用详解》
- 项目定位与版本节奏：《grocy 4.7.1 介绍与选型指南》