YwxAppThink/docs/自定义命令清单.md

YwxApp 自定义命令清单

生成日期：2026-07-30 运行方式：在项目根目录执行 php think <命令> [参数] [选项] 命令注册入口：ywxapp/service/AppService.php 的 boot() 方法（$this->commands([...])） 命令类扫描范围：app/command、ywxapp/command、addon/*/command

---

一、已注册命令（实际可用，共 14 个）

按功能分组列出。

1. 插件管理

addon:manage <插件名> -a <action>

• 文件：ywxapp/command/addon/Manage.php（health 动作委托 app/command/AddonHealth.php）
• 用途：插件统一管理入口，合并原 addon:develop / addon:install / addon:refresh-menu / addon:reload / addon:health 五条命令为单入口。
• 参数：
  • <插件名>（可选）：部分动作需要；留空语义见各动作
  • -a, --action（必填）：develop | install | refresh-menu | reload | health
• 动作与选项：
  • develop：开发者模式安装（源码已在 addon/<name>，原地建表 / 注入菜单 / 启用，免打包）。例：php think addon:manage mqttbroker -a develop
  • install：安装插件。--local=<zip> 离线安装；--force 在线强制覆盖。例：php think addon:manage demo -a install / php think addon:manage demo -a install --local=/path/addon.zip
  • refresh-menu：重导菜单（menu.json → admin_power / user_rule），不改安装 / 启用、不跑 SQL；插件名留空 = 刷新全部。例：php think addon:manage / php think addon:manage blog -a refresh-menu
  • reload：热重载（需 app_debug）。--force 强制；--status 查看状态；插件名留空 = 全部。例：php think addon:manage myplugin -a reload --force / php think addon:manage -a reload --status
  • health：健康检查（委托 AddonHealth）。[插件名] 可选；--detail 详情；--fix 修复；--output=text|json|html；--send-alert；--webhook=<url>；--email=<addr>；--save-report。例：php think addon:manage -a health / php think addon:manage myplugin -a health --fix / php think addon:manage -a health --output=json --send-alert

ywxapp:upgrade

• 文件：ywxapp/command/Upgrade.php
• 用途：本地离线升级一键命令。绕过在线下载，直接对本地打包产物执行升级，复用系统既有升级逻辑：
  • 框架：FrameworkService::apply() —— 备份、解压覆盖、跑 upgrade.sql、写回 config/ywxapp.php 版本号（自动备份到 runtime/framework/backup/）。
  • 插件：AddonService::localUpgrade() —— 备份旧目录、解压覆盖（含 Zip Slip 防护与 static 资源处理）、增量 SQL、更新 info.php 版本（自动备份到 runtime/addon/backup/）。
  • 区别于 addon:manage -a install --local=（首次安装，插件已存在会拒绝）：本命令支持覆盖已安装插件的离线升级。
• 选项：
  • -f, --file=<zip>（必填）：升级包本地路径（绝对或相对项目根）
  • -t, --type=<type>（必填）：framework | addon
  • -r, --ver=<ver>（可选）：目标版本号。framework 必填（写入 config/ywxapp.php）；addon 自动从 zip 内 info.php 读取
  • -p, --patch：框架补丁包标记（核心包，解压时剥离 ywxapp/ 前缀解到 ywxapp/；整站包勿加）
• 示例：
  • 框架整站包：php think ywxapp:upgrade -f runtime/framework/ywxapp-1.0.9.zip -t framework -r 1.0.9
  • 框架核心补丁包：php think ywxapp:upgrade -f runtime/framework/ywxapp-1.0.9.zip -t framework -r 1.0.9 -p
  • 插件升级：php think ywxapp:upgrade -f runtime/market/forum-1.0.2.zip -t addon
• 注意：执行后会提示清理 runtime/cache、runtime/temp；插件升级前会自动备份到 runtime/addon/backup/<name>-<ver>-<时间戳>/，失败可回滚。

2. 数据库

install:copy

• 文件：app/command/InstallCopy.php
• 用途：复制 / 初始化本项目数据库安装（核心表 + 插件表）。脚本只执行 CREATE TABLE / INSERT（白名单），对已存在的表 / 数据做幂等跳过。
• 选项：
  • -c, --core：仅安装核心表
  • -a, --addon=<name>：仅安装指定插件（逗号分隔），默认全部插件
• 示例：
  • php think install:copy
  • php think install:copy --core
  • php think install:copy --addon=blog,wxchat

3. 服务进程（常驻 / 网关）

workerman:gateway

• 文件：ywxapp/command/GatewayWorker.php
• 用途：启动 Workerman GatewayWorker 服务（Register / Gateway / BusinessWorker）。
• 选项：
  • -a, --acthon=<val>：操作（start / stop / restart 等，透传给 Workerman）
• 示例：php think workerman:gateway -a start

wxchat:server

• 文件：addon/wxchat/command/ChatServer.php
• 用途：启动 wxchat 的 GatewayWorker 即时通讯服务。
• 选项：
  • -a, --action=<val>：操作（如 start）
• 示例：php think wxchat:server -a start

mqttbroker:start

• 文件：addon/mqttbroker/command/MqttBroker.php
• 用途：启动 MQTT Broker 常驻进程（兼容 MQTT 3.1.1 / 5.0，类 EMQX 轻量 broker，零外部依赖；转发规则桥接 EMQX 需 workerman/mqtt，未安装时自动跳过）。
• 选项：
  • -p, --port=<val>：监听端口（默认 1883）
  • -H, --host=<val>：监听地址（默认 0.0.0.0）
• 示例：php think mqttbroker:start / php think mqttbroker:start -p 1883

4. 插件运维 / 监控

addon:health / addon:reload 已并入 addon:manage

• 原 addon:health、addon:reload 现统一为 addon:manage -a health / addon:manage -a reload，选项与行为不变。详见上文 §1 addon:manage。

addon:license-check

• 文件：ywxapp/command/AddonLicenseCheck.php
• 用途：运行期授权巡检（Discuz 式：已启用付费插件定期复查授权，过期自动禁用）。遍历 addon/ 下已启用且 info['license']=true 的付费插件，逐个向中心站 validDomain 校验，校验拒绝或（非 offline_tolerant 时）中心站不可达 → 落库 status=0 禁用并写 Log::warning。放行条件：调试+未知来源 / config('ywxapp.addon_license_check')===false / 非客户机（!is_market_client()）时直接跳过。
• 依赖：仅客户机（is_market_client()===true）且 addon_license_check 开启时生效。
• 示例：
  • php think addon:license-check
  • crontab（建议每日 03:10 巡检一次）：

    10 3 * * * cd /path/to/site && php think addon:license-check >> runtime/license_check.log 2>&1
    

  • 仅观察不禁用：临时设 addon_license_check=offline_tolerant 后运行，中心站不可达不禁用（仅真实过期拒绝仍禁用）。

5. 代码生成

make:modely <name>

• 文件：ywxapp/command/ModelY.php
• 用途：创建一个新模型类（继承自 think\console\command\Make）。
• 参数：
  • name（必填）：模型类名，例如 Yasd
• 示例：php think make:modely Yasd

6. 第三方 / 业务集成

mqttbroker:acltest

• 文件：addon/mqttbroker/command/TestAcl.php
• 用途：ACL 实网决策验证，用真实 DB 规则校验 Auth::checkAcl 的放行 / 拒绝逻辑（deny 拒绝、默认放行、用户定向拒绝、超管绕过、$SYS 只读）。不依赖运行中的 Broker。
• 示例：php think mqttbroker:acltest

haonav:checklinks

• 文件：addon/haonav/command/CheckLinks.php
• 用途：haonav 网址导航死链巡检，更新 status_code / last_check_at。适合放 crontab。
• 选项：
  • --limit=<n>：本次最多检测条数（0=全部，按最久未检测优先，默认 0）
  • --timeout=<s>：单条检测超时秒数（默认 8）
• 示例：
  • php think haonav:checklinks
  • php think haonav:checklinks --limit=50
  • crontab：0 3 * * * cd /path/to/site && php think haonav:checklinks >> runtime/haonav_check.log 2>&1

---

二、已定义但未注册命令（共 4 个）

以下命令类已实现 setName，但未写入 config/console.php，因此 php think list 不会列出、直接执行会报「命令不存在」。如需启用，把对应键值加入 config/console.php 的 commands 数组即可（注意 clear 重名冲突问题）。

命令名	类	文件	说明 / 参数
addon:make	ywxapp\command\addon\Addon	ywxapp/command/addon/Addon.php	统一脚手架/生成器（已通过 AppService 注册，替代原 addon:build/addon:clear/addon:controller/addon:model/addon:middleware/addon:validate/addon:event/addon:listener/addon:service/addon:subscribe）。用法 php think addon:make <插件名> -a <action>；-a 取 build/clear/controller/model/middleware/validate/event/listener/service/subscribe；生成器用 --name=<类>；controller 另支持 --api/--plain；clear 支持 -c/-l/-r。
app	ywxapp\command\AppCommand	ywxapp/command/AppCommand.php	应用命令统一入口（已通过 AppService 注册）。聚合 ywxapp/command/app/* 全部命令：build/clear/controller/model/event/listener/middleware/service/subscribe/validate。用法 php think app <子命令> [参数]；如 php think app controller app\index --api、php think app clear --cache。子命令专有选项（--api/--plain/--cache 等）透传至原命令类，未内联、不另立独立命令名。

说明：ywxapp/command/Create.php 中的 YMake 是抽象基类（abstract class YMake extends Command），本身不是可执行命令，供 ModelY 等生成类继承，不在清单内。

---

三、附：config/console.php 当前注册表（去重后）

'commands' => [
    "workerman:gateway"      => \ywxapp\command\GatewayWorker::class,
    "make:modely"            => \ywxapp\command\ModelY::class,
    "wxchat:server"          => \addon\wxchat\command\ChatServer::class,
    "install:copy"           => \app\command\InstallCopy::class,
    "mqttbroker:start"       => \addon\mqttbroker\command\MqttBroker::class,
    "mqttbroker:acltest"     => \addon\mqttbroker\command\TestAcl::class,
    "addon:manage"           => \ywxapp\command\addon\Manage::class,
    "addon:license-check"   => \ywxapp\command\AddonLicenseCheck::class,
    "haonav:checklinks"     => \addon\haonav\command\CheckLinks::class,
]

注：原文件中 install:copy 出现了两次（重复键），实际生效一份，建议清理重复项。