phpBB 常用 CLI 命令详解
面向真实服务器的 phpBB 3.3.19 命令行工具 phpbbcli.php 实测手册：config、db、cron、extension、fixup、reparser、thumbnail、update、user 九组 26 个子命令逐条给出命令输入与真实回显，并沉淀 user:add 非交互环境报错、config:set-atomic 参数顺序、extension:purge 假成功等真实排障实录。
phpBB 常用 CLI 命令详解
phpBB 的图形化管理后台（ACP）覆盖了绝大多数日常运维动作，但批量化运维、自动化巡检、无浏览器的紧急修复，都要走它自带的命令行工具 bin/phpbbcli.php。本文在真实 Ubuntu 22.04 服务器视角下，对 phpBB 3.3.19 的全部 26 个专有子命令逐条实测：每条命令给出真实输入与真实回显，并把实测中踩到的坑（非交互环境执行 user:add 报错、config:set-atomic 参数顺序、extension:purge 假成功等）沉淀为排障实录。
一、环境信息
本文全部命令与回显均在下表所示环境中实测取得（版本查询日期：2026-10-22）：
| 项目 | 实测值 |
|---|---|
| 操作系统 | Ubuntu 22.04.5 LTS |
| PHP（CLI） | PHP 8.1.2-1ubuntu2.28（cli, NTS） |
| 数据库 | MariaDB 10.6.23（phpBB 使用 mysqli 驱动连接） |
| phpBB | 3.3.19（config:get version 实测值） |
| 论坛规模 | 83 个注册用户、2 篇帖子（SQL 实测） |
| phpBB 安装目录 | /var/www/phpbb |
| CLI 入口 | /var/www/phpbb/bin/phpbbcli.php |
| 运行用户 | www-data（与 Web 服务同用户，保证缓存文件读写权限一致） |
phpBB 的安装与 Web 侧配置请先阅读本专栏《Ubuntu 22.04 安装 phpBB 指南》与《phpBB 配置参数详解》，本文在其基础上展开。
二、工具概览
phpbbcli.php 是 phpBB 官方自带的控制台入口，基于 Symfony Console 组件构建，位于安装目录的 bin/ 下：
cd /var/www/phpbb
php bin/phpbbcli.php <子命令> [选项] [参数]
按 list 实测，phpBB 3.3.19 共提供 26 个专有子命令，分 9 组，外加 Symfony 自带的 help、list 两个通用命令：
| 分组 | 子命令 | 用途 |
|---|---|---|
| cache | cache:purge | 清空全部缓存 |
| config | config:get / config:set / config:increment / config:delete / config:set-atomic | 配置项读取与修改 |
| cron | cron:list / cron:run | 计划任务查看与手动执行 |
| db | db:list / db:migrate / db:revert | 数据库迁移查看、升级、回滚 |
| dev | dev:migration-tips | 找出不再被依赖的迁移（开发调试用） |
| extension | extension:show / extension:enable / extension:disable / extension:purge | 扩展状态查看与启停、清除 |
| fixup | fixup:fix-left-right-ids / fixup:update-hashes | 树结构修复、旧密码哈希升级 |
| reparser | reparser:list / reparser:reparse | 文本重解析 |
| thumbnail | thumbnail:generate / thumbnail:recreate / thumbnail:delete | 附件缩略图生成、重建、删除 |
| update | update:check | 检查论坛是否为最新版 |
| user | user:add / user:activate / user:delete / user:delete_id / user:reclean | 用户增删、激活、重清洗 |
与 ACP 后台相比，CLI 的价值在于：不依赖浏览器与会话、可写进 cron 与自动化脚本、故障时 ACP 不可用也能修复数据。
三、前置条件
- 能登录服务器并以安装 phpBB 的系统用户执行命令。phpBB 缓存目录（
cache/、store/等）属主是 Web 服务用户，建议始终以同一用户运行 CLI，避免缓存文件属主混乱：
su -s /bin/bash www-data -c 'cd /var/www/phpbb && php bin/phpbbcli.php list'
- PHP CLI 与 MariaDB 服务正常（
php -v、mariadb --version）。 - 确认版本与入口：
php bin/phpbbcli.php --version
实测输出：
phpBB Console 3.3.19
- 交互模式说明：Symfony Console 默认在「stdin 是终端」时启用交互问答；在 cron、CI、
su -c等非终端场景会自动降级为非交互。个别带问答逻辑的命令（如user:add）在非交互环境有特殊行为，详见第 4.12 节与 FAQ。
四、命令详解
4.1 命令列表与帮助
查看全部命令：
php bin/phpbbcli.php list
实测输出（完整照抄）：
phpBB Console 3.3.19
Usage:
command [options] [arguments]
Options:
-h, --help Display this help message
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi Force ANSI output
--no-ansi Disable ANSI output
-n, --no-interaction Do not ask any interactive question
--safe-mode Run in Safe Mode (without extensions).
-e, --env=ENV The Environment name.
-s, --shell Launch the shell.
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
Available commands:
help Displays help for a command
list Lists commands
cache
cache:purge Purge the cache
config
config:delete Deletes a configuration option
config:get Gets a configuration option’s value
config:increment Increments a configuration option’s integer value
config:set Sets a configuration option’s value
config:set-atomic Sets a configuration option’s value only if the old matches the current value
cron
cron:list Prints a list of ready and unready cron jobs.
cron:run Runs all ready cron tasks.
db
db:list List all installed and available migrations.
db:migrate Updates the database by applying migrations.
db:revert Revert a migration.
dev
dev:migration-tips Finds migrations that are not depended upon.
extension
extension:disable Disables the specified extension.
extension:enable Enables the specified extension.
extension:purge Purges the specified extension.
extension:show Lists all extensions in the database and on the filesystem.
fixup
fixup:fix-left-right-ids Repairs the tree structure of the forums and modules.
fixup:update-hashes Updates outdated password hashes to be hashed with bcrypt.
reparser
reparser:list Lists the types of text that can be reparsed.
reparser:reparse Reparses stored text with the current text_formatter services.
thumbnail
thumbnail:delete Delete all existing thumbnails.
thumbnail:generate Generate all missing thumbnails.
thumbnail:recreate Recreate all thumbnails.
update
update:check Check if the board is up to date.
user
user:activate Activate (or deactivate) a user account.
user:add Add a new user.
user:delete Delete a user account.
user:delete_id Delete user accounts by ID.
user:reclean Re-clean usernames.
全局选项对每个子命令都生效，常用三个：-v/-vv/-vvv 提升输出详细度（部分命令默认静默，加 -vv 才有实质输出）、-n 禁止交互问答、--safe-mode 在不加载扩展和缓存的环境下运行（扩展出问题时排查用）。
查看单个命令的用法：
php bin/phpbbcli.php help cache:purge
实测输出：
Usage:
cache:purge
Help:
Purges all cache files.
4.2 缓存命令 cache:purge
清空论坛全部缓存（数据缓存、模板缓存、s9e 渲染器缓存等）。直接改数据库 phpbb_config 表或手工替换模板文件后，必须执行本命令，改动才会反映到前台：
php bin/phpbbcli.php cache:purge
实测输出：
[OK] Cache successfully purged.
该命令无参数、无交互，返回码 0。phpBB 配置体系（config.php + phpbb_config 表）与缓存生效关系在《phpBB 配置参数详解》中有完整实验：SQL 直改后前台仍显示旧值，cache:purge 后新值立即生效。
4.3 配置命令 config:get / set / increment / delete / set-atomic
五个子命令直接操作运行时配置（数据存于 phpbb_config 表）。
读取 config:get：
php bin/phpbbcli.php config:get version
实测输出：
3.3.19
加 --no-newline 则输出值后不换行（便于脚本取值）：
php bin/phpbbcli.php config:get version --no-newline
实测输出（无换行）：
3.3.19
写入 config:set（键不存在会自动创建）：
php bin/phpbbcli.php config:set cli_test_key 5
实测输出：
[OK] Successfully set config cli_test_key
自增 config:increment（整型值 +N）：
php bin/phpbbcli.php config:increment cli_test_key 3
实测输出：
[OK] Successfully incremented config cli_test_key
再次读取，实测从 5 变为 8：
8
删除 config:delete：
php bin/phpbbcli.php config:delete cli_test_key
实测输出：
[OK] Successfully deleted config cli_test_key.
删除后再读取（注意：报错但退出码仍是 0，见第五节注意事项）：
php bin/phpbbcli.php config:get cli_test_key; echo "EXIT=$?"
实测输出：
[ERROR] Config cli_test_key does not exist
EXIT=0
条件写入 config:set-atomic：仅当「当前值与给定旧值一致」时才写入，用于并发场景下的防覆盖。注意参数顺序是 <key> <旧值> <新值>，旧值在前：
php bin/phpbbcli.php config:set-atomic board_name "phpBB CLI Test Board" "phpBB CLI Board v2"
实测（旧值与当前值一致，写入成功）：
[OK] Successfully set config board_name
读取确认：
phpBB CLI Board v2
旧值不匹配时（实测当前值已是 phpBB CLI Board v2，仍传旧值 phpBB CLI Test Board）：
php bin/phpbbcli.php config:set-atomic board_name "phpBB CLI Test Board" "phpBB v3"; echo "EXIT=$?"
实测输出：
[ERROR] Could not set config board_name
EXIT=1
help config:set-atomic 实测的用法说明，明确标注了 old 在前：
Usage:
config:set-atomic [options] [--] <key> <old> <new>
Arguments:
key The configuration option’s name
old Current configuration value, use 0 and 1 to specify boolean values
new New configuration value, use 0 and 1 to specify boolean values
配置项含义与修改后的生效路径，见《phpBB 配置参数详解》。
4.4 计划任务命令 cron:list / cron:run
cron:list 把系统任务分为「就绪（到期待跑）」与「未就绪」两组展示：
php bin/phpbbcli.php cron:list
实测输出（21 个任务：3 个就绪 + 18 个未就绪）：
Ready tasks:
============
* cron.task.core.tidy_guest_sessions
* cron.task.text_reparser.pm_text
* cron.task.text_reparser.poll_option
Not ready tasks:
================
* cron.task.core.prune_all_forums
* cron.task.core.prune_forum
* cron.task.core.prune_shadow_topics
* cron.task.core.prune_notifications
* cron.task.core.version_check
* cron.task.core.queue
* cron.task.core.tidy_cache
* cron.task.core.tidy_database
* cron.task.core.tidy_plupload
* cron.task.core.tidy_search
* cron.task.core.tidy_sessions
* cron.task.core.purge_oauth_states
* cron.task.core.tidy_warnings
* cron.task.text_reparser.poll_title
* cron.task.text_reparser.post_text
* cron.task.text_reparser.user_signature
* cron.task.core.update_hashes
* cron.task.viglink
cron:run 手动执行所有就绪任务。论坛流量低、依赖服务器 cron 触发 cron/task 入口的场景下，可用它手动兜底：
php bin/phpbbcli.php cron:run; echo "EXIT=$?"
实测输出（成功时没有任何输出，退出码 0）：
EXIT=0
4.5 数据库迁移命令 db:list / db:migrate / db:revert
db:list 列出已安装与可用的迁移文件。实测共 340 行输出，开头如下：
php bin/phpbbcli.php db:list
实测输出（前 20 行）：
Installed migrations
--------------------
* \phpbb\viglink\migrations\viglink_ask_admin_wait
* \phpbb\viglink\migrations\viglink_cron
* \phpbb\viglink\migrations\viglink_data_v2
* \phpbb\viglink\migrations\viglink_ask_admin
* \phpbb\viglink\migrations\viglink_data
* \phpbb\db\migration\data\v310\topic_sort_username
* \phpbb\db\migration\data\v310\forgot_password
* \phpbb\db\migration\data\v310\style_update_p1
* \phpbb\db\migration\data\v310\extensions_version_check_force_unstable
* \phpbb\db\migration\data\v310\profilefield_location
* \phpbb\db\migration\data\v310\acp_prune_users_module
* \phpbb\db\migration\data\v310\allow_cdn
* \phpbb\db\migration\data\v310\notifications
* \phpbb\db\migration\data\v310\jquery_update2
* \phpbb\db\migration\data\v310\notifications_schema_fix
* \phpbb\db\migration\data\v310\reset_missing_captcha_plugin
db:migrate 应用所有未安装的迁移，把数据库结构升级到代码对应版本。升级 phpBB 版本、安装/更新扩展后都需要跑：
php bin/phpbbcli.php db:migrate; echo "EXIT=$?"
实测输出：
[OK] The database update was successful.
EXIT=0
db:revert 回滚指定迁移。<name> 必须写成带前导反斜杠的完整命名空间（与 db:list 显示一致），实测使用「正斜杠缩写」或双反斜杠转义都会报 is not a valid migration（详见 FAQ）：
php bin/phpbbcli.php db:revert '\phpbb\db\migration\data\v33x\v3319'; echo "EXIT=$?"
实测输出：
Reverted Data: \phpbb\db\migration\data\v33x\v3319; Time: 0.00 seconds
Reverted Schema: \phpbb\db\migration\data\v33x\v3319; Time: 0.00 seconds
[OK] The database update was successful.
EXIT=0
回滚是危险动作，务必先备份再操作，回滚后按需重新执行 db:migrate 复原：
php bin/phpbbcli.php db:migrate
实测输出：
[OK] The database update was successful.
4.6 开发辅助命令 dev:migration-tips
找出「不再被任何其他迁移依赖」的迁移文件，扩展开发者用于判断哪些历史迁移可以考虑合并精简：
php bin/phpbbcli.php dev:migration-tips; echo "EXIT=$?"
实测输出（它直接打印出迁移类的 depends_on() 片段）：
[
'\phpbb\db\migration\data\v33x\v3319',
];
EXIT=0
日常运维用不到它，仅在编写扩展迁移时参考。
4.7 扩展管理命令 extension:show / enable / disable / purge
四个命令的 <extension-name> 都必须写**「厂商/扩展名」全称**（如 phpbb/viglink），只写 viglink 会被判定为不存在的扩展（实测见 FAQ）。
extension:show 列出已启用、已停用、仅安装在文件系统三组扩展：
php bin/phpbbcli.php extension:show
实测输出（phpBB 3.3.19 自带官方 viglink 扩展并处于启用态）：
Enabled
-------
* phpbb/viglink
Disabled
--------
Available
---------
extension:enable 启用扩展（自动执行其数据库迁移、写入权限等初始化数据）：
php bin/phpbbcli.php extension:enable phpbb/viglink; echo "EXIT=$?"
实测输出：
[OK] Successfully enabled extension phpbb/viglink
EXIT=0
对已启用扩展重复执行会报错：
[ERROR] Extension phpbb/viglink is already enabled
EXIT=1
extension:disable 停用扩展（保留数据）：
php bin/phpbbcli.php extension:disable phpbb/viglink; echo "EXIT=$?"
实测输出：
[OK] Successfully disabled extension phpbb/viglink
EXIT=0
extension:purge 清除扩展：执行其卸载清理逻辑，删除其迁移记录与专属数据，但保留文件系统中的代码（show 中移到 Available 组）。完整「停用 → 清除 → 重新启用」实测：
php bin/phpbbcli.php extension:purge phpbb/viglink; echo "EXIT=$?"
实测输出：
[OK] Successfully purged extension phpbb/viglink
EXIT=0
清除后验证：extension:show 中 phpbb/viglink 从 Enabled 移到 Available；SQL 查库确认其 5 条迁移记录已清空（phpbb_migrations 中 LIKE '%viglink%' 为 0 行）。重新启用即重装数据：
php bin/phpbbcli.php extension:enable phpbb/viglink
实测输出：
[OK] Successfully enabled extension phpbb/viglink
注意：purge 只清扩展自身数据，phpBB 核心拥有的相关配置键（如 allow_viglink_phpbb）实测仍保留在 phpbb_config 表中。
4.8 修复命令 fixup:fix-left-right-ids / fixup:update-hashes
fixup:fix-left-right-ids 重建版面与 ACP 模块的左右值树结构。版面排序异常、ACP 菜单错乱时的修复手段：
php bin/phpbbcli.php fixup:fix-left-right-ids; echo "EXIT=$?"
实测输出：
[OK] Successfully repaired the tree structure of the forums and modules.
EXIT=0
fixup:update-hashes 把老版本算法存储的密码哈希批量升级为 bcrypt（用户下次登录时自动完成透明转换，此命令用于主动批量处理）：
php bin/phpbbcli.php fixup:update-hashes; echo "EXIT=$?"
实测输出（本论坛无待升级哈希，进度条一闪而过）：
0 [>---------------------------]Successfully updated outdated password hashes to bcrypt.
EXIT=0
4.9 文本重解析命令 reparser:list / reparser:reparse
phpBB 把帖子、私信等富文本解析结果缓存在数据库中；BBCode 扩展规则变化或数据修复后，可对指定类型文本全量重解析。
reparser:list 列出全部可重解析的文本类型（实测 9 项）：
php bin/phpbbcli.php reparser:list
实测输出：
Available reparsers:
--------------------
* contact_admin_info
* forum_description
* forum_rules
* group_description
* pm_text
* poll_option
* poll_title
* post_text
* user_signature
reparser:reparse 执行重解析，带实时进度条：
php bin/phpbbcli.php reparser:reparse post_text; echo "EXIT=$?"
实测输出：
Reparsing post_text (range 1..2)
--------------------------------
0/2 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0%
Reparsing post_text... < 1 sec/< 1 sec 12.0 MiB
2/2 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 100%
Reparsing post_text (range 1..2) < 1 sec/< 1 sec 20.0 MiB
[OK] Reparsing ended with success
EXIT=0
4.10 附件缩略图命令 thumbnail:generate / recreate / delete
三个命令处理附件缩略图：generate 补齐缺失的、recreate 全部重建、delete 全部删除。实测论坛尚无带缩略图的附件，三个命令都给出 WARNING 而非报错：
php bin/phpbbcli.php thumbnail:generate; echo "EXIT=$?"
实测输出：
Generating thumbnails
---------------------
[WARNING] No thumbnails to generate.
EXIT=0
php bin/phpbbcli.php thumbnail:recreate; echo "EXIT=$?"
实测输出：
Deleting thumbnails
-------------------
[WARNING] No thumbnails to delete.
Generating thumbnails
---------------------
[WARNING] No thumbnails to generate.
EXIT=0
php bin/phpbbcli.php thumbnail:delete; echo "EXIT=$?"
实测输出：
Deleting thumbnails
-------------------
[WARNING] No thumbnails to delete.
EXIT=0
4.11 版本检查命令 update:check
检查论坛是否为官方最新稳定版。默认静默——已是最新版时无任何输出、退出码 0：
php bin/phpbbcli.php update:check; echo "EXIT=$?"
实测输出：
EXIT=0
加 -vv 才能看到详细信息：
php bin/phpbbcli.php update:check -vv; echo "EXIT=$?"
实测输出：
phpBB core
==========
! [NOTE] Current version: 3.3.19
[OK] The board is up to date.
EXIT=0
写成巡检脚本时判断退出码即可：非 0 表示有可用更新或检查失败。
4.12 用户管理命令 user:add / activate / delete / delete_id / reclean
user:add 命令行创建用户。help user:add 实测用法：
Usage:
user:add [options]
Options:
-U, --username=USERNAME Username of the new user
-P, --password=PASSWORD Password of the new user
-E, --email=EMAIL E-mail address of the new user
--send-email Send account activation email to the new user (not sent by default)
-h, --help Display this help message
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi Force ANSI output
--no-ansi Disable ANSI output
-n, --no-interaction Do not ask any interactive question
排障实录（重要）：在 cron、su -c 等非终端（stdin 不是 TTY）环境下，即使 -U/-P/-E 三个参数都给全，实测仍然失败：
php bin/phpbbcli.php user:add --username cliuser --password q1w2e3r4 --email cliuser@example.com; echo "EXIT=$?"
实测输出：
PHP Warning: Trying to access array offset on value of type null in /var/www/phpbb/includes/functions_user.php on line 1544
PHP Warning: Trying to access array offset on value of type null in /var/www/phpbb/includes/functions_user.php on line 1544
PHP Warning: Trying to access array offset on value of type null in /var/www/phpbb/includes/functions_user.php on line 1544
PHP Warning: Trying to access array offset on value of type null in /var/www/phpbb/includes/functions_user.php on line 1544
PHP Warning: Trying to access array offset on value of type null in /var/www/phpbb/includes/functions_user.php on line 1544
PHP Warning: Trying to access array offset on value of type null in /var/www/phpbb/includes/functions_user.php on line 1544
PHP Warning: Undefined array key "user_email" in /var/www/phpbb/includes/functions_user.php on line 1937
[ERROR] The username you entered is too short.
The password you entered is too short.
The email address you entered is too short.
EXIT=1
报错信息极具误导性——看起来像用户名太短，实际根因在 Symfony Console 的 configureIO()：stdin 非 TTY 且未设置 SHELL_INTERACTIVE 环境变量时，输入被标记为非交互，命令的 interact() 阶段被整体跳过，负责承接选项值的内部数据结构未初始化，校验阶段全部拿到空值，才产生三条 "too short"。修复方式是显式声明交互环境：
SHELL_INTERACTIVE=1 php bin/phpbbcli.php user:add --username cliuser --password q1w2e3r4 --email cliuser@example.com; echo "EXIT=$?"
实测输出（创建成功；首行 Warning 是该命令在成功路径上也会出现的已知噪音，不影响结果）：
PHP Warning: Undefined array key "user_email" in /var/www/phpbb/includes/functions_user.php on line 1937
[OK] Successfully added user cliuser.
EXIT=0
实测查库：新用户 user_type=0（普通用户）、user_inactive_reason=0，即 CLI 创建的账号默认就是激活状态，无需再去 ACP 手工激活。
user:activate 激活或停用账号。停用（-d / --deactivate）：
php bin/phpbbcli.php user:activate cliuser -d; echo "EXIT=$?"
实测输出：
[OK] User deactivated successfully.
EXIT=0
实测查库该用户 user_inactive_reason 由 0 变为 3。重新激活：
php bin/phpbbcli.php user:activate cliuser; echo "EXIT=$?"
实测输出：
[OK] User activated successfully.
EXIT=0
对不存在用户执行：
php bin/phpbbcli.php user:activate nosuchuser; echo "EXIT=$?"
实测输出：
[ERROR] The requested user does not exist.
EXIT=1
user:delete 按用户名删除账号（加 --delete-posts 连同其帖子一并删除，默认保留帖子）：
php bin/phpbbcli.php user:delete cliuser; echo "EXIT=$?"
实测输出：
[OK] User deleted successfully.
EXIT=0
缺参数时（实测退出码 1）：
Not enough arguments (missing: "username").
user:delete [--delete-posts] [-h|--help] [-q|--quiet] [-v|vv|vvv|--verbose] [-V|--version] [--ansi] [--no-ansi] [-n|--no-interaction] [--safe-mode] [-e|--env ENV] [--] <command> <username>
user:delete_id 按用户 ID 批量删除，可一次传多个 ID。实测（重建测试用户 cliuser2 得到 ID 85 后执行）：
php bin/phpbbcli.php user:delete_id 85; echo "EXIT=$?"
实测输出：
0/1 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0%
< 1 sec/< 1 sec 12.0 MiB
1/1 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 100%
< 1 sec/< 1 sec 14.0 MiB
[OK] Successfully deleted user IDs.
EXIT=0
user:reclean 批量重清洗全站用户名（去除非法字符、统一格式），不接用户名参数。实测：
php bin/phpbbcli.php user:reclean; echo "EXIT=$?"
实测输出（进度条实测自 0/83 逐帧推进至 83/83，中间帧省略）：
Re-cleaning usernames
---------------------
0/83 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0%
< 1 sec/< 1 sec 12.0 MiB
……中间进度帧省略（实测 8/83 → 80/83 逐帧推进）……
83/83 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ 100%
< 1 sec/< 1 sec 14.0 MiB
[OK] Re-cleaning complete. No usernames needed to be cleaned.
EXIT=0
五、注意事项
- 统一运行身份：始终用 Web 服务同一用户（本文为
www-data）执行 CLI，避免cache/、store/目录下缓存文件属主混杂导致 Web 侧写缓存失败。 - 退出码不统一：多数命令失败时退出码为 1，但
config:get对不存在的键虽然打印[ERROR]，实测退出码仍是 0。脚本判断不能只依赖退出码，必要时解析输出文本。 - 部分命令默认静默：
cron:run、update:check成功时零输出，config:get成功时直接打印值；自动化里要先想清楚「无输出 = 成功」还是「加 -vv 才有输出」。 - 缓存一致性：
config:set*会同步刷新配置缓存；但绕过 CLI 直接改数据库phpbb_config表后，必须cache:purge，否则 CLI 的config:get与前台都可能读到旧值。 - 危险命令先备份：
db:revert、fixup:*、thumbnail:delete、user:delete*都直接改库或删文件，执行前先备份数据库与files/目录；db:revert执行过程中会自动清空缓存（源码内置cache->purge()）。 - 扩展名必须写全称：
extension:*系列一律使用厂商/扩展名（如phpbb/viglink），且 purge 前需先 disable（对启用中的扩展 purge 无效）。 - 非交互环境：cron/CI 中执行带交互逻辑的命令（当前只有
user:add）必须带SHELL_INTERACTIVE=1，否则报出与真实原因无关的错误（见 FAQ 第一条）。
六、常见问题
Q1：user:add 参数给全了，为什么还报 "The username you entered is too short."？
这是 phpBB 3.3.19 CLI 最典型的误导性报错。真实原因不是用户名长度，而是非 TTY 环境下 Symfony Console 自动关闭了交互，命令内部承接选项值的数据结构未初始化，三项校验全部按空值处理。三种解决办法（实测均有效）：① 命令前加 SHELL_INTERACTIVE=1；② 在真实终端（TTY）中执行；③ 改用 Web 注册流程。顺带一提：即使成功路径，实测也会打出一条 Undefined array key "user_email" 的 PHP Warning，属已知噪音，不影响创建结果。
Q2：config:set-atomic 总是报 "Could not set"，值明明是对的？
先检查参数顺序：该命令是 config:set-atomic <key> <旧值> <新值>，旧值在前、新值在后（help 输出可确认）。本文实测中即因把新值写在第 2 位，导致「成功」与「失败」两条路径反复颠倒。可用 config:get 先取当前值，再把它作为第 2 参数传入。
Q3：config:get 报 "Config xxx does not exist"，但数据库里这个键明明存在？
CLI 的运行时配置优先从缓存加载，缓存条目不完整时就会出现「数据库有、CLI 读不到」。实测过一个衍生怪象：这种状态下 config:set-atomic 可能报 [OK] 但数据库并未更新（源码在该分支会走 INSERT 补偿路径并返回成功）。执行一次 cache:purge 重建缓存后即恢复正常。判断数据真实状态时，以数据库直查为准。
Q4：extension:purge 显示 "Successfully purged"，但扩展数据一点没删？
大概率是扩展名写成了裸名（如 viglink）。purge 命令对无效名称不会报错，而是走「未启用 → 清除」的成功分支，输出 [OK] 但实际什么都没做（实测源码中成功分支只写日志后直接返回成功）。必须写全称 phpbb/viglink，并且先 extension:disable 再 purge；purge 后用 extension:show 和数据库直查双重验证。
Q5：db:revert 报 "is not a valid migration"？
迁移名必须与 db:list 显示的完全一致：带前导反斜杠的完整命名空间，如 '\phpbb\db\migration\data\v33x\v3319'。实测「正斜杠简写」（help 文本声称可用）与双反斜杠转义都会被拒。命令行传参时用单引号包裹，避免 shell 吞掉反斜杠。
Q6：cron:run 执行后没有任何输出，是失败了吗？
不是。实测 cron:run 在没有就绪任务或任务全部执行成功时都输出为空、退出码 0。用 cron:list 查看当前就绪任务，用退出码判断执行结果即可。
Q7：CLI 写入或匹配中文值时要注意什么？
通过 mariadb 命令行直查/直改中文配置时，连接默认字符集不是 utf8mb4，中文会显示或匹配异常，需加 --default-character-set=utf8mb4（详见《Ubuntu 22.04 安装 phpBB 指南》FAQ）。phpBB CLI 自身经 mysqli 驱动连接，读写中文配置值实测正常，但 config:set-atomic 的旧值匹配发生在 SQL 层，建议中文键值尽量走 ACP 或 SQL（utf8mb4 连接）+ cache:purge，减少脚本传参带来的编码变量。
七、参考链接
- phpBB 官方文档（含 CLI 说明）：https://www.phpbb.com/support/docs/
- phpBB 3.3.x 官方发布目录：https://download.phpbb.com/pub/release/3.3/
- 本专栏《phpBB 介绍与选型指南》——版本脉络与同类产品对比
- 本专栏《Ubuntu 22.04 安装 phpBB 指南》——Nginx/Apache 双方案安装与初始化实测
- 本专栏《phpBB 配置参数详解》——config.php、phpbb_config 表与 PHP 层配置逐项解析