Flarum 2.0 常用 CLI 命令与工具详解

目标：系统整理 Flarum 2.0 命令行工具 php flarum 的全部子命令与参数——信息查看、缓存与资产、数据库迁移、扩展启停、任务调度、头像与公告维护，逐条给出实测回显与典型用法，已在 Ubuntu 22.04.5 LTS + PHP 8.3.36 + MySQL 8.0.46 + Flarum 2.0.2 环境逐条实测通过。

一、环境信息

本篇实测环境（与安装篇、配置篇同一台服务器）：

操作系统：Ubuntu 22.04.5 LTS（x86_64）
PHP：8.3.36（CLI）
数据库：MySQL 8.0.46
Flarum：2.0.2（2026-10-22 实查 GitHub Releases 的最新稳定版）
站点路径：/var/www/flarum
论坛地址：http://192.168.146.128
CLI 执行身份：www-data（站点目录属主，权限语义与 PHP-FPM 一致）

二、工具概览

Flarum 的 CLI 只有一个入口：站点根目录下的 flarum 可执行脚本（无 .php 后缀，shebang 为 #!/usr/bin/env php），本质是 Symfony Console 应用。两种等价执行形态：

php flarum <命令>        # 推荐，与 PHP-FPM 同解释器
./flarum <命令>          # 直接执行（需可执行位）

flarum 脚本本身极薄（实测 634 字节），仅加载 site.php 并启动 Flarum\Console\Server：

cd /var/www/flarum && head -3 flarum && wc -c flarum

实测回显：

#!/usr/bin/env php
<?php

634 flarum

命令全景（php flarum list，实测回显）：

Flarum 2.0.2

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display help for the given command. When no command is given display help for the list command
      --silent          Do not output any message
  -q, --quiet           Only errors are displayed. All other output is suppressed
  -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:
  completion                 Dump the shell completion script
  help                       Display help for a command
  info                       Gather information about Flarum's core and installed extensions
  list                       List commands
  migrate                    Run outstanding migrations
  tinker                     Interact with your Flarum installation through an interactive PHP shell (REPL)
 announcements
  announcements:refresh      Fetch and cache the latest announcements from discuss.flarum.org.
 assets
  assets:publish             Publish core and extension assets.
 avatars
  avatars:backfill-variants  Detect and record which HiDPI variants (@2x, @3x) exist for each locally-stored avatar.
  avatars:convert-to-webp    Convert existing local user avatars from PNG/JPEG/BMP to WebP format
 cache
  cache:clear                Remove all temporary and generated files
 extension
  extension:bisect           Find which extensions is causing an issue. This command will progressively enable and disable extensions to find the one causing the issue. This command will put the forum in maintenance mode.
  extension:enable           [extension:disable] Enable or disable an extension.
 extensions
  extensions:sync-abandoned  Sync the list of abandoned extensions from flarum/abandoned-extensions.
 migrate
  migrate:reset              Run all migrations down for an extension
 schedule
  schedule:list              List all scheduled tasks
  schedule:run               Run the scheduled commands

速查表（按用途索引，详解见第四章）：

用途	命令	风险等级
查看版本/扩展清单	`info`	只读
清缓存/重建资产	`cache:clear` / `assets:publish`	安全
升级后跑迁移	`migrate` / `migrate:reset`	迁移方向操作
扩展启停/排障	`extension:enable` / `extension:disable` / `extension:bisect`	影响线上功能
停用扩展同步	`extensions:sync-abandoned`	只读+通知
计划任务	`schedule:list` / `schedule:run`	安全
头像维护	`avatars:backfill-variants` / `avatars:convert-to-webp`	数据转换
公告刷新	`announcements:refresh`	安全
交互调试	`tinker`	取决于执行代码

三、前置条件

已有一套可用的 Flarum 2.0 站点（安装见站内《Ubuntu 22.04 安装 Flarum 指南》），且满足以下两点：

以站点属主身份执行。CLI 与 PHP-FPM 同属 www-data，混用 root 执行会在 storage/ 留下 root 属主文件，后续缓存清理报权限错（实测排障见 5.2 节）。推荐两种执行形态：

# 形态一：切换到 www-data 执行（服务器管理员推荐）
cd /var/www/flarum
su -s /bin/bash www-data -c 'php flarum info'

# 形态二：属主本身就是 www-data 时直接执行
cd /var/www/flarum && php flarum info

实测回显（形态一，验证版本）：

Flarum core: 2.0.2
PHP version: CLI: 8.3.36, Web: 8.3.36
MySQL version: 8.0.46 (below the recommended MySQL 8.4.0)

在站点根目录执行。flarum 脚本通过相对路径加载 site.php，换目录执行会报 Could not open input file: flarum。验证：

cd / && php flarum list 2>&1 | head -1

实测回显：

Could not open input file: flarum

四、各命令详解

4.1 info：查看站点信息

最常用的体检命令，输出核心版本、PHP/MySQL 版本、扩展清单与运行配置：

cd /var/www/flarum && php flarum info

实测回显（完整）：

Flarum core: 2.0.2
PHP version: CLI: 8.3.36, Web: 8.3.36
MySQL version: 8.0.46 (below the recommended MySQL 8.4.0)
Loaded extensions: Core, date, libxml, openssl, pcre, zlib, filter, hash, json, pcntl, random, Reflection, SPL, session, standard, sodium, mysqlnd, PDO, xml, calendar, ctype, curl, dom, mbstring, FFI, fileinfo, ftp, gd, gettext, iconv, intl, exif, mysqli, pdo_mysql, Phar, posix, readline, shmop, SimpleXML, sockets, sysvmsg, sysvsem, sysvshm, tokenizer, xmlreader, xmlwriter, xsl, zip, Zend OPcache
+--------------------------------+---------+--------+-------+
| Flarum Extensions              |         |        |       |
+--------------------------------+---------+--------+-------+
| ID                             | Version | Commit | Notes |
+--------------------------------+---------+--------+-------+
| flarum-flags                   | v2.0.1  |        |       |
| flarum-suspend                 | v2.0.2  |        |       |
| flarum-approval                | v2.0.1  |        |       |
| flarum-tags                    | v2.0.2  |        |       |
| fof-user-directory             | 2.0.1   |        |       |
| flarum-subscriptions           | v2.0.1  |        |       |
| flarum-sticky                  | v2.0.2  |        |       |
| flarum-statistics              | v2.0.1  |        |       |
| flarum-mentions                | v2.0.2  |        |       |
| flarum-markdown                | v2.0.1  |        |       |
| flarum-lock                    | v2.0.1  |        |       |
| flarum-likes                   | v2.0.2  |        |       |
| flarum-lang-english            | v2.0.0  |        |       |
| flarum-lang-chinese-simplified | 2.0.1   |        |       |
| flarum-extension-manager       | v2.0.1  |        |       |
| flarum-emoji                   | v2.0.1  |        |       |
| flarum-bbcode                  | v2.0.1  |        |       |
+--------------------------------+---------+--------+-------+
Base URL: http://192.168.146.128
Installation path: /var/www/flarum
Queue driver: sync
Session driver: file
Scheduler status: Never run
Mail driver: mail
Debug mode: off

要点解读：Scheduler status: Never run 表示计划任务调度器从未被 cron 触发（见 4.8 节配置方法）；扩展表中的 ID 就是 extension:enable/disable 的参数值。该命令无子参数。

4.2 cache:clear：清缓存与重建资产

清空 storage/ 下的编译产物并重建前端资产。扩展冲突、样式异常、升级后的第一修复动作：

cd /var/www/flarum && php flarum cache:clear

实测回显（完整，含资产重建表）：

Cleared
  cache store
  formatter (1)
  locale (4)
  views (6)
+-----------------------------+--------------------+--------------------+-------+-------+
| Rebuilt assets              |                    |                    |       |       |
+-----------------------------+--------------------+--------------------+-------+-------+
| Frontend                    | Bundle             | Revision           | Size  | Time  |
+-----------------------------+--------------------+--------------------+-------+-------+
| admin                       | admin.js           | new → 7a1e7082     | 586KB | 345ms |
| admin                       | admin.css          | new → 5775e0a6     | 230KB |       |
| admin · en (English)        | admin-en.js        | new → bad77328     | 54KB  | 18ms  |
| admin · en (English)        | admin-en.css       | nothing to compile |       |       |
| admin · zh-Hans (简体中文)  | admin-zh-Hans.js   | new → 740b7b46     | 69KB  | 15ms  |
| admin · zh-Hans (简体中文)  | admin-zh-Hans.css  | nothing to compile |       |       |
| admin                       | chunks             | 4 changed          |       | 19ms  |
| forum                       | forum.js           | 61c90509 unchanged |       | 312ms |
| forum                       | forum.css          | 77a47008 unchanged |       |       |
| forum · en (English)        | forum-en.js        | 87ce313b unchanged |       | 4ms   |
| forum · en (English)        | forum-en.css       | nothing to compile |       |       |
| forum · zh-Hans (简体中文)  | forum-zh-Hans.js   | ab031127 unchanged |       | 3ms   |
| forum · zh-Hans (简体中文)  | forum-zh-Hans.css  | nothing to compile |       |       |
| forum                       | chunks             | 0 changed          |       | 25ms  |
| common                      | common.js          | nothing to compile |       | 3ms   |
| common                      | common.css         | nothing to compile |       |       |
| common · en (English)       | common-en.js       | nothing to compile |       | 3ms   |
| common · en (English)       | common-en.css      | nothing to compile |       |       |
| common · zh-Hans (简体中文) | common-zh-Hans.js  | nothing to compile |       | 3ms   |
| common · zh-Hans (简体中文) | common-zh-Hans.css | nothing to compile |       |       |
| common                      | chunks             | 0 changed          |       | 39ms  |
+-----------------------------+--------------------+--------------------+-------+-------+

参数 -f, --force：强制重编译所有资产（即使输出未变化），默认只重建有变化的。表格解读：new → <8位指纹> 表示该 bundle 被重新编译并换了 revision；unchanged 表示指纹未变直接复用。

4.3 assets:publish：发布前端资产

把核心与各扩展的前端资产（JS/CSS）发布到 storage/，比 cache:clear 更「纯发布」——不清缓存只重发布：

cd /var/www/flarum && php flarum assets:publish

实测回显：

Publishing core assets...
Publishing extension assets...
Publishing for extension: flarum-lang-chinese-simplified
Publishing for extension: flarum-extension-manager

适用场景：手动删除过 storage/ 内资产文件后恢复；正常运维用 cache:clear 即可（其内部会触发等价逻辑）。

4.4 migrate / migrate:reset：数据库迁移

migrate 执行所有未跑的迁移（升级版本或新装扩展后必跑）：

cd /var/www/flarum && php flarum migrate

实测回显（已全部迁移完毕的稳态输出）：

Migrating Flarum...
Nothing to migrate.
Migrating extension: flarum-flags
Nothing to migrate.
Migrating extension: flarum-suspend
Nothing to migrate.
Migrating extension: flarum-approval
Nothing to migrate.
Migrating extension: flarum-tags
Nothing to migrate.
Migrating extension: fof-user-directory
Nothing to migrate.
Migrating extension: flarum-subscriptions
Nothing to migrate.
Migrating extension: flarum-sticky
Nothing to migrate.
Migrating extension: flarum-mentions
Nothing to migrate.
Migrating extension: flarum-markdown
Nothing to migrate.
Migrating extension: flarum-lock
Nothing to migrate.
Migrating extension: flarum-likes
Nothing to migrate.
Migrating extension: flarum-extension-manager
Nothing to migrate.
Migrating extension: flarum-emoji
Nothing to migrate.
DONE.

参数 --isolated[=ISOLATED]（默认 false）：防止多实例并发跑同一迁移，自动化升级脚本建议带上。有新迁移时的输出形态为逐条 Done in <秒>s（本站处于稳态故显示 Nothing to migrate）。

migrate:reset 回滚指定扩展的全部迁移（仅用于卸载扩展清表，参数必填）：

cd /var/www/flarum && php flarum help migrate:reset

实测回显：

Description:
  Run all migrations down for an extension

Usage:
  migrate:reset [options]

Options:
      --extension=EXTENSION  The extension to reset migrations for.
  -h, --help                 Display help for the given command. When no command is given display help for the list command
      --silent               Do not output any message
  -q, --quiet                Only errors are displayed. All other output is suppressed
  -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

⚠️ 注意：migrate:reset 会删除该扩展的表与数据，仅按官方卸载流程（先停用扩展再 reset）使用，切勿对核心 flarum/core 执行。

4.5 extension:enable / extension:disable：扩展启停

后台「扩展」页的命令行等价物，参数为扩展 ID（info 表格中的 ID 列）。实测禁用再启用 BBCode 扩展：

cd /var/www/flarum && php flarum extension:disable flarum-bbcode

实测回显：

Disabling 'flarum-bbcode' extension...

php flarum extension:enable flarum-bbcode

实测回显：

Enabling 'flarum-bbcode' extension...

传错 ID 的报错（实测）：

There are no extensions by the ID of 'no-such-ext'.

生效验证：启停操作同步改写 settings 表的 extensions_enabled JSON，并立即影响前台（详见站内《Flarum 2.0 配置参数详解》5.6 节）：

php flarum info | grep -E 'bbcode|markdown'

实测回显（bbcode 已恢复在列）：

| flarum-bbcode                  | v2.0.1  |        |       |
| flarum-markdown                | v2.0.1  |        |       |

4.6 extension:bisect：扩展冲突二分定位

论坛白屏/异常且怀疑某扩展引起时，此命令自动进入维护模式并逐步启停扩展做二分排查，交互式引导你定位肇事扩展。无参数。⚠️ 会在排查期间把论坛置于维护模式，生产上请在低峰期使用。帮助回显：

Description:
  Find which extensions is causing an issue. This command will progressively enable and disable extensions to find the one causing the issue. This command will put the forum in maintenance mode.

Usage:
  extension:bisect

4.7 extensions:sync-abandoned：停用扩展同步

从官方 flarum/abandoned-extensions 清单同步「已废弃」扩展标记，--notify 给管理员发邮件提醒：

cd /var/www/flarum && php flarum help extensions:sync-abandoned

实测回显：

Description:
  Sync the list of abandoned extensions from flarum/abandoned-extensions.

Usage:
  extensions:sync-abandoned [options]

Options:
      --notify          Email admins if newly abandoned extensions are found
  -h, --help            Display help for the given command. When no command is given display help for the list command
      --silent          Do not output any message
  -q, --quiet          Only errors are displayed. All other output is suppressed
  -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

4.8 schedule:list / schedule:run：计划任务

Flarum 2.0 内置调度器（Symfony Scheduler），schedule:list 列出全部已注册任务与下次执行时间（实测回显）：


  6 5 * * 6  php flarum extensions:sync-abandoned --notify  Next Due: 2 days from now
  6 5 * * 6  php flarum announcements:refresh ...... Next Due: 2 days from now

即每周六 05:06 执行「废弃扩展同步（带邮件通知）」与「官方公告刷新」两项任务。

schedule:run 是调度触发器——由 cron 每分钟调一次，它判断到期任务并执行。标准配置方法（用 www-data 的 crontab）：

crontab -u www-data -e
# 加入一行：
# * * * * * cd /var/www/flarum && php flarum schedule:run >> /dev/null 2>&1

参数：--whisper（无到期任务时不输出提示，适合 cron 静默）、--timezone（schedule:list 显示时区）、--next（按下次到期排序）、--json（JSON 输出，便于脚本解析）。

配置 cron 后的验证：php flarum info 的 Scheduler status 不再是 Never run（首次触发需要等到下一个整分钟）。

4.9 avatars:backfill-variants / avatars:convert-to-webp：头像维护

两个头像批量维护命令（大用户量站点用，本站用户少故输出极短）。参数实测：

cd /var/www/flarum && php flarum help avatars:backfill-variants

实测回显：

Description:
  Detect and record which HiDPI variants (@2x, @3x) exist for each locally-stored avatar.

Usage:
  avatars:backfill-variants [options]

Options:
      --chunk=CHUNK     Number of users to process per database chunk [default: "100"]
      --force           Re-check users even if both flags are already set
  -h, --help            Display help for the given command. When no command is given display help for the list command
      --silent          Do not output any message
  -q, --quiet         Only errors are displayed. All other output is suppressed
  -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

--chunk 默认 100（每批处理用户数，大表调大提速）；--force 强制重查已标记用户。avatars:convert-to-webp 无参数，把存量 PNG/JPEG/BMP 头像统一转 WebP 省体积（转换不可逆，转换前建议备份 storage/）。

4.10 announcements:refresh：官方公告刷新

从 discuss.flarum.org 拉取官方公告写入本地缓存（管理后台首页展示），无参数：

Description:
  Fetch and cache the latest announcements from discuss.flarum.org.

Usage:
  announcements:refresh

离线内网环境此命令会因无法访问官方论坛而失败，属预期行为。

4.11 tinker：交互式调试 REPL

进入交互式 PHP shell，可直接调用 Flarum 服务容器内已初始化的对象（比如查 settings、调服务）。实测（非交互输入表达式）：

cd /var/www/flarum && echo 'print_r("flarum-tinker-ok"); exit;' | php flarum tinker

实测回显：

flarum-tinker-ok

表达式写错的报错形态（实测）：

 Error  Undefined constant "version".
=>  null

⚠️ 注意：tinker 里能执行任意 PHP 代码且改动即时落库，仅限维护人员在服务器本地使用；交互模式以 exit 退出。

五、注意事项

5.1 命令速查与组合场景

场景	命令序列
升级版本后	`php flarum migrate` → `php flarum cache:clear`
装完新扩展	`php flarum extension:enable <ID>`（enable 内部自动跑迁移）
论坛白屏/样式错乱	`php flarum cache:clear`；仍异常则 `assets:publish`
卸载扩展	`php flarum extension:disable <ID>` → `php flarum migrate:reset --extension=<ID>`
排查扩展冲突	`php flarum extension:bisect`（会进维护模式）

5.2 执行身份与权限

禁止用 root 长期跑 CLI：root 跑过的命令会在 storage/ 写入 root 属主文件，之后 www-data 清缓存报权限错。实测报错原文：

Could not clear contents of `storage/cache`. Please adjust file permissions and try again. This can frequently be fixed by clearing cache via the `Tools` dropdown on the Administration Dashboard page.

修复方法（实测有效）：

chown -R www-data:www-data /var/www/flarum/storage
cd /var/www/flarum && su -s /bin/bash www-data -c 'php flarum cache:clear'

修复后再跑即恢复 4.2 节的正常输出（Cleared ... + Rebuilt assets 表格）。

5.3 help 与 --version 的通用用法

任何子命令加 help 前缀（php flarum help <命令>）或 -h 选项可看完整参数说明；php flarum --version 输出版本号（实测输出 Flarum 2.0.2）。全局选项 -n（非交互，脚本化必带）、-q（静默，cron 里用）、-v/-vv/-vvv（调试排障逐级加详细度）对所有子命令通用。

六、常见问题（FAQ）

Q1：php flarum info 报连接数据库失败？ CLI 读的也是 config.php，先核对其中 database 段与实际服务一致；再 mysql -u<用户> -p<口令> -e 'SELECT 1;' 验证账号；最后确认 host 值——localhost 走 socket 而 127.0.0.1 走 TCP，两者在 MySQL 只允许其一的托管环境会一个通一个不通。

Q2：cache:clear 报 Could not clear contents？ storage/ 内混入非 www-data 属主文件所致，按 5.2 节两行命令修复；同时排查是否曾用 root 跑过 CLI，纠正执行习惯。

Q3：schedule:run 手动执行没反应？ 正常——它只执行「当前到期」的任务，本站两项任务都是每周六 05:06，平时手动跑无任务到期则空转。用 php flarum schedule:list 看每个任务的 Next Due；想立即观察执行效果可临时等 --timezone 输出的到期窗口，或在测试环境把任务时间调到当下。

Q4：extension:enable 后论坛前台没变化？ 先 php flarum info 确认扩展真的在列；再强刷浏览器；仍有问题跑 php flarum cache:clear 重建前端资产（新扩展的 JS/CSS 需要进 bundle）。依赖缺失会让 enable 直接报错，按报错先启依赖扩展。

Q5：migrate 中途失败怎么回滚？ 迁移是逐条事务执行，失败时已跑的条目保留。先看报错定位是核心还是某扩展的迁移；扩展问题可 migrate:reset --extension=<ID> 后修复再重跑；核心迁移失败建议恢复数据库备份后重试，勿盲目 reset 核心。

七、参考链接

Flarum 官方文档 - Console 命令：https://docs.flarum.org/extend/console
Flarum 官方文档 - 扩展管理：https://docs.flarum.org/extend/start
Flarum GitHub 仓库：https://github.com/flarum/framework
站内配套阅读：《Ubuntu 22.04 安装 Flarum 指南》、《Flarum 2.0 配置参数详解》