尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

Grocy 1.24.0 配置体系升级:环境变量覆盖全部 config.php 设置(GROCY_ 前缀详解)

Grocy 1.24.0 配置体系升级:环境变量覆盖全部 config.php 设置(GROCY_ 前缀详解) Grocy 1.24.0 配置体系升级环境变量覆盖全部 config.php 设置GROCY_ 前缀详解【免费下载链接】grocyERP beyond your fridge - Grocy is a web-based self-hosted groceries household management solution for your home项目地址: https://gitcode.com/GitHub_Trending/gr/grocy本文对应 changelog/41_1.24.0_2018-12-30.md。Grocy 1.24.02018-12-30 发布引入了一项影响所有自托管部署方式的重要能力全部config.php配置项均可通过环境变量覆盖主要面向 grocy-docker 这类容器化部署场景。读完本文你将掌握 Grocy 配置加载的完整调用链、三级覆盖优先级、环境变量的命名与类型转换规则并能直接用docker run/docker-compose编写一套不依赖配置文件的环境变量部署方案。一、版本背景一次为容器化部署准备的配置重构1.24.0 的完整变更记录非常精炼全篇只有一句话Allconfig.phpsettings can now also be set via environment variables (for grocy-docker)即所有config.php设置现在都可以通过环境变量设置服务于 grocy-docker 容器化部署。对比相邻版本可见其分量——上一版 1.23.1 还只是购物清单工作流的按钮与 UI 修复而 1.24.0 直接为部署层打开了一个新维度配置不再必须落盘在config.php文件里而是可以跟随容器环境动态注入。这条变更的本质是让 Grocy 的配置解析器Setting()函数支持“外部来源”取值。要理解它必须先厘清 Grocy 配置从入口到生效的完整链路。二、配置加载链路从入口到常量定义Grocy 的启动入口是 public/index.php它首先处理“嵌入式模式”存在embedded.txt时或通过GROCY_DATAPATH环境变量/服务器变量确定数据目录随后引入 app.php 完成应用装配。配置加载发生在app.php的第 14–15 行// Load config files require_once GROCY_DATAPATH . /config.php; require_once __DIR__ . /config-dist.php; // For not in own config defined values we use the default ones即先加载用户数据目录下的config.php用户自定义配置再加载仓库根目录的 config-dist.php全量默认值兜底。关键点在于config-dist.php中每一个配置项都不是普通 PHP 常量赋值而是通过Setting()函数定义的例如Setting(MODE, production); Setting(DEFAULT_LOCALE, en); Setting(BASE_URL, /); Setting(FEATURE_FLAG_STOCK, true);而Setting()正是 1.24.0 引入环境变量支持后实现“三级优先级覆盖”的核心函数实现在 helpers/extensions.phpfunction Setting(string $name, $value) { if (!defined(GROCY_ . $name)) { // The content of a $name.txt file in /data/settingoverrides can overwrite the given setting (for embedded mode) $settingOverrideFile GROCY_DATAPATH . /settingoverrides/ . $name . .txt; if (file_exists($settingOverrideFile)) { define(GROCY_ . $name, ExternalSettingValue(file_get_contents($settingOverrideFile))); } elseif (getenv(GROCY_ . $name) ! false) { // An environment variable with the same name and prefix GROCY_ overwrites the given setting define(GROCY_ . $name, ExternalSettingValue(getenv(GROCY_ . $name))); } else { define(GROCY_ . $name, $value); } } }所有设置最终都被定义成形如GROCY_MODE、GROCY_BASE_URL、GROCY_FEATURE_FLAG_STOCK的 PHP 常量供后续代码全局读取例如 app.php 中的GROCY_BASE_URL、GROCY_BASE_PATH参与视图缓存哈希app.php 中GROCY_AUTH_CLASS决定认证中间件。由于defined()做了幂等保护config.php中已显式定义的项不会被二次覆盖——这正是优先级设计能成立的前提。三、三级配置覆盖优先级config-dist.php文件头部的注释config-dist.php与Setting()源码共同确认了完整的覆盖顺序优先级来源说明1最高/data/settingoverrides/设置名.txt与设置同名的.txt文件文件内容即设置值主要服务于嵌入式模式2环境变量GROCY_设置名与设置同名并加上GROCY_前缀例如GROCY_BASE_URL即 1.24.0 新增能力3兜底config-dist.php 中的默认值未做任何外部覆盖时使用的默认配置从源码可见第 1、2 优先级都经由ExternalSettingValue()做值归一化该函数helpers/extensions.php的逻辑是去除字符串首尾的换行符后将小写的true/false转换为 PHP 布尔值其余内容原样保留为字符串。function ExternalSettingValue(string $value) { $tvalue rtrim($value, \r\n); $lvalue strtolower($tvalue); if ($lvalue true) { return true; } elseif ($lvalue false) { return false; } return $tvalue; }这意味着通过环境变量传入的true、TRUE、True以及带尾随换行的true\n都会被正确识别为布尔值与配置文件里写true的效果完全一致其余值则按字符串使用。四、环境变量写法详解命名规则非常简单设置名大写 GROCY_前缀。config-dist.php中每个Setting(NAME, value)都对应一个GROCY_NAME环境变量Setting(MODE, production)→GROCY_MODEproductionSetting(BASE_URL, /)→GROCY_BASE_URL/Setting(BASE_PATH, )→GROCY_BASE_PATH/grocySetting(DEFAULT_LOCALE, en)→GROCY_DEFAULT_LOCALEdeSetting(CURRENCY, USD)→GROCY_CURRENCYEURSetting(FEATURE_FLAG_STOCK, true)→GROCY_FEATURE_FLAG_STOCKfalseSetting(DISABLE_AUTH, false)→GROCY_DISABLE_AUTHtrueSetting(AUTH_CLASS, Grocy\Middleware\Auth\DefaultAuthMiddleware)→GROCY_AUTH_CLASSGrocy\Middleware\Auth\LdapAuthMiddleware布尔型设置传true/false大小写不敏感数值型设置如GROCY_TPRINTER_PORT9100、GROCY_FEATURE_FLAG_STOCK_BEST_BEFORE_DATE_FIELD_NUMBER_PAD等虽然以字符串形式进入但会按外部值原样参与后续逻辑。一个值得注意的特例是数据目录本身虽然GROCY_DATAPATH不属于Setting()体系但 public/index.php 同样支持用环境变量或$_SERVER中的同名变量指定数据目录且支持绝对路径与相对路径两种写法$datapath data; if (getenv(GROCY_DATAPATH) ! false) { $datapath getenv(GROCY_DATAPATH); } elseif (array_key_exists(GROCY_DATAPATH, $_SERVER)) { $datapath $_SERVER[GROCY_DATAPATH]; } if ($datapath[0] ! /) { $datapath __DIR__ . /../ . $datapath; }五、典型应用场景Docker 与不可变基础设施1.24.0 引入环境变量覆盖的动机在变更记录中写得很明确——服务于 grocy-docker 容器镜像。容器化部署中配置文件不便于挂载或重建而环境变量是 Docker 生态的标准配置注入手段具备三个优势配置与镜像解耦同一镜像无需修改任何文件仅靠-e参数即可适配不同实例敏感值不入库GROCY_LDAP_BIND_PW、GROCY_REVERSE_PROXY_AUTH_HEADER这类凭据类配置可以来自编排平台的 Secret 机制避免写入镜像层或代码仓库按环境差异化开发、演示、生产环境仅需切换一组环境变量。一个最小化的docker run示例将 Grocy 部署到https://example.com/grocy子目录并关闭用不到的模块docker run -d \ --name grocy \ -p 80:80 \ -e GROCY_BASE_URLhttps://example.com/grocy \ -e GROCY_BASE_PATH/grocy \ -e GROCY_DEFAULT_LOCALEde \ -e GROCY_CURRENCYEUR \ -e GROCY_FEATURE_FLAG_TASKSfalse \ -e GROCY_FEATURE_FLAG_BATTERIESfalse \ -e GROCY_FEATURE_FLAG_EQUIPMENTfalse \ -v grocy-data:/var/www/html/data \ grocy/grocy使用docker-compose时则可以集中管理services: grocy: image: grocy/grocy ports: - 8080:80 environment: GROCY_MODE: production GROCY_BASE_URL: https://grocy.example.com GROCY_DEFAULT_LOCALE: zh_CN GROCY_CURRENCY: CNY GROCY_ENTRY_PAGE: stock GROCY_FEATURE_FLAG_SHOPPINGLIST: true GROCY_FEATURE_FLAG_RECIPES_MEALPLAN: false GROCY_DATAPATH: /var/www/html/data volumes: - grocy-data:/var/www/html/data volumes: grocy-data:注意环境变量中的布尔值即使写成true/false字符串YAML 中便于统一ExternalSettingValue()也会正确转换为布尔类型因此无需担心字符串与布尔值混用。六、配置校验与生效时机环境变量覆盖后并非直接生效还需要经过启动期的校验。app.php第 42–50 行在容器装配前调用ConfigurationValidator::validateConfig()任一校验失败都会输出Invalid setting in config.php: ...并终止启动try { (new Grocy\Helpers\ConfigurationValidator())-validateConfig(); } catch (\Grocy\Helpers\EInvalidConfig $ex) { exit(Invalid setting in config.php: . $ex-getMessage()); }helpers/ConfigurationValidator.php 中定义了几项硬性规则环境变量取值同样受其约束GROCY_MODE只能是production、dev、demo、prerelease之一CheckModeGROCY_DEFAULT_LOCALE必须在localization目录下真实存在对应的语言文件夹CheckDefaultLocaleGROCY_CURRENCY必须是三位大写字母组成的 ISO 4217 货币代码CheckCurrencyFormatGROCY_CALENDAR_FIRST_DAY_OF_WEEK为空或 0–6 的数字CheckFirstDayOfWeekGROCY_ENTRY_PAGE只能是stock、shoppinglist、recipes、chores、tasks、batteries、equipment、calendar、mealplan之一CheckEntryPageGROCY_MEAL_PLAN_FIRST_DAY_OF_WEEK为空或 -1–6 的数字CheckMealplanFirstDayOfWeek默认用户设置中的夜间模式时间范围必须是HH:mm格式CheckAutoNightModeRangeGROCY_AUTH_CLASS对应的类必须存在CheckAuthClass。此外还有一处联动机制需要留意app.php第 61–77 行用GROCY_BASE_URL、GROCY_BASE_PATH与版本号共同计算 SHA-256 哈希哈希变化时会清空视图缓存并触发数据库迁移跳转。因此变更GROCY_BASE_URL/GROCY_BASE_PATH这类影响 URL 生成的配置后首次访问会自动重建缓存无需手动干预——这也是在容器中改环境变量重启后配置自动生效的底层原因之一。七、注意事项与限制基于源码实现使用环境变量覆盖时有几点边界需要明确仅覆盖Setting()定义的配置config-dist.php中还有一批通过DefaultUserSetting()定义的用户级默认设置如night_mode、stock_due_soon_days等它们走的是$GROCY_DEFAULT_USER_SETTINGS数组helpers/extensions.php不受环境变量机制影响仍通过用户设置界面调整config.php中的显式定义优先如果数据目录下的config.php已用Setting()或直接define()定义了某常量环境变量不会覆盖它Setting()内的defined()检查保证了这一点环境变量机制实际作用的是未在用户配置中声明的项GROCY_DATAPATH是独立通道它决定配置文件config.php本身的位置属于引导级变量必须在应用加载配置前就绪public/index.php 处理适合在容器 EntryPoint 或编排环境层面设置非法值会被启动期拦截如第六节所述模式、货币代码、入口页等受限项传入非法值会导致应用拒绝启动并提示错误这既是约束也是排错线索MODE的连带行为当GROCY_MODE被设置为dev、demo或prerelease时app.php第 28–31 行会自动将用户 ID 固定为 1认证关闭、演示数据生成生产环境请保持production。八、小结Grocy 1.24.0 通过将配置读取统一收敛到Setting()函数并接入环境变量来源helpers/extensions.php在不破坏既有config.php用法的前提下为容器化部署提供了一条干净、可审计、与镜像解耦的配置注入路径。其价值链条清晰可循入口加载public/index.php → app.php默认值全集config-dist.php每个配置项均含注释与取值范围覆盖实现helpers/extensions.php值类型归一化helpers/extensions.php启动期校验helpers/ConfigurationValidator.php对于希望让同一套 Grocy 镜像在多个环境开发/演示/生产、子目录/域名根路径、不同语言与货币间无痛切换的运维者来说环境变量方案是当前版本下最贴合 Docker 生态的配置方式。【免费下载链接】grocyERP beyond your fridge - Grocy is a web-based self-hosted groceries household management solution for your home项目地址: https://gitcode.com/GitHub_Trending/gr/grocy创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表