Live Helper Chat 4.97v 常用 CLI 命令与工具详解

目标：系统讲清 Live Helper Chat 4.97v 的命令行工具体系——唯一的命令行入口 cron.php 的参数语法与安全校验、modules/lhcron/ 下全部计划任务控制器的用途与调度建议、缓存/数据库/文件三大维护工具、无人值守安装器 install-cli.php、队列 worker 入口 resque.php，以及日志排障方法。全部命令输出均取自 4.97v 实机实测（2026-10-26），所有命令默认在应用根目录 lhc_web/ 下执行。

一、CLI 体系总览

LHC 没有独立的 shell 工具集，命令行能力集中在应用根目录的少数几个入口文件：

入口	用途	面向场景
`cron.php`	核心 CLI 入口，按 `-c` 参数执行 modules/lhcron/ 下的任务控制器	计划任务、维护、升级
`cli/install-cli.php`	无人值守安装器	批量部署/自动化
`resque.php`（启用 lhcphpresque 扩展后出现）	队列 worker 进程入口	后台队列消费
`composer.phar`（自备）	依赖安装/更新	升级、补依赖

所有计划任务和绝大多数维护操作都走 php cron.php ...，记住一个入口即可。

二、cron.php 参数体系

2.1 四个参数

php cron.php -s <siteaccess> -c <cronjob> [-e <extension>] [-p <path>]

参数	必填	说明
`-s` / `--siteaccess`	是	站点入口，维护任务一律用 `site_admin`
`-c` / `--cronjob`	是	任务路径（不含 `lh` 前缀与 `.php` 后缀），对应 `modules/lh<cronjob>.php`
`-e` / `--extension`	否	从扩展目录执行任务：`extension/<e>/modules/lh<cronjob>.php`
`-p` / `--path`	否	部分任务自己的附加参数（如 `update_database` 的 `-p local`）

源码注释里给的两个标准示例：

php cron.php -s site_admin -c cron/workflow
php cron.php -s site_admin -e customstatus -c cron/customcron

2.2 缺参会怎样（实测）

不带任何参数直接执行会立即抛配置异常（siteaccess 为空导致找不到 site_access_options 配置节）：

$ php cron.php
Exception: Setting with section {site_access_options} value {} in
/var/www/livehelperchat/lhc_web/lib/core/lhconfig/lhconfig.php:28

因此 -s site_admin 是每次调用的固定前缀，没有交互式默认值。

2.3 路径安全校验（实测）

cron.php 对 -c 与 -e 做两层校验：正则只允许字母数字下划线连字符与斜杠，随后 realpath 确认解析结果落在 modules 目录内（防目录穿越）：

$ php cron.php -s site_admin -c cron/../settings
Invalid cronjob option value

$ php cron.php -s site_admin -e noexist -c cron/test
Cronjob file not found or not allowed

遇到这两种输出说明参数写错或扩展未安装，不是故障。

三、计划任务控制器全表（modules/lhcron/）

3.1 核心运行任务

任务（-c 值）	作用	实测输出
`cron/workflow`	最核心：关闭超时聊天、清理挂起会话、自动分配坐席	`Starting chat/workflow at 2026-10-26 09:21:01` / `Closed chats - 0` / `Purged chats - 0` / `Auto assignment starts/ended ...`
`cron/transfer`	部门间转移（依赖后台 transfer_if_na 配置）	无待转移时静默
`cron/webhook`	处理 webhook 出站事件队列	静默
`cron/update_views`	刷新在线访客视图	静默

cron/workflow 建议每分钟执行一次，这是 LHC 后台"自动分配/自动关闭"行为的时间基准；不跑它，排队聊天永远不会自动流转。

3.2 每日与低频任务

任务	作用	实测输出
`cron/archive`	归档超期聊天（含文件维护子流程）	`Starting archive workflow` / `Automatic chats archiving is not setup`（未配置归档策略时）
`cron/encrypt`	按策略加密历史消息	`Starting chat encrypt workflow` / `Automatic chats encrypting is not setup`（未配置时）
`cron/report`	发送报表邮件	`Starting report sending` / `Ended report sending`
`cron/departament-availability`	预生成部门可用性索引	`Already indexed - <部门名> at <分钟>`
`cron/login_monitoring`	登录安全监控（口令策略/锁定）	静默
`cron/mailing`	邮件营销/群发队列投递（mailconv 扩展）	静默
`cron/notifications`	未读消息通知	静默
`cron/syncmail`	邮件账户 IMAP 同步（80 分钟防重入窗口）	静默
`cron/archive_mail`	邮件对话归档	静默
`cron/mail/auto_close`	自动关闭无响应邮件对话	静默
`cron/mail/monitor_mailbox`	邮箱轮询监控	静默
`cron/stats/department`	部门统计聚合	静默
`cron/stats/department_load`、`cron/stats/performance`	负载/性能统计	静默

3.3 util 维护工具箱（cron/util/*）

任务	作用	实测输出
`cron/util/clear_cache`	清缓存：模板编译、配置缓存全部重建	`Finished clearing cache`
`cron/util/update_database`	升级后更新数据库结构，`-p local` 用本地 schema	`Using remote database schema to update database` / `UPDATE DONE`
`cron/util/maintain_files`	按保留策略清理上传文件	`Starting Automatic files removing workflow ...` / `Automatic files maintenance is not setup ...`（未配置保留策略时）
`cron/util/maintain_database`	数据库例行维护	静默
`cron/util/check_archives`	归档完整性检查	静默
`cron/util/generate_css`	重新生成主题 CSS	静默
`cron/util/generate_structure`	重建模块结构缓存	静默
`cron/util/generate_translation_file`	重建翻译文件	静默
`cron/util/test_antivirus`	测试防病毒集成	静默
`cron/util/update_files`、`update_times`、`reparse_url_args` 等	一次性数据修复	静默

3.4 官方调度建议

官方分发的 cron 定义文件对 15 条任务给出了频率，源码安装时可换算成系统 crontab：

频率	任务
每分钟	`cron/workflow`、`cron/webhook`、`cron/transfer`、`cron/mail/auto_close`、启动脚本（worker 看护）
每 5 分钟	启动脚本 `cron_5m.sh` 包装的一组任务
每 15 分钟	`cron/mail/monitor_mailbox`
每 6 小时 / 每 8 小时 / 每 12 小时	6h 启动脚本 / `cron/util/maintain_files`（每日 7 点）/ `cron/stats/department`
每日定点	5 点 `cron/archive`、6 点 `cron/encrypt`、`cron/report`、8 点 `cron/util/maintain_database`

最小可用配置：把 cron/workflow 挂到每分钟，其余按需挂载。所有条目建议以 Web 服务器运行用户执行并重定向输出。

四、无人值守安装器 install-cli.php

cli/install-cli.php 用一个 ini 文件完成与 Web 向导等价的三步安装，适合批量部署：

php cli/install-cli.php settings.ini

ini 样例（cli/example.settings.ini）关键段：

[db]
host = localhost
user = user
password = xxxxxxx
database = livehelperchat
port = 3306

[admin]
AdminUsername = username
AdminPassword = xxxxxxxx
AdminEmail = example@domain.com
AdminName = Name
AdminSurname = Surname
Domain = domain.com
DefaultDepartament = Departament
ForceVirtualHost = 0
Extensions =
TimeZone = UTC
WebhooksEnabled = 0
WebhooksWorker = http
DefaultConfigs = []
; DefaultConfigs['sharing_nodejs_path'] = 'somepath'

要点：

[admin] 段字段与 Web 向导第三步一一对应（DefaultDepartament 为官方拼写）；
ForceVirtualHost 决定生成配置里的 URL 形态（与配置篇 2.3 节呼应）；
DefaultConfigs 可在安装瞬间覆写任意 lh_chat_config 默认值，实现"装完即符合运维基线"。

五、队列 worker 入口 resque.php

启用 lhcphpresque 扩展后，应用根目录会出现 resque.php。它是常驻进程入口，由官方脚本包装启动，手工启动的等价形式：

REDIS_BACKEND=127.0.0.1:6379 REDIS_BACKEND_DB=1 \
INTERVAL=1 COUNT=6 VERBOSE=0 QUEUE='*' php resque.php

环境变量	说明
`REDIS_BACKEND`	队列 Redis 地址（注意与主配置 `redis` 节相互独立）
`REDIS_BACKEND_DB`	队列 db 号，官方默认 1
`COUNT`	worker 数量（官方默认取 `LHC_RESQUE_WORKERS_COUNT`，缺省 2）
`QUEUE`	消费的队列名，`*` 为全部
`INTERVAL`	取任务间隔秒数

健康检查直接查 Redis：resque:workers 有注册键、resque:stat:processed 计数在增长、各 resque:queue:* 长度归零，即 worker 正常。Webhook worker 模式设为 resque 后，该进程不跑，出站事件会积压在队列里。

六、日志与排障

6.1 cron 任务的异常记录

cron.php 注册了全局错误与异常处理器：致命错误和未捕获异常在写 stderr 的同时，会以 JSON 形式写入应用日志，category 分别为 cronjob_fatal 与 cronjob_exception。排查计划任务"没跑出预期效果"时优先搜这两类记录，而不是盯着任务 stdout。

6.2 常见问题速查

现象	原因与处理
`Invalid cronjob option value`	`-c` 含非法字符或路径穿越，改正任务名
`Cronjob file not found or not allowed`	任务名写错，或 `-e` 指定的扩展未安装/未启用
裸执行抛 `Setting with section {site_access_options}`	漏了 `-s` 参数，补 `-s site_admin`
改了配置/模板不生效	执行 `php cron.php -s site_admin -c cron/util/clear_cache`（见配置篇第八节）
升级后页面报数据库字段错误	跑 `php cron.php -s site_admin -c cron/util/update_database -p local` 后再 clear_cache
队列积压、webhook 不发	worker 未运行：按第五节手工拉起并检查 Redis 键
聊天不自动关闭/不自动分配	`cron/workflow` 没挂到 crontab，或频率低于每分钟

七、小结

场景	命令
日常心跳	`php cron.php -s site_admin -c cron/workflow`
清缓存	`php cron.php -s site_admin -c cron/util/clear_cache`
升级库结构	`php cron.php -s site_admin -c cron/util/update_database -p local`
文件清理	`php cron.php -s site_admin -c cron/util/maintain_files`
无人值守安装	`php cli/install-cli.php settings.ini`
队列 worker	`COUNT=6 QUEUE='*' php resque.php`

相关阅读：配置参数与生效规则见《Live Helper Chat 4.97v 配置参数详解》；部署方式见《Debian 12 安装 Live Helper Chat 4.97v 指南》与《Docker Compose 部署 Live Helper Chat 4.97v 指南》；组件定位与选型见《Live Helper Chat 4.97v 介绍与选型指南》。