Geeftlist 0.51.2 配置参数详解
Geeftlist 0.51.2 配置参数逐项实测详解：配置加载体系（config.ini/local.ini/环境变量与 [app]/[api] 段）、站点、注册、邮件、数据库、缓存、安全七大参数组的行为验证与排障实录。
Geeftlist 0.51.2 配置参数详解
目标：对 Geeftlist 0.51.2 的配置参数做逐项说明与行为实测，明确"每个参数改了会发生什么"。安装过程见《Ubuntu 22.04 安装 Geeftlist 0.51.2 指南》，项目定位见《Geeftlist 介绍与选型指南》。本文默认值均摘自应用自带配置文件
src/etc/config.ini与src/etc/app.ini（标注行号），行为结论均为实测环境验证所得。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04（x86_64） |
| 应用版本 | Geeftlist 0.51.2（源码安装，/var/www/webapp） |
| 运行组件 | Apache/2.4.52 + PHP 8.3.36 + MariaDB 10.6.23 + Redis 6.0.16 |
| 访问地址 | http://localhost:8150/ |
| 参数核对手段 | php ./src/console system/dumpConfig（加载后的实际参数值） |
二、配置加载体系
2.1 三层配置源与优先级
Geeftlist 的配置按以下优先级从低到高合并（后者覆盖前者，实测验证）：
| 层 | 文件/来源 | 定位 |
|---|---|---|
| 1. 出厂默认 | src/etc/config.ini（F3 全局变量）、src/etc/app.ini（应用参数） | 随源码分发，不应修改 |
| 2. 部署覆盖 | src/etc/local.ini | 部署者自有的差异配置，推荐入口 |
| 3. 环境变量 | 前缀 app__*（应用参数）/ F3__*（F3 变量），__ 对应层级分隔 | 打包部署形态的临时覆盖场景，优先级最高 |
2.2 [app] 段与 [api] 段的分界
local.ini 中 [app] 段的参数全局加载（Web、CLI、API 三种上下文都可见），[api] 段仅在 API 上下文加载。实测中最典型的事故就是把这个分界搞反：把 AUTHENTICATION_JWT_SECRET_KEY 只写在 [api] 段，Web 上下文读不到密钥，整站跳 /error（见排障实录第 2 条）。原则：密钥类、连接类参数一律写 [app] 段。
2.3 CLI 上下文的额外配置
CLI 入口（src/console → src/cli.php）在 Web 配置之外还会加载 config-cli.ini、app-cli.ini 等 CLI 专属文件，因此 CLI 与 Web 的行为可能不一致（典型：PASSWORD_MIN_LENGTH 对 CLI 不生效，见 4.2 节）。
2.4 参数核对与生效流程
改动 local.ini 后必须清缓存才生效，然后可用 system/dumpConfig 核对实际加载值。实测输出（头部）：
php ./src/console system/dumpConfig
Array
(
[TITLE] => Geeftlist 实验站
[VERSION] => dev
[DB_VERSION_SCHEMA] => 0.50.0
[DB_VERSION_DATA] => 0.36.0
[DB_VERSION_SAMPLEDATA] => 0.39.0
[BASE_URL] => http://localhost:8150/
[MODE] => production
[SETUP_SCRIPTS_DIR] => app/code/Geeftlist/setup/
[URL_DEFAULT_FORCE_SCHEME] => 0
[USE_X_FORWARDED_HOST] => 1
[DB_CONNECT_TIMEOUT] => 20
[MAINTENANCE_FLAG] => var/lock/maintenance.flag
💡 注意
[VERSION] => dev：源码直装（--depth 1拉取 tag）不带标签元数据，版本号显示为dev，属正常现象，与参数无关。
三、全局与站点参数
3.1 DEBUG（[globals] 段）
- 默认值：
1（config.ini:6）；本文实测配置为2 - 作用：Fat-Free 框架调试级别，同时影响错误显示与日志行为；应用日志级别也跟随它（
app.ini:85注释明确 LOG_LEVEL 保持注释、按globals.DEBUG取特殊行为） - 实测：
DEBUG=0时日志初始化失败，整站 500 并报Could not parse file: etc/monolog.yml（排障实录第 1 条）；恢复2后正常 - 建议：生产保持
2，不要设0
3.2 MODE（[app] 段）
- 默认值：
production（app.ini:12） - 作用：运行模式标记。实测
dumpConfig中显示[MODE] => production；日常部署无需改动
3.3 TITLE（[app] 段）
- 默认值：
Geeftlist（app.ini:6） - 作用：站点名称，出现在页面标题与页脚。实测改为
Geeftlist 实验站后，dumpConfig显示[TITLE] => Geeftlist 实验站，页面页脚同步显示
3.4 BASE_URL（[app] 段）
- 默认值：
https://geeftlist.local/（app.ini:11） - 作用：全站链接生成的基础地址。不匹配实际访问地址是常见故障源：实测改为
http://localhost:8150/后页面资源路径正确（如http://localhost:8150/asset/default/js/app.js）；若保持默认而实际走其他地址/端口，页面会引用错误域名导致样式脚本 404 - 建议：与真实访问协议+域名+端口严格一致
3.5 TIMEZONE（[app] 段）
- 默认值：
UTC（app.ini:226） - 作用：页面显示时区。实测设为
Asia/Shanghai；注意应用日志（src/var/log/app.log）时间戳仍为+00:00（UTC）格式，二者独立，不要用日志时间判断时区参数是否生效
3.6 SHOW_VERSION（[app] 段）
- 默认值：
0（app.ini:231） - 作用：控制页脚版本号显示（模板逻辑：
SHOW_VERSION为真时页脚输出站点名 + VERSION，否则该段为空，见src/app/template/default/page/footer.phtml） - 实测：设为
1并清缓存后，页脚出现：
<p class="app-version">
Geeftlist 实验站 dev <span class="powered-by">Powered by <a href="http://localhost:8150/about">Free Software</a></span>
对公网站点建议保持默认 0 隐藏版本信息（减少版本指纹暴露）。
四、账户与注册参数
4.1 GEEFTER_REGISTRATION_ENABLE（[app] 段）
- 默认值：
1（app.ini:150） - 作用：开放/关闭自助注册
- 实测：设为
0后注册页提交不再创建用户（提交被拒、geefter表无新增记录）；已注册用户登录不受影响 - 建议：家庭小圈子场景建议邀请制——先关闭自助注册，用站内邀请功能拉人
4.2 PASSWORD_MIN_LENGTH（[app] 段）
- 默认值：
8（app.ini:141） - 作用：Web 端密码最小长度校验
- 实测：设为
12后 Web 端按新长度校验；但 CLI 通道（geefter/setPassword命令重置密码）不受该参数约束，8 位密码可经命令行设置成功——这是 2.3 节所述"CLI 加载独立配置"的直接体现 - 建议：运维用 CLI 重置密码时自行保证强度；不能把"Web 校验通过"当作全通道保证
4.3 CAPTCHA_* 组（[app] 段）
| 参数 | 默认值（app.ini） | 作用 |
|---|---|---|
| CAPTCHA_GEEFTER_SIGNUP_ENABLE | 1（:187） | 注册表单验证码 |
| CAPTCHA_INVITATION_CREATION_ENABLE | 1（:188） | 创建邀请的验证码 |
| CAPTCHA_CONTACT_GEEFTER_ENABLE | 0（:189） | 联系成员表单验证码 |
| CAPTCHA_CONTACT_VISITOR_ENABLE | 1（:190） | 访客联系表单验证码 |
实测将 CAPTCHA_GEEFTER_SIGNUP_ENABLE 设为 1 时注册表单出现验证码字段；无图形环境（无 SMTP/纯 API 演练）可按需关闭。默认全开的两个入口即注册与邀请创建，符合"注册入口防滥用"的取向。
五、邮件与通知参数
5.1 参数清单（[app] 段，默认值摘自 app.ini:119-134）
| 参数 | 默认值 | 说明 |
|---|---|---|
| EMAIL_ENABLED | 1 | 邮件功能总开关 |
| EMAIL_ADMIN | admin@geeftist.local | 管理员收件地址（上游默认值拼写即有笔误：geeftist 少了 l，部署时应覆盖） |
| EMAIL_ABUSE | abuse@geeftist.local | 滥用举报收件地址（同样需覆盖） |
| EMAIL_CONTACT | contact@geeftlist.local | 联系表单收件地址 |
| EMAIL_DEFAULT_SENDER | Geeftlist <noreply@geeftlist.local> | 默认发件人 |
| EMAIL_TEMPLATE_TTL | 1800 | 邮件模板缓存时长（秒） |
| EMAIL_TEMPLATE_THEME | email-default | 邮件模板主题 |
| EMAIL_MAILER_DSN | smtp://localhost:25 | SMTP 连接串（symfony/mailer DSN 格式） |
| SKIP_EMAIL_CHECK_MX | 0 | 跳过注册邮箱域 MX 校验 |
| NO_CONFIRMATION_EMAIL | 0 | 注册时不发确认邮件 |
| NOTIFICATION_DEFER_DELAY | 20 | 通知延迟合并窗口（秒） |
| NOTIFICATION_DEFER_MAX_COUNT | 12 | 单次合并发送的通知上限 |
5.2 无 SMTP 环境的最小配置（实测组合）
EMAIL_ENABLED=0
NO_CONFIRMATION_EMAIL=1
SKIP_EMAIL_CHECK_MX=1
实测该组合下：注册流程不依赖邮件服务器即可完成（新用户可直接登录）；邮箱域无 MX 记录（如内部域 .local）也不会在注册环节被拒（对照实测：未开启 SKIP_EMAIL_CHECK_MX 时 .local 域注册不生效）。邮件功能连通性可用 dev/sendTestEmail 命令自测（实测回显 Done.，命令细节见 CLI 篇）。
六、数据库连接参数（[app] 段）
| 参数 | 默认值 | 说明 |
|---|---|---|
| RESOURCE_CONFIG.db.driver | Pdo_Mysql | 驱动，保持默认 |
| RESOURCE_CONFIG.db.database | —— | 库名，实测 geeftlist |
| RESOURCE_CONFIG.db.username / password | —— | 连接凭据，最小授权只给本库 |
| RESOURCE_CONFIG.db.hostname | —— | 实测 127.0.0.1 |
| RESOURCE_CONFIG.db.port | —— | 实测 3306 |
| RESOURCE_CONFIG.db.charset | —— | 实测 utf8mb4（应用安装即 28 张表，含中文标题场景，勿降为 utf8） |
| DB_CONNECT_TIMEOUT | 20（dumpConfig 实测确认） | 连接超时（秒） |
实测故障行为：把 password 改成错误值并清缓存后，首页返回 503（应用进入不可用状态而非白屏），恢复正确值并 cache/clear 后复原。数据层部署与调优可参考《MariaDB 11.8 配置参数详解》。
七、缓存连接参数（[app] 段）
| 参数 | 说明 |
|---|---|
| RESOURCE_CONFIG.redis_cache.host | 实测 127.0.0.1 |
| RESOURCE_CONFIG.redis_cache.port | 实测 6379 |
| RESOURCE_CONFIG.redis_cache.database | 实测 0（多实例部署时可与测试环境分库） |
实测故障行为：停止 Redis 后首页与 /system/healthcheck 立即返回 500——Redis 是硬依赖而非可选加速层，监控应把它纳入与数据库同级的基础设施告警。缓存层的安装部署可参考《Ubuntu 22.04 安装 Redis 8 指南》。
八、安全与访问控制参数
8.1 两把密钥（[app] 段，必须显式设置）
| 参数 | 默认值 | 用途 |
|---|---|---|
| GEEFTER_SESSION_SECRET_KEY | 未设（app.ini:144 注释 changeme） | 会话加密密钥 |
| AUTHENTICATION_JWT_SECRET_KEY | 未设（app.ini:240 注释 changeme） | API Token（JWT）签名密钥 |
实测 AUTHENTICATION_JWT_SECRET_KEY 缺失时 Web 上下文报 InvalidKeyProvided: Key cannot be empty 并跳转 /error（排障实录第 2 条）。生成方式：
openssl rand -base64 48
两把密钥独立生成、不要复用；写入 [app] 段（[api] 段可选同名同值，仅供 API 上下文强调）。
8.2 HEALTHCHECK_ALLOWED_IPS
- 默认值：
127.0.0.1/8,::0,172.16.0.1/12（app.ini:27） - 作用：
/system/healthcheck（Prometheus 指标端点）的调用方 IP 白名单（CIDR 列表，逗号分隔） - 实测：监控端 IP 不在名单时返回 403；将其网段加入并清缓存后恢复 200
- 建议：接入 Prometheus 时显式写入监控机网段，保留
127.0.0.1/8
8.3 CRON_ALLOWED_IPS
- 默认值：
127.0.0.1/8,::0,172.16.0.1/12（app.ini:26） - 作用：
/cron/run触发端的 IP 白名单，机制与 8.2 相同（源码中两个控制器取值逻辑相邻，均为不在范围抛 403） - 实测：设为
10.99.0.0/24后本机请求/cron/run返回 403；恢复默认后返回 200 - 注意：若用系统定时器在本机
curl 127.0.0.1/cron/run，默认值即满足；若由独立跳板机触发，必须把跳板机 IP 加入名单
九、参数变更流程与验证
一次完整的参数变更（实测流程）：
# 1. 编辑 local.ini（只在 [app]/[globals] 段动参数）
sudo vi /var/www/webapp/src/etc/local.ini
# 2. 清缓存使新值生效
cd /var/www/webapp && sudo -u www-data php8.3 ./src/console cache/clear
# 3. 核对加载值
php8.3 ./src/console system/dumpConfig | grep -A2 "参数名"
# 4. 行为验证（按参数对应端点实测）
第 2 步实测回显：
OK, cache has been cleared.
跳过清缓存是"改了没生效"的第一大原因。快速系统核对可用 system/sysinfo（输出 F3 运行时 hive 数组，实测首行起为 AGENT/AJAX/ALIAS/AUTOLOAD/...），命令细节见《Geeftlist 0.51.2 常用 CLI 命令与工具详解》。
十、常见问题与排障实录
10.1 DEBUG=0 导致整站 500
现象：将 [globals] DEBUG 从 2 改 0 并清缓存后全站 500，日志报 Could not parse file: etc/monolog.yml。
原因：实测 0.51.2 在 DEBUG=0 下日志配置初始化失败，属该版本可用性边界。
处置：DEBUG 保持 2。
10.2 JWT 密钥写在 [api] 段导致整站跳 /error
现象：AUTHENTICATION_JWT_SECRET_KEY 只写入 [api] 段，首页 302 跳 /error，error.log 报 InvalidKeyProvided: Key cannot be empty。
原因：[api] 段仅 API 上下文加载，Web 上下文读不到。
处置：密钥写入 [app] 段并 cache/clear。
10.3 停 Redis 后全站 500
现象：Redis 服务停止后首页与 /system/healthcheck 均 500。
原因：缓存层为硬依赖（见第七章）。
处置：恢复 Redis 并确认应用自愈；监控侧对 Redis 做同级告警。
10.4 数据库口令错误返回 503
现象：改错 RESOURCE_CONFIG.db.password 后首页 503。
原因：数据库连接失败进入维护态（503 而非 500，可与缓存故障的 500 区分定位）。
处置：恢复正确凭据并 cache/clear。
10.5 白名单参数加了却不生效
现象：为限制 /cron/run 调用方，把 CRON_ALLOWED_IPS=10.99.0.0/24 追加到 local.ini 文件末尾，实测本机请求仍返回 200（未按预期 403）。
原因：local.ini 文件末尾是 [api] 段作用域，该行实际写进了 [api] 段；[app] 段仍取默认白名单（含 127.0.0.1/8）。
处置：插入到 [app] 段内后实测 403/200 行为恢复正常（见 8.3）。教训：INI 段内追加参数时先确认当前段落。
10.6 CLI 重置密码不受 PASSWORD_MIN_LENGTH 约束
现象：PASSWORD_MIN_LENGTH=12 生效后，CLI geefter/setPassword 仍可设置 8 位密码。
原因：CLI 上下文加载独立的 *-cli.ini 配置链，且该命令走内部通道不做 Web 校验（见 4.2）。
处置：视为特性使用（运维救援通道），同时建立口令强度的人工把关。
十一、参考链接
- 应用配置文件：
src/etc/config.ini、src/etc/app.ini、src/etc/local.ini.sample（均溯源自官方仓库 codeberg.org/nanawel/geeftlist tag 0.51.2，查询日期 2026-10-28） - Fat-Free Framework 配置文档：https://fatfreeframework.com/3.8/configuration-and-routing
- 站内配套文档：
- 《Geeftlist 介绍与选型指南》——架构与参数体系的整体背景
- 《Ubuntu 22.04 安装 Geeftlist 0.51.2 指南》——首次配置 local.ini 的完整上下文
- 《Geeftlist 0.51.2 常用 CLI 命令与工具详解》——cache/clear、dumpConfig 等命令细节
- 《MariaDB 11.8 配置参数详解》——数据库层参数参考
- 《Ubuntu 22.04 安装 Redis 8 指南》——缓存层部署参考