Galette 1.3.1 常用 CLI 命令与工具详解

目标：系统梳理 Galette 1.3.1 自带的命令行工具——以 Symfony Console 实现的 bin/console 及其 galette:* 命令族（共 19 条），覆盖安装、环境诊断、运维保障、开发辅助与插件管理五类，逐条给出用途、参数与实测回显，并给出生产环境的三种组合用法（邮件队列 cron、超管密码重置、演示数据注入与清理）。全部命令均在实测站点上执行验证（站点部署见《Ubuntu 22.04 安装 Galette 1.3.1 指南》）。

一、环境信息

本文实测环境（与前篇同一站点）：

操作系统：Ubuntu 22.04；PHP 8.3.36（CLI）；MariaDB 10.6.23；Apache 2.4.52
Galette：1.3.1（官方 tarball 部署于 /var/www/galette-1.3.1，命令行入口 /var/www/galette-1.3.1/bin/console）
数据库：galette 库（账号 galette，密码 q1w2e3r4）
后台超管：admin（密码 q1w2e3r4）
命令执行身份：Web 服务运行用户 www-data（应用需要读写 config/ 与 data/ 目录）

二、前置条件

已完成 Galette 1.3.1 安装，config/config.inc.php 已生成（未装请先看《Ubuntu 22.04 安装 Galette 1.3.1 指南》）；
服务器上具备 PHP CLI 与 sudo 权限（以 www-data 身份执行命令）；
了解 Symfony Console 通用参数（所有命令都支持 --help 在线帮助、-n 免交互、-v/-vv/-vvv 三级详细输出）。

三、CLI 入口与命令总览

Galette 的命令行入口是解压根目录的 bin/console（不是 galette/bin/ 下的内部文件），以 Web 运行用户执行：

cd /var/www/galette-1.3.1
sudo -u www-data php bin/console list

实测回显（可用命令清单）：

Galette version v1.3.1

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, and 3 for debug

Available commands for the "galette" namespace:
  galette:check-routes                Check Galette routes naming conventions
  galette:checks                      Check PHP requirements and permissions
  galette:compile-locales             Compile translation files (PO) into MO files, for the core and plugins
  galette:feature:disable             Disable a feature flag
  galette:feature:enable              Enable a feature flag
  galette:feature:status              Display status of all registered feature flags
  galette:headers:check               Check for missing or invalid file headers
  galette:install                     Install Galette
  galette:mailing:process-queue       Process the mailing queue
  galette:plugins:disable             Disable a plugin
  galette:plugins:enable              Enable a plugin
  galette:plugins:install-db          Install or update a plugin database
  galette:plugins:list                List existing Galette plugins
  galette:seed-fixtures               Seed database with E2E test fixtures
  galette:superadmin:password         Change the super administrator password
  galette:twig-cache                  Compile Twig templates in cache
  galette:twig-pot-references         Update translation POT references from Twig templates
  galette:twofactor:reset             Reset two-factor authentication

19 条命令按用途分五类：

类别	命令	一句话用途
安装与迁移	galette:install	命令行安装/更新实例
环境诊断	galette:checks / galette:check-routes / galette:headers:check	运行环境自检、路由命名核查、代码头核查
运维保障	galette:superadmin:password / galette:twofactor:reset / galette:mailing:process-queue	密码重置、两步验证重置、群发队列处理
插件管理	galette:plugins:list / enable / disable / install-db	插件四件套
特性与开发	galette:feature:status / enable / disable、galette:seed-fixtures、galette:twig-cache / twig-pot-references / compile-locales	特性开关、演示数据、模板缓存与翻译链

💡 说明：除上述 galette:* 命令族外，list、help 等Symfony Console 内建命令同样可用；php bin/console --version 实测输出 Galette version v1.3.1，可直接用于版本核对。Galette 核心 1.3.1 未提供 REST API（路由核查中无 api 前缀路由），所有自动化均走本 CLI 或数据库层；acls/oauth2/api-v2 三个特性开关仍处于源码注释中的规划阶段（见《Galette 1.3.1 配置参数详解》 5.10 节）。

四、命令逐条详解

4.1 galette:install——命令行安装/更新

用途与用法已在安装篇完整实测（6 项权限 ✔️ 核验、三阶段执行、[OK] Galette installation is complete! 实录），此处不重复；参数清单与选择建议见《Ubuntu 22.04 安装 Galette 1.3.1 指南》第五章。要点回顾：-w 写配置文件、--ignore-config 覆盖重装、不带 --dbprefix 时会交互询问（实测回显 Database prefix [galette_]:）。

4.2 galette:checks——环境自检（运维首查命令）

检查 PHP 版本、15 项模块与依赖是否满足。实测执行与回显：

cd /var/www/galette-1.3.1
sudo -u www-data php bin/console galette:checks

Galette requirements checks
===========================

 * ✔️ PHP version: 8.3.36
 * ✔️ 'SimpleXML' module
 * ✔️ 'ctype' module
 * ✔️ 'dom' module
 * ✔️ 'fileinfo' module
 * ✔️ 'filter' module
 * ✔️ 'gd' module
 * ✔️ 'gettext' module
 * ✔️ 'iconv' module
 * ✔️ 'intl' module
 * ✔️ 'mbstring' module
 * ✔️ either 'mysql' or 'pgsql' PDO driver
 * ✔️ 'session' module
 * ✔️ 'curl' module
 * ✔️ 'openssl' module

Directories rights are not checked from the command line, it is not reliable enough

 [OK] Everything is OK :)

适用场景：装完复检、系统升级（apt 大版本升级/换 PHP 仓库）后复检、迁移前体检。输出末尾明确提示目录权限无法从命令行可靠检查，需要按安装篇 7.2 节人工确认 data/ 可写。

4.3 galette:superadmin:password——超管密码重置

忘记超管密码时的救援命令（1.3.0 新增）。交互式输入新密码，无需 --help 之外参数（实测帮助仅通用项）：

sudo -u www-data php bin/console galette:superadmin:password

执行后按提示输入新密码两遍即重置 galette_preferences 表中 pref_admin_pass 的 bcrypt 哈希（参数存储细节见配置篇 5.11 节）。适用场景：管理员离职/密码遗失、初始密码遗忘。注意该命令改的是超级管理员（表内 admin 记录），普通管理员密码仍走后台或邮件找回流程。

4.4 galette:twofactor:reset——两步验证重置

会员丢失手机（TOTP 设备）后的管理员侧救援命令（实测帮助确认存在）。交互输入会员登录名后清除其第二因子绑定，会员即可用密码单独登录并重新配对。与 1.3.0 官网公告中"administrators can reset the second factor of a member who lost their phone"（后台操作）等价的命令行路径。前提：实例启用了两步验证（默认关闭；强制开启需要 two-factor-required 特性开关）。

4.5 galette:mailing:process-queue——群发队列处理

1.3.0 邮件分批发送的队列消费命令（实验特性）。实测帮助关键参数：

Description:
  Process the pending mass mailing queue, respecting configured limits

Usage:
  galette:mailing:process-queue [options]

Options:
      --force           Send without asking for confirmation (required to run unattended)

--force 免确认（官方注释明确：无人值守运行必须加它）。生产组合用法见 6.1 节；间隔与配额上限在高级配置页设置（官网公告原文），未配置时保持旧行为（一次性发送）。

4.6 galette:plugins:list / enable / disable / install-db——插件四件套

本站未装插件，galette:plugins:list 实测回显为空列表：

Galette plugins
===============

装插件后的管理路径（按命令帮助）：--complete/--enabled/--disabled 三种过滤的清单查看；galette:plugins:enable <插件目录名> / galette:plugins:disable <插件目录名> 启停；galette:plugins:install-db <插件目录名> 负责插件的建表与升级（1.3.0 起每个插件有独立数据库版本号，官网公告原文，该命令即其升级入口）。与后台插件页（列出已启用/已禁用/未安装/待更新四类）等效，命令行适合批量与无人值守。

4.7 galette:feature:status / enable / disable——特性开关三件套

galette:feature:status 全量回显已在配置篇 5.10 节实录（1.3.1 仅注册 two-factor-required 一个 flag，默认 DISABLED，统计区显示 Total registered flags: 1）。启停语法（实测帮助）：

sudo -u www-data php bin/console galette:feature:enable two-factor-required
sudo -u www-data php bin/console galette:feature:disable two-factor-required

状态持久化进数据库（status 的 Source 列显示 config/environment/database 三个来源），与后台高级配置页的 feature 区块等效；behavior.inc.php 的 GALETTE_FEATURE_FLAGS 强制声明优先级最高。

4.8 galette:seed-fixtures——E2E 演示数据注入/清理

开发与演示环境专用（帮助原文："Seed database with E2E test fixtures (fictional members, contributions, groups, etc.)"）。两个用法：

sudo -u www-data php bin/console galette:seed-fixtures        # 注入虚构会员/缴费/群组
sudo -u www-data php bin/console galette:seed-fixtures --clean  # 全部移除后退出

⚠️ 注意：该命令直接写业务库（会员表、缴费表、群组表），只用于测试/演示实例；--clean 是配套的完整卸载动作。生产实例禁用。

4.9 模板与翻译链：twig-cache / twig-pot-references / compile-locales

三条服务于模板缓存与多语言维护的辅助命令（实测帮助）：

galette:twig-cache [<plugin>]：预编译 Twig 模板进缓存（可选参数限定某插件目录），冷启动提速用；
galette:twig-pot-references [<plugin>]：从 Twig 模板刷新翻译 POT 引用（翻译模板维护）；
galette:compile-locales [-f|--force] [<plugin>]：把 PO 翻译文件编译成 MO（核心与全部插件默认一起处理，--force 强制重编）。

运维侧主要用第一条；后两条是插件/翻译贡献者的工具。

4.10 代码质量三件套：check-routes / headers:check

面向 Galette 核心与插件开发者的静态检查命令，实测运行：

sudo -u www-data php bin/console galette:check-routes

⚠️  Warnings
   Not named route: [GET] /public/{orig:list|members}[/{option:page|order}/{value:\d+|\w+}]
   Not named route: [GET] /public/{orig:trombinoscope|trombi}

 [OK] 239 checked routes.

239 条核心路由通过命名核查，2 条公开页路由未命名（--names/--urls 可分项检查）——这是核心代码现状的真实快照。galette:headers:check 检查文件版权头（支持 -d 指定目录、--fix 自动修复、--owner/--project-name/--start-year 等参数），不带 -d 时实测报 No header path defined 并打印用法——它是"先选目录再用"的命令，适合插件开发时校验版权头一致性。这两条对运维无直接作用，列出以完整覆盖 19 条命令。

五、生产场景组合用法

5.1 群发队列 cron 化

启用分批发送后的标准运维组合：高级配置页设置间隔与配额（如每封信间隔 3 秒、每小时 500 封、每天 2000 封），cron 每 5 分钟消费一次队列：

*/5 * * * * www-data cd /var/www/galette-1.3.1 && php bin/console galette:mailing:process-queue --force >> /var/log/galette-queue.log 2>&1

要点：--force 必须加（无人值守）；crontab 行以 www-data 身份运行（crontab -u www-data 编辑）；日志重定向便于追踪发送量。发送历史在后台 Mailings 页可查，1.3.0 起队列可从界面、cron 或命令行任一入口恢复（官网公告原文）。

5.2 升级后的体检三连

每次版本升级（覆盖代码目录后）依次执行：

cd /var/www/galette-1.3.1
sudo -u www-data php bin/console galette:checks          # ① 运行环境 15 项
sudo -u www-data php bin/console galette:plugins:list --complete   # ② 插件版本与状态
sudo -u www-data php bin/console galette:check-routes    # ③ 核心路由完整性

①确认 PHP 侧无缺失，②确认插件均已适配（1.2 时代插件会被禁用，官网公告），③确认代码完整性（路由数应与升级前一致，本站基准 239 条）。三者全绿再切流量。

5.3 演示实例的快速搭建与复位

给外部演示搭一个"看完即毁"的实例：命令行安装（方案 B）→ galette:seed-fixtures 注入演示数据 → galette:install 带 --ignore-config 或直接重建数据库即完全复位；演示期间行为覆写用 GALETTE_MODE=DEMO 锁定超管凭据与邮件设置（配置篇 5.2 节）。

六、常见问题（FAQ）

Q1：命令报 "config file does not exists" 或直接进不了命令？

galette:install 以外的多数命令依赖已生成的 config/config.inc.php（读取数据库连接）。确认文件存在且属主为 Web 运行用户；不存在则先完成安装（Web 向导或 4.1 节命令行安装）。

Q2：以 root 跑命令会有问题吗？

会。root 生成的缓存/日志文件属主是 root，Web 用户写不进去会引发权限错误。统一用 sudo -u www-data（或 su www-data -c）执行；历史遗留的 root 属主文件用 chown -R www-data:www-data data/ 修复。

Q3：galette:install 与 Web 安装器装出的结果一致吗？

一致。实测两种方式装出的 config.inc.php 内容逐字符一致、数据库初始化等效，事后都可用 galette:checks 复检。区别仅在交互形态（页面 vs 终端）与错误提示方式。

Q4：seed-fixtures 注入的数据怎么区分？

它注入的是 E2E 测试命名规范的虚构数据（帮助原文），--clean 可完整移除；但生产库不要碰它——清理虚构数据应通过后台筛选删除或直接用 --clean 前确认当前实例无真实数据。

Q5：有 REST API 吗？自动化该走哪条路？

Galette 核心 1.3.1 无 REST API（实测路由核查中无 api 前缀；api-v2 特性在源码注释中标记 Planning 且依赖 acls/oauth2 两个更早期规划项）。当前的自动化路径：命令行（本文命令族）、CSV 导入导出（会员与缴费批量）、以及缴费后置脚本回调（pref_script_auth_token 鉴权，配置篇 5.1 节）。

七、参考链接

官方变更日志（CLI 命令的版本出处，如 1.3.0 新增 galette:superadmin:password）：https://doc.galette.eu/en/develop/changelog.html
官网 1.3.0 发布公告（分批发送队列与 cron/命令行恢复说明）：https://galette.eu/site/post/2026/10/03/galette-1-3-0/
Symfony Console 文档（通用参数语义）：https://symfony.com/doc/current/components/console.html
本专栏选型背景：《Galette 1.3.1 介绍与选型指南》
本专栏安装过程（含命令行安装实测）：《Ubuntu 22.04 安装 Galette 1.3.1 指南》
本专栏配置参数（特性开关与覆写层细节）：《Galette 1.3.1 配置参数详解》