HumHub 1.19.3 常用 CLI 命令与工具详解

本文把 HumHub 1.19.3 的运维控制台（yii 命令族）与随服务发行的辅助脚本讲全，全部命令在 2026-11-02 对真实运行实例实测，回显逐行照抄（含报错原文）。实例由 《HumHub 1.19.3 Docker Compose 部署指南》 部署，参数语义见 《HumHub 1.19.3 配置参数详解》。

一、CLI 入口与执行方式

1.1 官方入口形态

官方 CLI 文档（humhub/docker 仓库 docs/cli.md，2026-11-02 查阅）给出的标准执行方式——在主机上 compose 文件所在目录运行，把命令送进应用服务进程组：

docker compose exec humhub /app/yii <command>

不带参数列出全部可用命令：

docker compose exec humhub /app/yii

/app/yii 外层包装脚本有身份检查（源码实测）：以 root 执行会自动切换到 www-data 身份运行真正的 /app/bin/yii；其他身份直接拒绝并回显：

This wrapper must be run as root or www-data

1.2 命令总览（实测全表）

/app/yii 裸跑回显 "This is Yii version 2.0.55."，随后按控制器分组列出命令族（2026-11-02 实测，共 25 组）：

二、cron 族：定时任务

HumHub 的定时体系不依赖系统 crontab——服务进程组里的调度器按周期自动跑（内置机制）。CLI 的 cron 族用于手动强制执行，典型场景是装完模块后立刻触发清理/摘要：

docker compose exec humhub /app/yii cron/run

实测静默无输出（正常执行，退出码 0）。分级别强制触发有回显：

docker compose exec humhub /app/yii cron/daily

Executing daily tasks:

Deleting old notifications... done.
Deleting old unassigned files... done.

docker compose exec humhub /app/yii cron/hourly

Executing hourly tasks:

（本实例小时级暂无注册任务，输出仅标题行。）每日任务的基准时刻由 params.dailyCronExecutionTime（默认 18:00）控制，见配置篇 1.2 节实测。

三、cache 族：缓存清理

docker compose exec humhub /app/yii cache/flush-all

实测回显：

The following cache components were processed:

	* cache (yii\caching\FileCache)
	* runtimeCache (yii\caching\DummyCache)

注意第二项：控制台上下文里 runtimeCache 降级为 DummyCache（Web 上下文是 ArrayCache），属预期行为。改配置/改表结构后的三板斧：cache/flush-all（全量）、cache/flush <组件名>（指定）、cache/flush-schema db（仅清表结构缓存）。服务启动脚本在安装完成后会自动执行 flush-all + 迁移（官方入口脚本逻辑，见部署篇第六章）。

四、migrate 族：数据库迁移

docker compose exec humhub /app/yii migrate/up --includeModuleMigrations=1

Yii Migration Tool (based on Yii v2.0.55)

No new migrations found. Your system is up-to-date.

• --includeModuleMigrations=1 是关键开关：核心迁移默认包含，模块迁移必须显式带上；官方启动序列是先跑核心（=0）再 module/update-all 后跑全量（=1）。
• migrate/new 只列出未应用迁移、不写入——服务的就绪等待脚本正是用 "No new migrations found" 字符串判断放行调度器/队列（源码实测）。
• migrate/history 查已应用版本；migrate/to/migrate/fresh 属危险操作（fresh 会删全表重放），仅测试环境使用。

五、queue 族：任务队列

队列驱动默认 MySQL 表（配置篇 3.1），无需外部 MQ：

docker compose exec humhub /app/yii queue/info

Jobs
- waiting: 0
- delayed: 0
- reserved: 0
- done: 0

• queue/run：手动消费一轮积压任务（实测无积压时静默返回）。
• queue/listen：常驻监听——服务进程组里的 2 个 worker 就是它（HUMHUB_DOCKER__NUMPROCS_WORKER=2），实测日志可见任务逐条 Started/Done 带耗时与内存：

[humhub-worker_01] 2026-11-02 06:18:37 [7] humhub\modules\live\jobs\DatabaseCleanup (attempt: 1, pid: 233) - Started
[humhub-worker_01] 2026-11-02 06:18:37 [7] humhub\modules\live\jobs\DatabaseCleanup (attempt: 1, pid: 233) - Done (0.015 s, 13.95 MiB)

• queue/clear 清空队列、queue/remove <id> 删单任务：用于处理反复失败的毒任务。

六、settings 族：数据库运行设置

后台设置页的 CLI 等价物（读写 setting 表，语义见配置篇第五节）：

docker compose exec humhub /app/yii settings/set base displayNameSubFormFormat "test {firstname} {lastname}"

*** Successfully set setting

docker compose exec humhub /app/yii settings/delete base displayNameSubFormFormat

*** Successfully deleted setting

settings/list 全量、settings/list-module <模块ID> 按模块过滤（实测 base 模块含 oembed 端点表、空间默认权限等大量行，输出为窄列 ASCII 表格、长值换行，脚本消费建议配合 grep）。改完设置若未生效，补一发 cache/flush-all（配置篇排障第 1 条）。

七、module 族：模块管理

docker compose exec humhub /app/yii module/list

实测回显（节选）：

Installed Modules (22)
────────────────────────────────────────────
  ID                          STATUS      VERSION       NAME
  ──────────────────────────────────────────────────────────────────────
  web                         disabled    1.0           Web
  notification                disabled    1.0           Notifications
  ...
  user                        disabled    1.0           User

  0 of 22 module(s) enabled.

注意实测语义：核心模块在该列表里一律显示 disabled、且不计入 enabled 统计（"0 of 22"）——核心模块随系统常驻，不受 enable 开关管辖；该列表真正关心的是市场/自装模块。其余子命令：

• module/info <id>：查单模块状态，实测 space 回显 Installed: Yes / Enabled: No / Version: 1.0 / Path: /opt/humhub/protected/humhub/modules/space。
• module/list-online：列市场在线模块（需 params.humhub.apiEnabled=true 出网）。
• module/install <id> / enable / disable / remove：市场模块生命周期；updater 模块被发行包默认黑名单屏蔽（配置篇 2.1 表），升级走换版本 tag。
• module/update-all：批量更新到兼容最新版，官方升级序列的一环。
• module/register <license-key>：付费模块/专业版授权注册。

八、installer 族：免交互安装

安装向导的命令行等价物（部署篇第五章的 Web 流程可整体脚本化）：

CI/批量开站场景：compose 里给齐 HUMHUB_CONFIG__COMPONENTS__DB__* 环境变量后，入口脚本自动开启免检模式（ENABLE_AUTO_SETUP=true，实测安装器据此跳过预检与数据库两步），再用 installer/create-admin-account 补管理员即可无人值守。

九、content-search 与 integrity：搜索索引与数据体检

docker compose exec humhub /app/yii content-search/rebuild

..OK!

重建全文索引（content_fulltext 表）。content-search/find <关键词> 查索引、queue-rebuild 走队列异步重建。optimize 实测直接报错（见本章排障实录第 2 条）。

docker compose exec humhub /app/yii integrity/run

Validating: User Module - Content container (4 entries)

*** All integrity checks done

数据一致性巡检（后台"维护"页的 CLI 版），排障时先跑它确认没有孤儿数据。

十、file / theme / test：辅助工具

• file/index：上传文件盘点，实测回显：

*** File module console

╔════════════════════════════════╤═════╗
║ Total number of uploaded files │ 0   ║
╟────────────────────────────────┼─────╢
║ Size                           │ 0 B ║
╚════════════════════════════════╧═════╝

Automatically generated file variants:
╔═════════╤══════╗
║ Variant │ Size ║
╚═════════╧══════╝

• file/downscale-images：把存量图片按最大尺寸/质量重缩（改了图片配置后批量应用）；file/delete-variants：删除全部派生变体（预览图），首屏变慢但省磁盘。
• theme/info：主题盘点，实测回显当前激活主题 HumHub，路径 /opt/humhub/protected/humhub/themes/HumHub——印证 1.19 起默认主题不再放数据目录（官方入口脚本注释）。
• test/db-connection：连通性自检；test/email <地址>：按当前邮件设置发测试信，实测回显 Message successfully sent!，file 传输模式下落盘可查：

/app/runtime/mail/20261102-142350-0722-0172.eml

• ldap 族（status/sync/mapping-rebuild 等 7 个子命令）：LDAP 模块启用后可用，域同步排障主力；space/assign-all-members：空间批量成员操作。

十一、随服务发行的运维脚本

/app/bin/ 目录实测清单（除 yii 外均为 bash 脚本）：

主机侧对这三类进程组（Web/调度/队列）的开关即 HUMHUB_DOCKER__AUTOSTART_* 三变量（配置篇 2.1 表），拆分部署时把 Web 进程的三项设 true,false,false、调度/队列各自单开角色。

十二、CLI 排障实录

1. help 的路由写法坑。yii help/cron/run 实测报错：

Unknown command: help/cron/run
Caused by: Exception 'yii\base\InvalidRouteException' with message 'Unable to resolve the request: help/cron/run'

正确写法是空格分隔：yii help cron/run，实测正常输出该命令的 DESCRIPTION/USAGE/OPTIONS（--appconfig、--color 等通用选项）。同理 help migrate/up 报错、help migrate up 可行。

2. content-search/optimize 在默认驱动下不可用。实测报错原文：

Optimizing search index: Exception 'yii\base\UnknownMethodException' with message 'Calling unknown method: humhub\modules\content\search\driver\MysqlDriver::optimize()'

默认全文索引驱动是 MySQL（MysqlDriver），未实现 optimize()——该子命令只对支持 optimize 的外部搜索驱动（如 Sphinx 类）有意义。MySQL 驱动下重建索引用 content-search/rebuild（实测 ..OK!）。

3. cron/run 静默不等于失败。与 cron/daily 有回显不同，cron/run 无输出（实测退出码 0）；验证是否真跑了任务，看 worker 日志的 Started/Done 行或 queue/info 计数变化。

4. module/list 的 "0 of 22 enabled" 不是异常。核心模块不计入 enabled（见第七章），市场模块装好后才会在这里出现非零计数。

5. 非特权身份跑 yii 被拒。身份检查见 1.1 节回显；官方 compose 形态下用 docker compose exec humhub /app/yii ... 进入即自带正确身份，无需手工切换。