MediaWiki 1.46 常用 CLI 命令与工具详解

run.php 统一入口与 16 个代表维护脚本逐条实测:install/update/createAndPromote/changePassword/edit/importImages/rebuildall/purgeList/sql/getConfiguration 等,含 1.46 表结构陷阱(ipblocks→block/block_target)与命令回显。

MediaWikiMediaWiki知识库2026/10/22

MediaWiki 1.46 常用 CLI 命令与工具详解

目标:系统梳理 MediaWiki 1.46 的 maintenance/ 命令行维护体系——统一入口 run.php 的用法与公共参数,以及安装升级、账号管理、内容编辑、文件导入、统计重建、缓存刷新、数据库直查、配置导出等 16 个代表脚本逐条实测(命令 + 真实回显 + 参数默认值)。已在 Ubuntu 22.04 + MySQL 8.0.46 + PHP 8.3.36 + MediaWiki 1.46.2 环境全部执行验证。

一、环境信息

  • 操作系统:Ubuntu 22.04.5 LTS(x86_64)
  • MediaWiki:1.46.2(官方 tarball 安装于 /var/www/mediawiki,安装过程见 《Ubuntu 22.04 安装 MediaWiki 1.46 指南》)
  • 数据库:MySQL 8.0.46,库名 wikidb;PHP 8.3.36
  • 演示账号:admin / q1w2e3r4(管理员)、editor(普通演示账号,命令篇中创建)
  • 演示站点:Qzuo Wiki,http://localhost/wiki/首页(Short URL 已配置)
  • 脚本清单规模:maintenance/ 目录实测 211 个条目,本文挑选 16 个最高频脚本逐条实测

二、工具概览

MediaWiki 的 CLI 维护体系由两类文件组成:

  1. 统一入口 maintenance/run.php(1.31+ 引入):负责加载站点配置、解析公共参数、调度目标脚本。1.46 下所有维护脚本的标准调用形态是 php maintenance/run.php <脚本名> [参数]。
  2. 200+ 个维护脚本(maintenance/*.php):覆盖安装(install)、升级(update)、账号(createAndPromote/changePassword)、内容(edit/importImages)、统计(initSiteStats/showSiteStats/rebuildall)、诊断(sql/getConfiguration/checkImages/Version)等域。

按域分类的速查表(全部本文实测过):

域脚本一句话用途
安装升级install一条命令从零安装并生成 LocalSettings.php
安装升级update表结构迁移 + 缓存刷新(升级必跑)
账号管理createAndPromote创建用户并授予用户组
账号管理changePassword改指定用户密码
账号管理resetUserEmail重置用户邮箱
账号管理blockUsers从文件批量封禁账号
内容操作edit从 stdin 写入创建/编辑页面
内容操作importImages批量导入本地图片
内容操作deleteOldRevisions删除历史旧版本
统计重建initSiteStats初始化站点统计计数
统计重建showSiteStats打印站点统计
统计重建rebuildall重建链接表/分类/最近更改等派生数据
缓存刷新purgeList从 stdin 批量清页面缓存
诊断sql直连数据库执行 SQL
诊断getConfiguration导出运行时配置值
诊断checkImages校验已上传图片文件完整性
诊断Version打印 MediaWiki 版本与构建时间

三、前置条件

  1. 已有可运行的 MediaWiki 1.46.x 站点;所有命令在站点根目录执行(cd /var/www/mediawiki),CLI 会自动读取同目录 LocalSettings.php。
  2. 数据库连接信息可用(LocalSettings.php 中的 $wgDBuser/$wgDBpassword);sql 脚本直接使用该连接。
  3. CLI 执行用户对 images/、cache/ 等目录有写权限(导入图片、缓存重建类脚本需要)。
  4. 界面语言为中文的站点,脚本回显会输出中文(本文环境 --lang=zh 安装)。

四、各工具详解

4.1 run.php:统一运行器

先看运行器自身的帮助(实测全文节选):

cd /var/www/mediawiki
php maintenance/run.php --help
Argument <script> is required!

Runner for maintenance scripts

Usage: php maintenance/run.php run.php [OPTION]... <script>

Script runner options:
    --conf <CONF>: Location of LocalSettings.php, if not default
    --globals: Output globals at the end of processing for debugging
    --help (-h): Display this help message
    --memory-limit <MEMORY-LIMIT>: Set a specific memory limit for the
        script, "max" for no limit or "default" to avoid changing it
    --profiler <PROFILER>: Profiler output format (usually "text")
    --quiet (-q): Whether to suppress non-error output
    --server <SERVER>: The protocol and server name to use in URLs, e.g.
        https://en.wikipedia.org. This is sometimes necessary because server
        name detection may fail in command line scripts.
    --wiki <WIKI>: For specifying the wiki ID

Arguments:
    <script>: The name of the maintenance script to run. Can be given as
        a class name or file path. The `.php` suffix is optional. Paths starting
        with `./` or `../` are interpreted to be relative to the current working
        directory. Other relative paths are interpreted relative to the
        maintenance script directory. Dots (.) are supported as namespace
        separators in class names. An extension name may be provided as a
        prefix, followed by a colon, e.g. "MyExtension:...", to indicate that
        the path or class name should be interpreted relative to the extension.

要点:.php 后缀可省(update 等价 update.php);带空格的参数值要引号;查任何脚本参数都可用 php maintenance/run.php <脚本> --help。

4.2 install:CLI 安装

一条命令完成建库建表并生成 LocalSettings.php(本机实测的完整 20 行回显、参数表与密码策略约束见 《Ubuntu 22.04 安装 MediaWiki 1.46 指南》第五章):

php maintenance/run.php install --lang=zh --dbname=wikidb \
  --dbserver=localhost --dbuser=root --dbpass=q1w2e3r4 \
  --pass='QzuoAdmin2026' --scriptpath=/mediawiki 'Qzuo Wiki' admin
已成功创建数据库
MediaWiki已成功安装。您现在可以访问<http://localhost/mediawiki>以查看您的wiki。...

关键参数:--dbname(默认 my_wiki)、--dbserver(默认 localhost)、--dbuser(默认 root)、--pass(管理员密码)、--lang(默认 en)、--scriptpath(URL 路径)、位置参数 <站点名> <管理员名>。

4.3 update:数据库迁移与缓存刷新

升级版本、改动表结构后必跑;重复执行是幂等的(已应用的步骤自动跳过):

php maintenance/run.php update

回显节选(实测末尾):

Adding empty categories with description pages...
Removing empty categories without description pages...
Category cleanup complete.
Fixing log entries with log_title starting with 'User:#'
done.
Skipped 34 updates that were already applied.
Purging caches...
Done in 0.1 s.

4.4 createAndPromote:创建用户并授权

php maintenance/run.php createAndPromote --help
Script specific options:
    --bot: Add the account to the bot group
    --bureaucrat: Add the account to the bureaucrat group
    --custom-groups <CUSTOM-GROUPS>: Comma-separated list of groups to
        add the user to
    --email <EMAIL>: Sets the users email address
    --force: If account exists already, just grant it rights or change
        password.
    --interface-admin: Add the account to the interface-admin group
    --reason <REASON>: Reason for account creation and user rights
        assignment to log to wiki
    --sysop: Add the account to the sysop group

Arguments:
    <username>: Username of new user
    [password]: Password to set

实测创建 editor 并授予 sysop + bureaucrat:

php maintenance/run.php createAndPromote --sysop --bureaucrat editor q1w2e3r4
wikidb: Creating and promoting User:editor into sysop, bureaucrat...
done.

(密码 q1w2e3r4 能通过是因为演示环境已按配置篇 5.6 节放宽了密码策略;默认策略下会报 "Passwords must be at least 10 characters."。)

4.5 changePassword:修改用户密码

php maintenance/run.php changePassword --user=admin --password=q1w2e3r4
Password set for Admin
Invalidated sessions for user Admin

要点:改密成功会立即失效该用户全部会话(Invalidated sessions),避免旧会话残留。

4.6 resetUserEmail:重置用户邮箱

php maintenance/run.php resetUserEmail admin admin@qzuo.example
Invalidated sessions for user Admin
Done!

可选参数(实测帮助):--email-password 给新邮箱发临时密码、--no-reset-password 不强制改密、--reason 记录原因(如工单号)。

4.7 blockUsers:批量封禁账号

封禁清单从文件读取(每行一个用户名),配合 --expiry 与 --reason:

printf 'Editor\n' > /root/blocklist.txt
php maintenance/run.php blockUsers --expiry '1 hour' --reason '测试封禁演示' /root/blocklist.txt
Blocking 'Editor' succeeded.

封禁结果落在数据库(实测查询):

php maintenance/run.php sql --query 'SELECT bt_id,bt_address,bt_user_text FROM block_target;'
stdClass Object
(
    [bt_id] => 1
    [bt_address] =>
    [bt_user_text] => Editor
)

⚠️ 实测重要发现:1.46 里不存在 ipblocks 表(直接查报 Table 'wikidb.ipblocks' doesn't exist),封禁数据已拆分到 block 与 block_target 两张表(1.42+ 的 schema 重构)。解封无独立维护脚本,走 Web 界面 Special:BlockList 或 API。演示环境清理封禁:DELETE FROM block_target 与 DELETE FROM block 各执行一次(实测各影响 1 行)。

4.8 edit:从 stdin 写入页面

printf '这是通过 edit.php 创建的测试页面,用于验证 MediaWiki CLI 编辑能力。\n' \
  | php maintenance/run.php edit --user=admin 'CLI测试页'
Saving...done

验证页面已存在(实测抓取页面 <title>):

CLI测试页 - Qzuo Wiki

要点:页面标题是位置参数,内容从 stdin 读入;重复执行即为追加编辑新版本;--user 指定以哪个账号身份提交(默认 bot 类操作账号)。

4.9 importImages:批量导入本地图片

准备测试图片(用 PHP 内置 GD 生成两张 PNG,实测 478/612 字节):

php -r '$i=imagecreatetruecolor(240,120); imagestring($i,5,30,50,"QzuoWiki Test",imagecolorallocate($i,20,90,180)); imagepng($i,"/root/imgs/qzuo-blue.png"); $j=imagecreatetruecolor(200,200); imagefilledrectangle($j,0,0,199,199,imagecolorallocate($j,220,60,60)); imagepng($j,"/root/imgs/qzuo-red.png");'
ls -l /root/imgs/
-rw-r--r-- 1 root root 478 Oct 21 21:57 qzuo-blue.png
-rw-r--r-- 1 root root 612 Oct 21 21:57 qzuo-red.png

导入(目录 + 扩展名过滤,--user 指定上传者,--comment 写入文件描述页):

php maintenance/run.php importImages --user=admin --comment='批量导入测试图片' /root/imgs png
Importing qzuo-blue.png...done.
Importing qzuo-red.png...done.

Found: 2
Added: 2

重复执行验证幂等性(实测):

qzuo-blue.png exists, skipping

Found: 2
Skipped: 2

要点:--sleep 可限速、--protect 指定保护级别;同名文件已存在则跳过(Skipped),不会覆盖。

4.10 initSiteStats / showSiteStats:统计初始化与查看

php maintenance/run.php initSiteStats
php maintenance/run.php showSiteStats

Done.
Total edits       : 1
Number of articles: 0
Total pages       : 1
Number of users   : 3
Active users      : 1
Number of images  : 0

(输出分两段:Done. 为 initSiteStats 的收尾,其后六行是 showSiteStats 的统计表——实测共六项:edits/articles/pages/users/active/images;导入两张图片后再跑 showSiteStats,Number of images 变为 2,计数联动正确。大站统计漂移时可加 --update 增量重算或 --active 重算活跃用户。)

4.11 rebuildall:重建派生数据

等价于串行跑 refreshLinks + updateCollation + 分类清理等,页面链接/分类显示异常时的修复利器:

php maintenance/run.php rebuildall

回显节选(实测末尾,每张派生表报告处理行数):

    externallinks: 0 deleted.
    iwlinks: 0 deleted.
    langlinks: 0 deleted.
    redirect: 0 deleted.
    page_props: 0 deleted.
Done.

4.12 deleteOldRevisions:清理旧版本

php maintenance/run.php deleteOldRevisions
Searching for active revisions...done.
Searching for inactive revisions...done.
0 old revisions found.

要点:不带参数是「dry-run 风格」只报告数量,实测 --delete 才真正删除(本环境每页仅 1 个版本,0 条可删,故未执行删除)。

4.13 purgeList:批量清页面缓存

标题列表从 stdin 读入(每行一个),输出将清的两个 URL(正文+历史页):

printf '首页\n' | php maintenance/run.php purgeList
http://localhost/mediawiki/index.php?title=%E9%A6%96%E9%A1%B5&action=history
Purging 2 urls
Done!

要点:一个标题会同时清正文与 action=history 两个 URL;CDN 前置时它会携带 purge 请求发往 $wgCdnServers。

4.14 sql:直连数据库执行 SQL

php maintenance/run.php sql --query 'SELECT user_id,user_name,user_real_name FROM user;'

完整回显(实测,4 行用户数据):

stdClass Object
(
    [user_id] => 1
    [user_name] => MediaWiki default
    [user_real_name] =>
)
stdClass Object
(
    [user_id] => 2
    [user_name] => Admin
    [user_real_name] =>
)
stdClass Object
(
    [user_id] => 3
    [user_name] => Maintenance script
    [user_real_name] =>
)
stdClass Object
(
    [user_id] => 4
    [user_name] => Editor
    [user_real_name] =>
)

⚠️ 实测两条纪律:① 一次 --query 只执行一条语句(; 串联多条会报错),要逐条调用;② 写操作(DELETE/UPDATE)同样受支持,回显 Query OK, 1 row(s) affected,生产环境务必先在备份库演练。

4.15 getConfiguration:导出运行时配置

php maintenance/run.php getConfiguration --regex 'wgEnableUploads|wgMainCacheType|wgSitename|wgDBname|wgScriptPath'
a:5:{s:8:"wgDBname";s:6:"wikidb";s:15:"wgEnableUploads";b:0;s:15:"wgMainCacheType";i:3;s:12:"wgSitename";s:9:"Qzuo Wiki";}

要点:默认 --format php 为 PHP 序列化格式(s:15:"xxx" = 15 字节字符串、b:1 = true、i:3 = 整数 3,此处 wgMainCacheType=3 即 CACHE_ACCEL/APCu);--format json 输出更易读。完整用法见 《MediaWiki 1.46 配置参数详解》 3.1 节。

4.16 checkImages / Version:诊断与版本

php maintenance/run.php checkImages
Good images: 2/2
php maintenance/run.php Version
MediaWiki version: 1.46.2 (built: 2026年10月21日 (三) 21:58)

要点:checkImages 逐个校验 images 目录与数据库记录的一致性(丢失/损坏会逐条列出);Version 注意首字母大写(脚本文件为 Version.php),括号内为构建/更新时间。

五、注意事项

  1. 执行目录:所有脚本默认从当前目录向上找 LocalSettings.php,在站点根目录执行最稳;跨 wiki 多站点部署用 --wiki <wikiId> 指定实例。
  2. 公共参数:所有脚本共享运行器参数——--quiet 静默、--memory-limit max 放开内存(大批量重建时建议加)、--server <URL> 在 cron 环境固定站点 URL(否则链接生成可能异常)。
  3. 幂等性:update/importImages/initSiteStats 重复执行安全(跳过已完成项);deleteOldRevisions、sql 写操作、blockUsers 具有破坏性,先备份再执行。
  4. 密码策略:createAndPromote/changePassword 都受 $wgPasswordPolicy 约束,弱口令必须先按组放宽(仅测试环境)。
  5. 大站节奏:rebuildall 在大库上是小时级操作,用 screen/tmux 挂后台并配合 --memory-limit max。

六、常见问题

Q1:php maintenance/run.php install 报 "Missing one or more required PHP extensions"(列 mbstring/xml/intl) CLI 的 php 指向了旧版本(如系统默认 8.1 而站点装了 8.3)。用 php -v 核对当前版本,update-alternatives --set php /usr/bin/php8.3 切换后复跑。

Q2:createAndPromote/changePassword 报 "Passwords must be at least 10 characters." MediaWiki 默认密码策略(sysop/bureaucrat/interface-admin/bot 组 10 位 + 常见口令清单校验)。要么用 12 位以上强口令,要么在 LocalSettings.php 按组放宽策略(测试环境做法,见配置篇 5.6 节)。

Q3:sql --query 'SELECT ... FROM ipblocks' 报 "Table 'wikidb.ipblocks' doesn't exist" 1.42+ schema 重构后封禁数据在 block 与 block_target 两张表(本文 4.7 节实测),查 SHOW TABLES LIKE '%block%' 可见;老教程里的 ipblocks 查询一律需要改写。

Q4:一次 --query 里写两条 SQL 报错 sql 脚本一次只执行一条语句(实测),多条请分多次调用。

Q5:importImages 提示文件被跳过 同名文件已存在(Skipped)。要覆盖先到 Special:ListFiles 删除旧文件,或改用新文件名导入。

Q6:脚本输出英文而不是中文? 回显语言跟随站点 $wgLanguageCode(中文站点脚本输出中文),个别脚本固定英文属正常现象,以 --help 输出为准。

七、参考链接