Revive Adserver 6.0.8 常用 CLI 命令与工具详解

目标：盘点 Revive Adserver 6.0.8 源码内全部命令行工具（维护主引擎、投递引擎重编译、统计修复四件套、Symfony Console 命令、升级辅助脚本），给出每个工具的用法、实测回显与排障实录。全部命令于 2026-10-29 在全新安装的 6.0.8 实例上逐条实测。安装步骤见本站《Ubuntu 22.04 安装 Revive Adserver 6.0.8 指南》，配置项含义见本站《Revive Adserver 6.0.8 配置参数详解》。

一、环境信息

项目	内容
软件版本	Revive Adserver 6.0.8（schema 628）
安装路径	/var/www/revive-adserver
访问主机名 / CLI host 参数	10.89.71.2（= 配置文件 var/10.89.71.2.conf.php）
数据库	MariaDB 10.6.23，库名 revive_db，表前缀 rv_
PHP	8.1.2（CLI 与 mod_php 同源）
实测日期	2026-10-29

二、CLI 工具全景与 host 参数机制

2.1 工具清单

路径	用途	host 参数	典型调度
scripts/maintenance/maintenance.php	统计汇总 + 优先级引擎 + 数据清理（核心）	必填（第 1 个参数）	cron 每小时
scripts/maintenance/maintenance-distributed.php	分布式部署下的维护分发	必填	仅分布式集群需要
scripts/maintenance/tools/rollupStats.php	把原始统计滚动汇总、释放空间	必填	手工/低频
scripts/maintenance/tools/republish.php	把指定时间片的投递数据重新发布	必填 + 起止时间	手工（修数据）
scripts/maintenance/tools/statisticsTestAndCorrect.php	统计一致性检查与修复	必填	手工（修数据）
scripts/maintenance/tools/migrateBucketData.php	原始桶数据迁移	必填	手工（版本迁移用）
scripts/delivery/rebuild.php	重编译投递引擎（delivery_dev → delivery）	必填	改配置后手工
scripts/db_dataobject/rebuild.php	重建 DataObject schema 映射	必填	开发/表结构变更后
scripts/console	Symfony Console 入口（condense-stats、delete-orphan-images）	可选 --hostname（支持自动探测）	手工
scripts/upgrade/buildXmlCache.php	刷新 MDB2 schema XML 缓存	不需要	开发/CI
scripts/upgrade/rebuildBundledPlugins.php	重打包内置插件	不需要	开发/CI
scripts/upgrade/buildPackagesArray.php	从目录构建插件包清单	不需要	开发/CI

2.2 host 参数机制（必懂）

所有 maintenance/rebuild 类脚本都要你告诉它"用哪份配置"。机制在 init-parse.php：Web 请求用 $_SERVER['HTTP_HOST']，命令行取 $GLOBALS['argv'][1]（第 69 行），再加载 var/<host>.conf.php。

不传 host 的实测结果：

php scripts/maintenance/maintenance.php

PHP Fatal error:  Uncaught RuntimeException: Revive Adserver was called via the command line, but had no host as a parameter. in /var/www/revive-adserver/init-parse.php:69
Stack trace:
#0 /var/www/revive-adserver/constants.php(210): parseIniFile()
#1 /var/www/revive-adserver/init.php(39): setupConstants()
#2 /var/www/revive-adserver/init.php(108): init()
#3 /var/www/revive-adserver/scripts/maintenance/maintenance.php(33): require_once('...')
#4 {main}
  thrown in /var/www/revive-adserver/init-parse.php on line 69

💡 host 参数的值 = 安装时访问用的主机名 = var/ 下配置文件名去掉 .conf.php。本文安装用 http://10.89.71.2:8128/ 访问，所以 host 参数就是 10.89.71.2。用域名安装的实例则传域名。

2.3 运行身份与属主陷阱

两类文件会被 CLI 写到，运行身份必须能写：

var/cache/（缓存）与各类运行时数据——属主应为 www-data。用 root 跑 maintenance 会在这里留下 root 属主文件，后续 Web 侧的目录可写检查会因此把整个 var/ 判为不可写（完整排障见安装指南 10.4 节）。cron 建议用 www-data 身份；
www/delivery/（投递引擎编译产物）——tar 包解压后属 root。实测用 www-data 跑 scripts/delivery/rebuild.php 全部报 Unable to open output file for writing，需用 root 跑（或把该目录 chown 给 www-data）。

三、maintenance.php——维护主引擎

3.1 用法与调度

php /var/www/revive-adserver/scripts/maintenance/maintenance.php 10.89.71.2

它做四件事：把原始投递日志按操作间隔（[maintenance] operationInterval，默认 60 分钟）汇总进中间/汇总表；运行优先级引擎计算各广告权重；执行数据清理（[maintenance] pruneDataTables）；触发插件维护钩子（如 GeoIP2 库检查）。源码入口 scripts/maintenance/maintenance.php 末尾调用 updateLastRun(true) 记录"计划维护最后运行时间"。

cron 建议（安装指南第九节同款，以 www-data 身份每小时执行）：

0 * * * * php /var/www/revive-adserver/scripts/maintenance/maintenance.php 10.89.71.2

3.2 实测

执行（回显为空，脚本成功时静默退出）：

cd /var/www/revive-adserver
php scripts/maintenance/maintenance.php 10.89.71.2
echo $?

数据库侧证据——运行后 rv_application_variable 表的时间戳被更新（实测回显）：

mysql -uroot -pq1w2e3r4 -N -e "SELECT name, value FROM revive_db.rv_application_variable WHERE name LIKE '%maintenance%'"

maintenance_cron_timestamp	1793281168
maintenance_timestamp	1793281162
rvMaxMindGeoIP2Maintenance_version	1.2.10

maintenance_timestamp/maintenance_cron_timestamp 即后台 Maintenance 页判断"计划维护是否 1 小时内运行过"的依据。

3.3 maintenance-distributed.php

仅当系统以分布式模式部署（多台投递机共享中央库）时使用，负责把中央库的分发任务下发给各节点。单机实例运行它等于空转（实测执行退出码 0、无输出）。用法与主引擎一致：php scripts/maintenance/maintenance-distributed.php 10.89.71.2。

四、scripts/delivery/rebuild.php——投递引擎重编译

投递端点 PHP 文件由 www/delivery_dev/ 模板编译生成到 www/delivery/。修改 [file]、[var]、[deliveryHooks] 等影响投递代码形态的配置后必须重编译（配置详解见本站 C1 篇第五节）。

php scripts/delivery/rebuild.php 10.89.71.2

成功输出（实测回显）：

=> STARTING TO RE-COMPILE THE DELIVERY ENGINE FILES
  => Processing php file: ax.php
  => Processing php file: al.php
  => crossdomain.xml is not a php file, copying as-is
  => async.js is a javascript file, leaving untouched
  => Processing php file: apu.php
  => Processing php file: afr.php
  => Processing php file: spc.php
  => Processing php file: ti.php
  => Processing php file: ai.php
  => Processing php file: ac.php
  => Processing php file: tjs.php
  => Processing php file: ajs.php
  => Processing php file: spcjs.php
  => Processing php file: fc.php
  => Processing php file: cl.php
  => Processing php file: lg.php
  => Processing php file: tv.php
  => Processing php file: ck.php
  => Processing php file: avw.php
  => asyncjs.php blacklisted, copying as-is
  => Processing php file: asyncspc.php
  => Time taken: 0.082818984985352 s
=> FINISHED RE-COMPILING THE DELIVERY ENGINE FILES

排障实录：若以 www-data 身份运行而 www/delivery/ 属 root（源码包解压的默认属主），会得到一串（实测回显）：

=> STARTING TO RE-COMPILE THE DELIVERY ENGINE FILES
  => Unable to open output file for writing: /var/www/revive-adserver/www/delivery/ax.php
  => Unable to open output file for writing: /var/www/revive-adserver/www/delivery/al.php
  ...

处理：用 root 运行本脚本（本文采用），或 chown -R www-data:www-data /var/www/revive-adserver/www/delivery 后再用 www-data 跑。

五、scripts/db_dataobject/rebuild.php——DataObject schema 重建

按当前数据库结构重建 lib/max/Dal/DataObjects/ 下的表映射（db_schema.ini 等）。安装态不变时无需运行；手工改过表结构/前缀后使用：

php scripts/db_dataobject/rebuild.php 10.89.71.2

成功时同样静默（退出码 0）。生效证据（实测，schema 文件时间戳被刷新）：

-rw-rw-r-- 1 root root 10250 Oct 29 13:39 /var/www/revive-adserver/lib/max/Dal/DataObjects/db_schema.ini

排障实录：以 www-data 运行且对源码目录无写权限时，直接抛 PHP Fatal（实测回显）：

PHP Fatal error:  Uncaught TypeError: fwrite(): Argument #1 ($stream) must be of type resource, bool given in /var/www/revive-adserver/lib/OA/DB/DataObject/Generator.php:115

本质同样是"写不进目标文件"，用可写身份运行即可。

六、scripts/maintenance/tools/——统计修复四件套

6.1 rollupStats.php——滚动汇总历史统计

把指定日期之前的原始/中间数据滚动压缩，释放库空间。必须带日期参数（YYYY-MM-DD）：

php scripts/maintenance/tools/rollupStats.php 10.89.71.2

缺日期的实测回显：

You must provide the date before which stats should be rolled up! (in YYYY-MM-DD format please)

带日期实测（全新库无历史数据，静默完成、退出码 0）：

php scripts/maintenance/tools/rollupStats.php 10.89.71.2 2026-10-28

6.2 republish.php——重新发布指定时间片的统计

把指定起止操作间隔的投递数据重新聚合（修数场景）。参数：host + 起始时间 + 结束时间（格式 YYYY-MM-DD HH:MM:SS，且须落在操作间隔边界上）：

php scripts/maintenance/tools/republish.php 10.89.71.2

缺时间参数的实测回显：

PHP Warning:  Undefined array key 2 in /var/www/revive-adserver/scripts/maintenance/tools/republish.php on line 38
PHP Warning:  Undefined array key 3 in /var/www/revive-adserver/scripts/maintenance/tools/republish.php on line 39

The start date passed into the republish.php script is not a valid operation interval start date.
Please pass in the start date in '%Y-%M-%d %H:%m:%s' format

只给起始、不给结束时的实测回显：

The end date passed into the republish.php script is not a valid operation interval end date.
Please pass in the end date in '%Y-%M-%d %H:%m:%s' format.

The republish.php script will NOT be run.

💡 起止时间必须与 [maintenance] operationInterval（默认 60 分钟）的时间片边界对齐，否则脚本拒绝执行——这是防止把统计数据切乱的守卫逻辑。

6.3 statisticsTestAndCorrect.php——统计一致性检查

不带参数运行时拒绝执行并要求先读源码内注释（实测回显）：


Please ensure that you have read the comments in the statisticsTestAndCorrect.php script, to ensure that
you fully understand the types of issues with data that the script will address - this script is NOT a
general panacea for every possible kind of data problem!

You will also find out how to make this script work by reading the comments. :-)

按注释要求传参后才会运行。它用于修复汇总表与原始表间的不一致（如中断的维护遗留的错账），修数前务必备份数据库。

6.4 migrateBucketData.php——桶数据迁移

跨版本升级时的历史数据迁移工具，同样有"先读注释"守卫（实测回显）：


Please ensure that you have read the comments in the scripts/maintenance/tools/migrateBucketData.php script.

You will also find out how to make this script work by reading the comments. :-)

The scripts/maintenance/tools/migrateBucketData.php script will NOT be run.

正常从老版本原地升级到 6.0.8 时由升级流程自动调用，手工场景极少。

七、scripts/console——Symfony Console 命令

7.1 入口与命令清单

scripts/console 是无扩展名的可执行 PHP 脚本（保护逻辑：非 CLI 调用直接退出）。命令清单（实测回显）：

php scripts/console list

Console Tool

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
  -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
  condense-stats        Condense statistics in order to free database space
  delete-orphan-images  Delete orphan image files and HTML5 banner folders
  help                  Display help for a command
  list                  List commands

7.2 --hostname 自动探测

与 maintenance.php 不同，console 命令的 --hostname 可省略：源码（lib/RV/Command/AbstractReviveCommand.php 的 getDefaultHostname）在 var/ 下只有一个 *.conf.php 时自动采用它；有多个时读 default.conf.php 的 realConfig 兜底，都不行则报 "Hostname auto-detection impossible"。多配置实例建议始终显式传 --hostname。

7.3 condense-stats——统计压缩

把老数据按"月→日→月"梯度压缩以释放库空间（实测帮助回显）：

php scripts/console help condense-stats

Description:
  Condense statistics in order to free database space

Usage:
  condense-stats [options]

Options:
  -H, --hostname=HOSTNAME            The hostname. If not provided, auto-detection will be enabled
  -f, --force                        Do not request permission to proceed
      --dry-run                      Dry-run operation
  -d, --daily-range=DAILY-RANGE      Number of full months to keep before condensing to daily
  -m, --monthly-range=MONTHLY-RANGE  Number of full months to keep before condensing to monthly
  -b, --process-only=PROCESS-ONLY    Number of months to process before exiting
  -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

dry-run 实测（未配置保留梯度时两档都是 disabled）：

php scripts/console condense-stats --hostname=10.89.71.2 --dry-run

Daily: disabled - Monthly: disabled (DRY-RUN)

实际启用需传 -d/-m（保留的完整月数），先 --dry-run 看影响范围，确认后加 --force 执行。

7.4 delete-orphan-images——孤儿素材清理

扫描 www/images/ 里不被任何广告引用的图片文件与 HTML5 素材目录并删除（帮助回显）：

php scripts/console help delete-orphan-images

Description:
  Delete orphan image files and HTML5 banner folders

Usage:
  delete-orphan-images [options]

Options:
  -H, --hostname=HOSTNAME  The hostname. If not provided, auto-detection will be enabled
  -f, --force              Do not request permission to proceed
      --dry-run            Dry-run operation
  -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

实测确认：即使 --dry-run，执行前也会询问 Are you sure you want to proceed?，非交互环境（cron/脚本）要加 --force。该命令会真删文件，务必先 dry-run，并在素材目录有备份时再执行。

八、scripts/upgrade/——开发与 CI 辅助三件套

8.1 buildXmlCache.php——刷新 schema XML 缓存

把 etc/ 下的 MDB2 schema XML 全部读一遍写入缓存（升级器靠它加速）。实测回显（节选）：

php scripts/upgrade/buildXmlCache.php

=> STARTING TO REFRESH THE MDB2 SCHEMA XML FILE CACHE
  => tables_core.xml: Processed
  => tables_temp_priority.xml: Processed
  => tables_temp_statistics.xml: Processed
  => schema_tables_core_049.xml: Processed
  ...
  => changes_tables_core_628.xml: Processed
  => changes_tables_temp_priority_501.xml: Processed
  => changes_tables_temp_statistics_501.xml: Processed
=> FINISHED REFRESHING THE MDB2 SCHEMA XML FILE CACHE

8.2 rebuildBundledPlugins.php——重打包内置插件

把 10 个内置插件重新打 zip 包（发版/CI 用）。依赖系统 zip 命令——缺 zip 时的实测报错：

=> STARTING TO UPDATE THE BUNDLED PLUGINS
  => openXBannerTypes (1.6.7): ./zipkg.sh: 23: zip: not found
PHP Fatal error:  Uncaught ValueError: Invalid or uninitialized Zip object in /var/www/revive-adserver/scripts/upgrade/rebuildBundledPlugins.php:100

apt-get install zip 后重跑的实测回显（顺带可看到各插件当前版本）：

=> STARTING TO UPDATE THE BUNDLED PLUGINS
  => openXBannerTypes (1.6.7): no changes
  => openXDeliveryLimitations (6.0.9): no changes
  => openXReports (1.6.11): no changes
  => openXDeliveryCacheStore (1.5.8): no changes
  => openXInvocationTags (1.8.19): no changes
  => openXDeliveryLog (1.5.1): no changes
  => openXVideoAds (1.15.10): no changes
  => reviveMailer (1.0.8): no changes
  => reviveMaxMindGeoIP2 (1.2.10): no changes
  => apVideo (1.7.10): no changes
=> FINISHED UPDATING THE BUNDLED PLUGINS

8.3 buildPackagesArray.php——构建插件包清单

两个位置参数：第 1 个为待扫描目录，第 2 个为输出文件。缺参时报警告后以空目录模式结束（实测回显）：

PHP Warning:  Undefined array key 1 in /var/www/revive-adserver/scripts/upgrade/buildPackagesArray.php on line 21
PHP Warning:  Undefined array key 2 in /var/www/revive-adserver/scripts/upgrade/buildPackagesArray.php on line 22
reading directory 
writing file

九、运维注意事项

cron 身份：维护任务用 www-data 身份跑（安装指南第九节），root 跑会留下属主隐患；delivery/rebuild.php 例外，要求对 www/delivery/ 有写权限（root 或 chown 后的 www-data 均可）；
先 dry-run 后动手：condense-stats、delete-orphan-images、statisticsTestAndCorrect 都是动数据/动文件的工具，先 --dry-run（或备份），确认影响范围再 --force 执行；
看结果别猜：maintenance.php 成功时静默，用 rv_application_variable 表的 maintenance_timestamp 确认；rebuild 类工具看输出尾部的 FINISHED 行；
host 参数一致性：所有 CLI 传的主机名必须与 var/<host>.conf.php 同名，用域名安装就传域名，用 IP 安装就传 IP。

十、参考链接

选型与背景：本站《Revive Adserver 介绍与选型指南》
安装与部署：本站《Ubuntu 22.04 安装 Revive Adserver 6.0.8 指南》
配置参数：本站《Revive Adserver 6.0.8 配置参数详解》
官方文档主页：https://www.revive-adserver.com/docs/
源码仓库：https://github.com/revive-adserver/revive-adserver