Geeftlist 0.51.2 常用 CLI 命令与工具详解

目标：覆盖 Geeftlist 0.51.2 自带命令行工具（src/console）的全部命令组，逐个给出语法、实测回显与运维用途。Geeftlist 当前没有 Web 管理后台（官方路线图项，见《Geeftlist 介绍与选型指南》），安装、诊断、维护、密码救援均依赖本文的命令行，是这套系统的实际"管理后台"。参数行为配套见《Geeftlist 0.51.2 配置参数详解》。

一、环境信息

二、命令行工具总览

2.1 入口与调用形态

CLI 入口为应用自带脚本 src/console（内容仅两行：shebang + 加载 cli.php）。命令必须带命令组前缀，实测两种形态对比：

php8.3 ./src/console sysinfo          # 实测 404（缺组前缀）
php8.3 ./src/console system/sysinfo   # 实测正常

前者实测报错：

HTTP 404 (GET /sysinfo)
[/vendor/bcosca/fatfree-core/base.php:1834] Base->error()
[/app/code/OliveOil/Core/Bootstrap.php:61] Base->run()
[/cli.php:76] OliveOil\Core\Bootstrap->run()
[/console:2] require()

2.2 命令清单（8 组 21 个，实测自源码路由与控制器）

⚠️ 实测发现：不带参数直接执行 php8.3 ./src/console 只输出 Available actions: 加一行 NOT IMPLEMENTED...——0.51.2 尚未实现内置帮助，命令清单以本文与源码 src/etc/routing-cli.ini 为准。

三、系统诊断命令（system 组）

3.1 system/sysinfo：运行时变量

打印 F3 框架运行时 hive 数组，实测输出头部：

Array
(
    [AGENT] => 
    [AJAX] => 
    [ALIAS] => 
    [AUTOLOAD] => ./app/
    [BASE] => 
    [BITMASK] => 2

用于确认 CLI 进程实际加载的框架环境，排查"AUTOLOAD 路径不对""BASE 为空"类问题。

3.2 system/dumpConfig：实际生效配置

打印合并后的应用参数（含 local.ini 覆盖结果），实测头部：

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

DB_VERSION_SCHEMA/DATA 同时是升级核对依据，改参数后用它验证生效值（详见参数详解篇第九章流程）。

3.3 system/waitForDb：数据库可用性探测

php8.3 ./src/console system/waitForDb

实测回显：

** Checking database server access...
Array
(
    [driver] => Pdo_Mysql
    [database] => geeftlist
    [username] => geeftlist
    [password] => ********
    [hostname] => 127.0.0.1
    [port] => 3306
    [charset] => utf8mb4
)

max_execution_time set to: 0
Database connection suceeded

连接参数数组中密码自动打码；suceeded 为上游原文拼写。数据库重启窗口可把它放在启动脚本里做"等库再起应用"的栅栏。

3.4 维护模式：startMaintenance / endMaintenance

实测闭环：进入维护模式后站点首页立即 503，健康检查端点仍可输出指标；退出后恢复 200。

php8.3 ./src/console system/startMaintenance
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/
php8.3 ./src/console system/endMaintenance
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/

实测两次状态码：

503
200

适合升级、备份恢复演练前挂维护页。维护开关落盘为 var/lock/maintenance.flag（dumpConfig 中 [MAINTENANCE_FLAG]）。

四、安装与升级命令（setup 组）

4.1 setup/isInstalled

php8.3 ./src/console setup/isInstalled

实测回显：

Application is installed.

4.2 setup/install

全新安装入口，实测过程与回显见《Ubuntu 22.04 安装 Geeftlist 0.51.2 指南》（6.5 节），成功收尾为 Installation finished successfully + Success.。

4.3 setup/upgrade

版本升级脚本执行器，重复执行幂等：

php8.3 ./src/console setup/upgrade

实测回显（已是最新版本时）：

2026-10-28T07:38:06+00:00 [10 MB] NOTICE Nothing to do! []
2026-10-28T07:38:06+00:00 [10 MB] INFO Upgrade finished successfully []
Success.

⚠️ setup/uninstall、setup/downgrade 及三个示例数据（SampleData）命令会改写或删除业务数据，本文遵循"演练环境不执行破坏性命令"原则未实测；使用前务必先做第十章的备份，并阅读源码确认影响面。

五、缓存命令（cache 组）

实测四个子命令行为：

前三个命令的运维定位不同但回显文案一致；日常改配置后用 cache/clear 即可。cache/invalidate --tags 适合细粒度刷新（标签名即实体码，如 geefter、gift）。

六、依赖注入命令（di 组）

应用把 DI 容器编译为 src/var/di/ 下的 PHP 文件加速启动，两个子命令实测：

php8.3 ./src/console di/clean

实测回显：

OK, compiled DI directory has been cleared.

di/clear 同样清理编译目录。DI 编译文件损坏、容器类冲突时执行，下一次请求会自动重建（首次请求略慢）。

七、账户与词典命令（geefter 组 + dev 组）

7.1 geefter/setPassword：密码救援

目标用户以 --id 或 --email 指定，新密码经 stdin 交互输入两次（无回显）。实测：

printf 'q1w2e3r4\nq1w2e3r4\n' | php8.3 ./src/console geefter/setPassword --email=admin@example.com

实测回显：

Geefter: admin
Email  : admin@example.com

New hash: $2y$10$EUatNtyIuAu7jTB85L50FuIRGx7j30KUm5RRYuzIUnuJDh.BaTjz.

实测不指定目标用户时：

You need to specify --id=<id> or --email=<email>

注意：该通道不受 PASSWORD_MIN_LENGTH 约束（实测 8 位密码可设置成功，见参数详解篇 4.2/10.6），是忘记密码时的标准救援路径。

7.2 geefter/calculatePasswordHash

php8.3 ./src/console geefter/calculatePasswordHash q1w2e3r4

实测回显：

Hash: $2y$10$lAAfG/jSzQpm7lLNf3Kb0ezBKIPVbKe9o6kGRmQgMtup0lQJsM5oG

用于核对/手工迁移口令字段（bcrypt，$2y$ 前缀）。

7.3 dev/sendTestEmail

php8.3 ./src/console dev/sendTestEmail

实测回显：

Done.

SMTP 配置调通与否的最快验证手段（配合 EMAIL_MAILER_DSN，见参数详解篇第五章）。

7.4 dev/dictSync：词典同步（实测踩坑）

该命令重新生成 src/app/dict/ 下词典文件。实测执行报 Permission denied——src/app/dict/ 属 root 而执行者为 www-data。处置：

sudo chown -R www-data:www-data /var/www/webapp/src/app/dict

授权后可正常同步。此目录在源码安装时容易被权限清单遗漏（安装篇排障实录 8.7 亦收录）。

八、索引与维护命令（indexer 组 + housekeeping 组）

8.1 indexer/reindexAll

php8.3 ./src/console indexer/reindexAll

实测回显：

Refreshing index gift/geefterAccess... Finished in 00:00:00.
Refreshing index discussion/topic/geefterAccess... Finished in 00:00:00.

重建全部访问控制索引（礼物的家庭成员可见性、讨论区成员访问）。升级或数据手工修复后建议执行；单索引重建用 indexer/reindex。

8.2 housekeeping/pruneBrokenEntityLinks

清理实体间的失效关联，需 --entityType 参数。实测三步定位可用取值：

php8.3 ./src/console housekeeping/pruneBrokenEntityLinks

Missing --entityType option.

php8.3 ./src/console housekeeping/pruneBrokenEntityLinks --entityType=geefter

Pruning broken entity links on geefter...
Unsupported entity type: geefter [/var/www/webapp/src/app/code/Geeftlist/Service/System/Housekeeping.php:43]

php8.3 ./src/console housekeeping/pruneBrokenEntityLinks --entityType=activity

Pruning broken entity links on activity...
Finished in 00:00:00.

实测结论：可用取值为 activity、share_entity_rule、discussion_topic（源码中以 pruneBroken<Entity> 方法名映射，并非任意实体码），不支持 geefter/gift 等业务实体码。

九、定时任务触发与健康自检

应用内置调度器由 HTTP 端点触发而非 console 命令（设计上与 Web 同生命周期），部署侧用系统 cron 每 5 分钟请求一次：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/cron/run

实测回显：

200

触发端 IP 受 CRON_ALLOWED_IPS 白名单限制（实测改白名单后 403/200 闭环，见参数详解篇 8.3）。执行效果可在 /system/healthcheck 的 geeftlist_cron_last_run 指标核对（时间戳随触发更新，实测）。

十、数据库备份与恢复闭环（实测演练）

以"备份 → 模拟事故 → 恢复 → 业务验证"完整闭环验证（命令在 /var/www/webapp 执行）：

10.1 备份

mariadb-dump -ugeeftlist -pq1w2e3r4 geeftlist > /tmp/geeftlist-backup.sql
ls -lh /tmp/geeftlist-backup.sql

实测回显：

-rw-r--r-- 1 root root 59K Oct 28 07:39 /tmp/geeftlist-backup.sql

10.2 模拟事故并恢复

mariadb -e "DROP DATABASE geeftlist; CREATE DATABASE geeftlist CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mariadb -ugeeftlist -pq1w2e3r4 geeftlist < /tmp/geeftlist-backup.sql && echo "restore OK"

实测回显：

restore OK

10.3 恢复后验证

mariadb -ugeeftlist -pq1w2e3r4 -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='geeftlist';"
php8.3 ./src/console cache/clear
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/login
mariadb -ugeeftlist -pq1w2e3r4 -N -e "SELECT username FROM geeftlist.geefter ORDER BY geefter_id;"

实测回显：

28
OK, cache has been cleared.
200
admin
bob
carol

28 张表完整恢复、登录页 200、三个用户数据无损。演练要点：恢复后必须 cache/clear——Redis 中可能残留指向旧数据的缓存键，实测清缓存后访问才稳定正常。

10.4 与 CLI 命令的配合

生产建议流程：system/startMaintenance（503 保护）→ 备份/恢复 → system/endMaintenance → cache/clear → indexer/reindexAll，形成一次完整的维护窗口操作序列。

十一、常见问题与排障实录

11.1 命令报 HTTP 404

现象：php8.3 ./src/console sysinfo 404，system/sysinfo 正常。 原因：命令必须带组前缀（2.1 节实测）。 处置：全部命令按 <组>/<action> 调用。

11.2 帮助命令未实现

现象：无参数执行 console 仅输出 Available actions: + NOT IMPLEMENTED...。 处置：以本文命令清单与源码 src/etc/routing-cli.ini 为准（2.2 节）。

11.3 housekeeping 实体类型不匹配

现象：--entityType=geefter 报 Unsupported entity type。 原因：参数值不是实体码，而是内部清理方法的映射名。 处置：使用 activity / share_entity_rule / discussion_topic（8.2 节实测）。

11.4 dictSync 权限拒绝

现象：dev/dictSync 报 Permission denied。 原因：src/app/dict/ 未授权给运行用户。 处置：chown -R www-data:www-data（7.4 节）。

11.5 setPassword 目标参数遗漏

现象：直接执行报 You need to specify --id=<id> or --email=<email>。 处置：--email=<邮箱> 指定目标，密码经 stdin 两次输入（7.1 节）。

11.6 恢复数据库后访问异常

现象：恢复备份后页面行为不稳定。 原因：Redis 残留旧缓存键。 处置：恢复后立即 cache/clear（10.3 节实测含此步）。

十二、参考链接

• CLI 路由定义：src/etc/routing-cli.ini、控制器源码 src/app/code/Geeftlist/Controller/Cli/*.php（溯源自官方仓库 codeberg.org/nanawel/geeftlist tag 0.51.2，查询日期 2026-10-28）
• MariaDB 备份文档：https://mariadb.com/kb/en/backup-and-restore-overview/
• 站内配套文档：
  • 《Geeftlist 介绍与选型指南》——无管理后台的定位背景
  • 《Ubuntu 22.04 安装 Geeftlist 0.51.2 指南》——setup/install 与首次部署
  • 《Geeftlist 0.51.2 配置参数详解》——cache/clear 与白名单参数联动
  • 《MariaDB 11.8 配置参数详解》——备份恢复的数据层参考
  • 《Ubuntu 22.04 安装 Redis 8 指南》——缓存层运维参考