Coolify 的 Laravel Actions 接线故障排查路由、队列、事件与命令的快速诊断指南【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolifyCoolify 的代码库大量使用lorisleiva/laravel-actions将业务用例封装为可在 HTTP、队列、事件、命令行四种入口复用的 Action 类。本篇技术指南以仓库内的排查参考文档 troubleshooting.md 为骨架逐条展开其快速检查项、五类常见故障模式与调试清单并结合 Coolify 的真实源码57 个AsActionAction、事件自动发现机制、控制台命令内核给出每一项故障的落点与验证方法。读完后你应能独立定位“Action 没被调用 / 调用参数不匹配 / 入口注册失效”这类接线问题并先于宽泛调试建立可复现的最小失败测试。适用范围什么时候需要这份排查文档原文档 troubleshooting.md 明确了自身的定位Scope当 Action 的接线wiring表现异常时使用该参考。它同时给出四条总纲Recap提供针对路由routing、队列queueing、事件events、命令command四类入口的快速分诊triage流程列出反复出现的故障模式并指明应首先检查的位置在宽泛调试之前优先用聚焦的测试复现问题将接线层诊断与领域逻辑验证分离开来。最后一条在 Coolify 中尤为重要Coolify 的 Action 约定是把领域逻辑集中在handle(...)把传输层/框架关注点留在适配方法asController、asJob、asListener、asCommand中见 SKILL.md 的 Project Conventions。因此排查时先问“入口到handle的路是否通”再问“handle内部的逻辑对不对”能避免在错误的层次上浪费时间。Coolify 中的 Actions 现状先确认前提再排查排查的第一步是确认运行前提。Coolify 在 composer.json 中声明了依赖lorisleiva/laravel-actions: ^2.10.2可以推断该版本区间对应 laravel-actions 2.x 的行为语义AsActiontrait、静态::run()/::dispatch()/::fake()等。仓库中 app/Actions/ 目录下现有 50 多个 Action 类按领域分子命名空间Application、Database、Server、Service、Proxy、Stripe、Shared、Development等。一个典型的真实 Action 是 RunCommand.php?php namespace App\Actions\Server; use App\Enums\ActivityTypes; use App\Models\Server; use Lorisleiva\Actions\Concerns\AsAction; class RunCommand { use AsAction; public function handle(Server $server, $command) { return remote_process(command: [$command], server: $server, ignore_errors: true, type: ActivityTypes::COMMAND-value); } }它只实现了handle(...)因此天然支持“作为对象运行”这一入口RunCommand::run($server, $cmd)、app(RunCommand::class)-handle(...)。只有当某个入口需要框架特定适配时才需要补as*方法。快速检查四项动手排查前的第一道闸门原文档 Fast checks 列出四项基础检查下面逐条结合 Coolify 源码说明“怎么查、查到什么”。1. Action 类是否使用了AsActionAsActiontrait 是静态调用入口::run()、::dispatch()、::fake()和__invoke可调用的来源。如果类没有use AsAction任何入口的调用都会退化为普通类静态调用直接报“方法不存在”。检查方式打开可疑的 Action 文件确认use Lorisleiva\Actions\Concerns\AsAction;与use AsAction;两处都齐全——前者是 import二者缺一即失效。可在全仓搜索比对仓库中所有正常工作的 Action如 app/Actions/Server/RunCommand.php、app/Actions/Database/StartDatabase.php都遵循这一写法。2. 命名空间与自动加载是否正确Coolify 采用 PSR-4 映射App\→app/。这意味着App\Actions\Server\RunCommand必须恰好位于app/Actions/Server/RunCommand.php文件内namespace App\Actions\Server;与路径逐段对应。常见失误是把文件移动后忘记同步命名空间或在子命名空间Application、Database、Server、Service、Proxy、Shared、Development中用错层级。验证方法很直接php artisan tinker中执行class_exists(\App\Actions\Server\RunCommand::class)或在测试环境中通过容器解析app(\App\Actions\Server\RunCommand::class)加载失败通常伴随 Composer 的 class-not-found 提示此时用composer dump-autoload刷新自动加载缓存往往就是修复动作。3. 入口接线路由 / 队列 / 事件 / 命令是否已注册原文档把“入口接线已注册”作为独立检查项因为handle(...)写得再对入口没挂上也不会执行。在 Coolify 中四个入口的注册位置各不相同这就是排查的分叉点路由routes/web.php、routes/api.php、routes/ai.php、routes/webhooks.php中是否存在指向该控制器/类的Route::注册队列dispatch/::dispatch()调用的队列与 config/queue.php 中 worker 实际消费的队列是否一致Coolify 使用 Horizon 管理队列相关配置见 config/horizon.php事件事件的监听映射是否会被加载见下文“Listener 映射未加载”一节Coolify 用的是自动发现模式与传统显式$listen映射不同命令app/Console/Kernel.php 中commands()方法通过$this-load(__DIR__./Commands);批量加载 app/Console/Commands/ 下的 35 个命令另外require base_path(routes/console.php)注册路由风格的 artisan 命令——命令必须位于这些被加载的位置内才会出现。4. 方法签名与参数类型是否匹配调用方期望handle(...)的签名即契约。以 RunCommand.php 为例handle(Server $server, $command)的第一个参数是 Eloquent 模型App\Models\Server调用方若传入关联对象或 ID会直接得到类型错误。排查时做两件事对比调用方实际传参的类型/顺序与签名若 Action 通过容器解析依赖如app(SomeAction::class)-handle(...)确认签名中被注入的类在容器中有绑定、没有循环依赖。Coolify 的 Action 普遍依赖Server、Application等模型与 helper 函数如remote_process签名层面的依赖注入异常通常表现为容器解析失败而非业务错误。五类反复出现的故障模式与首查位置原文档 Failure patterns 一节列出五类“反复出现”recurring的失败模式。下面按原文顺序逐条展开并给出在 Coolify 仓库中对应的具体核查位置。模式一控制器路由指向了错误的类当路由声明指向了类名拼错的类、错误的命名空间或指向了一个根本不是 invokable 控制器/Action 的类时请求要么 404要么报Class ... not found。首查位置对应路由文件routes/web.php、routes/api.php 等中的Route::调用确认控制器类名与实际文件一一对应。Coolify 的 HTTP 层以标准 Controller 为主app/Http/Controllers/下 48 个控制器Action 主要承担其后置业务编排如果你的场景是把 Action 类直接挂到路由上invokable 风格要额外确认该类存在__invoke——缺失时 Laravel 的RouteAction::makeInvokable会抛出Invalid route action异常该约束见 controller.md 的说明。模式二队列 worker 与配置不匹配dispatch(...)只负责把任务放入指定队列若 worker 没有消费该队列任务会“静默”积压——这是原文档将“Queue worker/config mismatch”单列为反复故障模式的原因。首查位置config/queue.php 中默认连接与队列名以及任务dispatch时-onQueue()指定的队列是否在其中Horizon 的实际消费范围config/horizon.phpworker 进程是否在运行、消费的是哪个连接。Coolify 的调度作业如 app/Console/Kernel.php 中每分钟的ServerManagerJob、ScheduledJobManager依赖队列链路畅通积压时仓库还提供了cleanup:redis命令清理卡住的 Horizon 作业与WithoutOverlapping锁实现见 app/Console/Commands/CleanupRedis.php这是“队列不消费”类故障的辅助诊断手段运行php artisan cleanup:redis --dry-run可先查看有多少积压键。模式三事件监听器映射未被加载原文档写的是“Listener mapping not loaded”。在 Coolify 中这一模式有一个仓库层面的特殊事实值得单独讲清app/Providers/EventServiceProvider.php 的显式$listen数组只注册了 Socialite 相关监听而方法public function shouldDiscoverEvents(): bool { return true; }返回true。也就是说Coolify 依赖Laravel 事件自动发现扫描监听器类上的handle方法及其参数类型来建立事件→监听器映射而不是逐条手写映射。由此推导出排查要点若你的监听器依赖自动发现检查其handle(SomeEvent $event)的参数类型是否与 app/Events/ 下的事件类如ApplicationStatusChanged、ServiceStatusChanged等完全一致类名、命名空间事件类被移动或改名后自动发现的映射会悄然失效且无任何报错——这正是“映射未加载”的典型表现事件/监听器代码变更后event.cache:forget或缓存清理往往是让发现机制重新生效的必要步骤。模式四命令签名不匹配当 artisan 命令的$signature与调用方式选项名、位置参数、默认值不一致时会得到 “The command is not defined” 或选项未识别的错误。Coolify 中的实例是 app/Console/Commands/CleanupRedis.phpprotected $signature cleanup:redis {--dry-run : Show what would be deleted without actually deleting} {--skip-overlapping : Skip overlapping queue cleanup} {--clear-locks : Clear stale WithoutOverlapping locks} {--restart : Aggressive cleanup mode for system restart (marks all processing jobs as failed)};排查时逐字符核对$signature与调度处的写法。Coolify 的调度app/Console/Kernel.php 的schedule()中多处通过$this-scheduleInstance-command(cleanup:redis --clear-locks)这类字符串形式引用命令名与选项——调度字符串里的命令名、选项名必须与$signature严格一致否则调度触发时命令解析失败。模式五命令未注册到控制台内核签名正确但命令仍然“不存在”时通常是因为该命令类没有被内核加载。Coolify 的加载机制在 app/Console/Kernel.php 的commands()中protected function commands(): void { $this-load(__DIR__./Commands); require base_path(routes/console.php); }因此一个 artisan 命令只有在app/Console/Commands/目录下或经由routes/console.php注册才会出现在php artisan list中。把新命令放在别处、或类名不符合加载约定都会导致“命令未注册”。验证方法php artisan list检索命令名找不到即回到本节核对加载路径。调试清单先用聚焦测试建立最小复现原文档 Debug checklist 的三条原则在 Coolify 的测试体系Pest 框架tests/Feature/ 520 余个功能测试、tests/Unit/ 298 个单元测试执行配置见 phpunit.xml下可以落地为具体动作。1. 用聚焦的失败测试复现问题原文档强调“Reproduce with a focused failing test”——在宽泛调试之前先写一个能稳定失败的最小测试。对 Action 而言最小复现通常是直接调用handle(...)it(runs the command on the server, function () { $server Server::factory()-create(); $result RunCommand::run($server, echo hello); expect($result)-toBeArray(); });Coolify 的 app/Jobs/ 下有 56 个队列 Job 与 35 个控制台命令tests/Feature/ 中已存在大量围绕部署队列、服务状态、命令执行的既有用例可作模板。跑php artisan test --compact --filterTestName只跑相关子集避免全量测试拖慢反馈循环。2. 先验证接线层再验证领域行为这是原文档 Recap 中“separates wiring diagnostics from domain logic verification”的操作化接线层故障路由没挂上、worker 没消费、监听映射丢了、命令没加载的特征是目标代码根本没被执行领域行为故障的特征是代码执行了但结果不对。区分手段在handle(...)入口加一条日志/断点或直接跑一个“只证明能被调用”的测试。能调通 → 故障在领域逻辑继续往内查调不通 → 回到前文的五类故障模式逐项核对接线。3. 用 fakes/spies 隔离依赖原文档建议“Isolate dependencies with fakes/spies where appropriate”。laravel-actions 的::fake()家族mock()、spy()、shouldRun()、shouldNotRun()、allowToRun()、clearFake()正是为此设计Coolify 技能文档 SKILL.md 与 testing-fakes.md 有完整方法表。接线测试的典型形态是“fake 下游 Action断言上游是否正确触发”it(dispatches the downstream action, function () { RunCommand::shouldRun()-once(); // 触发上游编排逻辑…… });注意两个实践要点来自 SKILL.md 的 Practical defaultsfake 只作用于被测边界不要把整条链路都替换掉否则测不到接线若 fake 可能泄漏到后续测试在清理阶段调用clearFake()。一张排查流程速查表把原文档三节内容Fast checks → Failure patterns → Debug checklist串起来完整的诊断顺序是步骤检查内容Coolify 首查位置1类是否use AsAction对应 Action 文件如 app/Actions/Server/RunCommand.php2命名空间与自动加载文件路径与namespace逐段比对composer dump-autoload3路由是否指向正确类routes/web.php、routes/api.php、routes/webhooks.php4队列与 worker 是否匹配config/queue.php、config/horizon.phpcleanup:redis --dry-run5事件监听映射是否加载app/Providers/EventServiceProvider.phpshouldDiscoverEvents自动发现 参数类型比对6命令签名是否一致命令类的$signature如 app/Console/Commands/CleanupRedis.php与调度字符串7命令是否被内核注册app/Console/Kernel.php 的commands()php artisan list8参数签名是否匹配调用方handle(...)签名 vs 调用处实参类型/顺序9聚焦失败测试复现Pest 子集php artisan test --filterName10接线层与领域层分离验证 fakes::fake()/shouldRun()断言上游是否触达handle需要强调的适用前提本文基于当前仓库状态——lorisleiva/laravel-actions ^2.10.22.x 语义、Laravel 事件自动发现开启、artisan 命令由内核目录批量加载。若 Coolify 后续升级框架版本或关闭事件自动发现shouldDiscoverEvents返回false并要求显式$listen映射第五节模式三的排查方式需要相应调整。小结troubleshooting.md 给出的是一套“先分诊、后深挖”的纪律四项快速检查排除低级错误五类故障模式指引首查位置路由文件、队列/Horizon 配置、事件自动发现机制、$signature、内核加载路径再用聚焦测试 fake 隔离把故障钉死在接线层或领域层之一。对 Coolify 这样的多入口HTTP 队列 事件 命令行 调度Laravel 应用而言把“接线诊断”与“领域逻辑验证”分成两个互不混叠的步骤是缩短 Action 类故障定位时间的关键。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Coolify 的 Laravel Actions 接线故障排查：路由、队列、事件与命令的快速诊断指南
Coolify 的 Laravel Actions 接线故障排查路由、队列、事件与命令的快速诊断指南【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolifyCoolify 的代码库大量使用lorisleiva/laravel-actions将业务用例封装为可在 HTTP、队列、事件、命令行四种入口复用的 Action 类。本篇技术指南以仓库内的排查参考文档 troubleshooting.md 为骨架逐条展开其快速检查项、五类常见故障模式与调试清单并结合 Coolify 的真实源码57 个AsActionAction、事件自动发现机制、控制台命令内核给出每一项故障的落点与验证方法。读完后你应能独立定位“Action 没被调用 / 调用参数不匹配 / 入口注册失效”这类接线问题并先于宽泛调试建立可复现的最小失败测试。适用范围什么时候需要这份排查文档原文档 troubleshooting.md 明确了自身的定位Scope当 Action 的接线wiring表现异常时使用该参考。它同时给出四条总纲Recap提供针对路由routing、队列queueing、事件events、命令command四类入口的快速分诊triage流程列出反复出现的故障模式并指明应首先检查的位置在宽泛调试之前优先用聚焦的测试复现问题将接线层诊断与领域逻辑验证分离开来。最后一条在 Coolify 中尤为重要Coolify 的 Action 约定是把领域逻辑集中在handle(...)把传输层/框架关注点留在适配方法asController、asJob、asListener、asCommand中见 SKILL.md 的 Project Conventions。因此排查时先问“入口到handle的路是否通”再问“handle内部的逻辑对不对”能避免在错误的层次上浪费时间。Coolify 中的 Actions 现状先确认前提再排查排查的第一步是确认运行前提。Coolify 在 composer.json 中声明了依赖lorisleiva/laravel-actions: ^2.10.2可以推断该版本区间对应 laravel-actions 2.x 的行为语义AsActiontrait、静态::run()/::dispatch()/::fake()等。仓库中 app/Actions/ 目录下现有 50 多个 Action 类按领域分子命名空间Application、Database、Server、Service、Proxy、Stripe、Shared、Development等。一个典型的真实 Action 是 RunCommand.php?php namespace App\Actions\Server; use App\Enums\ActivityTypes; use App\Models\Server; use Lorisleiva\Actions\Concerns\AsAction; class RunCommand { use AsAction; public function handle(Server $server, $command) { return remote_process(command: [$command], server: $server, ignore_errors: true, type: ActivityTypes::COMMAND-value); } }它只实现了handle(...)因此天然支持“作为对象运行”这一入口RunCommand::run($server, $cmd)、app(RunCommand::class)-handle(...)。只有当某个入口需要框架特定适配时才需要补as*方法。快速检查四项动手排查前的第一道闸门原文档 Fast checks 列出四项基础检查下面逐条结合 Coolify 源码说明“怎么查、查到什么”。1. Action 类是否使用了AsActionAsActiontrait 是静态调用入口::run()、::dispatch()、::fake()和__invoke可调用的来源。如果类没有use AsAction任何入口的调用都会退化为普通类静态调用直接报“方法不存在”。检查方式打开可疑的 Action 文件确认use Lorisleiva\Actions\Concerns\AsAction;与use AsAction;两处都齐全——前者是 import二者缺一即失效。可在全仓搜索比对仓库中所有正常工作的 Action如 app/Actions/Server/RunCommand.php、app/Actions/Database/StartDatabase.php都遵循这一写法。2. 命名空间与自动加载是否正确Coolify 采用 PSR-4 映射App\→app/。这意味着App\Actions\Server\RunCommand必须恰好位于app/Actions/Server/RunCommand.php文件内namespace App\Actions\Server;与路径逐段对应。常见失误是把文件移动后忘记同步命名空间或在子命名空间Application、Database、Server、Service、Proxy、Shared、Development中用错层级。验证方法很直接php artisan tinker中执行class_exists(\App\Actions\Server\RunCommand::class)或在测试环境中通过容器解析app(\App\Actions\Server\RunCommand::class)加载失败通常伴随 Composer 的 class-not-found 提示此时用composer dump-autoload刷新自动加载缓存往往就是修复动作。3. 入口接线路由 / 队列 / 事件 / 命令是否已注册原文档把“入口接线已注册”作为独立检查项因为handle(...)写得再对入口没挂上也不会执行。在 Coolify 中四个入口的注册位置各不相同这就是排查的分叉点路由routes/web.php、routes/api.php、routes/ai.php、routes/webhooks.php中是否存在指向该控制器/类的Route::注册队列dispatch/::dispatch()调用的队列与 config/queue.php 中 worker 实际消费的队列是否一致Coolify 使用 Horizon 管理队列相关配置见 config/horizon.php事件事件的监听映射是否会被加载见下文“Listener 映射未加载”一节Coolify 用的是自动发现模式与传统显式$listen映射不同命令app/Console/Kernel.php 中commands()方法通过$this-load(__DIR__./Commands);批量加载 app/Console/Commands/ 下的 35 个命令另外require base_path(routes/console.php)注册路由风格的 artisan 命令——命令必须位于这些被加载的位置内才会出现。4. 方法签名与参数类型是否匹配调用方期望handle(...)的签名即契约。以 RunCommand.php 为例handle(Server $server, $command)的第一个参数是 Eloquent 模型App\Models\Server调用方若传入关联对象或 ID会直接得到类型错误。排查时做两件事对比调用方实际传参的类型/顺序与签名若 Action 通过容器解析依赖如app(SomeAction::class)-handle(...)确认签名中被注入的类在容器中有绑定、没有循环依赖。Coolify 的 Action 普遍依赖Server、Application等模型与 helper 函数如remote_process签名层面的依赖注入异常通常表现为容器解析失败而非业务错误。五类反复出现的故障模式与首查位置原文档 Failure patterns 一节列出五类“反复出现”recurring的失败模式。下面按原文顺序逐条展开并给出在 Coolify 仓库中对应的具体核查位置。模式一控制器路由指向了错误的类当路由声明指向了类名拼错的类、错误的命名空间或指向了一个根本不是 invokable 控制器/Action 的类时请求要么 404要么报Class ... not found。首查位置对应路由文件routes/web.php、routes/api.php 等中的Route::调用确认控制器类名与实际文件一一对应。Coolify 的 HTTP 层以标准 Controller 为主app/Http/Controllers/下 48 个控制器Action 主要承担其后置业务编排如果你的场景是把 Action 类直接挂到路由上invokable 风格要额外确认该类存在__invoke——缺失时 Laravel 的RouteAction::makeInvokable会抛出Invalid route action异常该约束见 controller.md 的说明。模式二队列 worker 与配置不匹配dispatch(...)只负责把任务放入指定队列若 worker 没有消费该队列任务会“静默”积压——这是原文档将“Queue worker/config mismatch”单列为反复故障模式的原因。首查位置config/queue.php 中默认连接与队列名以及任务dispatch时-onQueue()指定的队列是否在其中Horizon 的实际消费范围config/horizon.phpworker 进程是否在运行、消费的是哪个连接。Coolify 的调度作业如 app/Console/Kernel.php 中每分钟的ServerManagerJob、ScheduledJobManager依赖队列链路畅通积压时仓库还提供了cleanup:redis命令清理卡住的 Horizon 作业与WithoutOverlapping锁实现见 app/Console/Commands/CleanupRedis.php这是“队列不消费”类故障的辅助诊断手段运行php artisan cleanup:redis --dry-run可先查看有多少积压键。模式三事件监听器映射未被加载原文档写的是“Listener mapping not loaded”。在 Coolify 中这一模式有一个仓库层面的特殊事实值得单独讲清app/Providers/EventServiceProvider.php 的显式$listen数组只注册了 Socialite 相关监听而方法public function shouldDiscoverEvents(): bool { return true; }返回true。也就是说Coolify 依赖Laravel 事件自动发现扫描监听器类上的handle方法及其参数类型来建立事件→监听器映射而不是逐条手写映射。由此推导出排查要点若你的监听器依赖自动发现检查其handle(SomeEvent $event)的参数类型是否与 app/Events/ 下的事件类如ApplicationStatusChanged、ServiceStatusChanged等完全一致类名、命名空间事件类被移动或改名后自动发现的映射会悄然失效且无任何报错——这正是“映射未加载”的典型表现事件/监听器代码变更后event.cache:forget或缓存清理往往是让发现机制重新生效的必要步骤。模式四命令签名不匹配当 artisan 命令的$signature与调用方式选项名、位置参数、默认值不一致时会得到 “The command is not defined” 或选项未识别的错误。Coolify 中的实例是 app/Console/Commands/CleanupRedis.phpprotected $signature cleanup:redis {--dry-run : Show what would be deleted without actually deleting} {--skip-overlapping : Skip overlapping queue cleanup} {--clear-locks : Clear stale WithoutOverlapping locks} {--restart : Aggressive cleanup mode for system restart (marks all processing jobs as failed)};排查时逐字符核对$signature与调度处的写法。Coolify 的调度app/Console/Kernel.php 的schedule()中多处通过$this-scheduleInstance-command(cleanup:redis --clear-locks)这类字符串形式引用命令名与选项——调度字符串里的命令名、选项名必须与$signature严格一致否则调度触发时命令解析失败。模式五命令未注册到控制台内核签名正确但命令仍然“不存在”时通常是因为该命令类没有被内核加载。Coolify 的加载机制在 app/Console/Kernel.php 的commands()中protected function commands(): void { $this-load(__DIR__./Commands); require base_path(routes/console.php); }因此一个 artisan 命令只有在app/Console/Commands/目录下或经由routes/console.php注册才会出现在php artisan list中。把新命令放在别处、或类名不符合加载约定都会导致“命令未注册”。验证方法php artisan list检索命令名找不到即回到本节核对加载路径。调试清单先用聚焦测试建立最小复现原文档 Debug checklist 的三条原则在 Coolify 的测试体系Pest 框架tests/Feature/ 520 余个功能测试、tests/Unit/ 298 个单元测试执行配置见 phpunit.xml下可以落地为具体动作。1. 用聚焦的失败测试复现问题原文档强调“Reproduce with a focused failing test”——在宽泛调试之前先写一个能稳定失败的最小测试。对 Action 而言最小复现通常是直接调用handle(...)it(runs the command on the server, function () { $server Server::factory()-create(); $result RunCommand::run($server, echo hello); expect($result)-toBeArray(); });Coolify 的 app/Jobs/ 下有 56 个队列 Job 与 35 个控制台命令tests/Feature/ 中已存在大量围绕部署队列、服务状态、命令执行的既有用例可作模板。跑php artisan test --compact --filterTestName只跑相关子集避免全量测试拖慢反馈循环。2. 先验证接线层再验证领域行为这是原文档 Recap 中“separates wiring diagnostics from domain logic verification”的操作化接线层故障路由没挂上、worker 没消费、监听映射丢了、命令没加载的特征是目标代码根本没被执行领域行为故障的特征是代码执行了但结果不对。区分手段在handle(...)入口加一条日志/断点或直接跑一个“只证明能被调用”的测试。能调通 → 故障在领域逻辑继续往内查调不通 → 回到前文的五类故障模式逐项核对接线。3. 用 fakes/spies 隔离依赖原文档建议“Isolate dependencies with fakes/spies where appropriate”。laravel-actions 的::fake()家族mock()、spy()、shouldRun()、shouldNotRun()、allowToRun()、clearFake()正是为此设计Coolify 技能文档 SKILL.md 与 testing-fakes.md 有完整方法表。接线测试的典型形态是“fake 下游 Action断言上游是否正确触发”it(dispatches the downstream action, function () { RunCommand::shouldRun()-once(); // 触发上游编排逻辑…… });注意两个实践要点来自 SKILL.md 的 Practical defaultsfake 只作用于被测边界不要把整条链路都替换掉否则测不到接线若 fake 可能泄漏到后续测试在清理阶段调用clearFake()。一张排查流程速查表把原文档三节内容Fast checks → Failure patterns → Debug checklist串起来完整的诊断顺序是步骤检查内容Coolify 首查位置1类是否use AsAction对应 Action 文件如 app/Actions/Server/RunCommand.php2命名空间与自动加载文件路径与namespace逐段比对composer dump-autoload3路由是否指向正确类routes/web.php、routes/api.php、routes/webhooks.php4队列与 worker 是否匹配config/queue.php、config/horizon.phpcleanup:redis --dry-run5事件监听映射是否加载app/Providers/EventServiceProvider.phpshouldDiscoverEvents自动发现 参数类型比对6命令签名是否一致命令类的$signature如 app/Console/Commands/CleanupRedis.php与调度字符串7命令是否被内核注册app/Console/Kernel.php 的commands()php artisan list8参数签名是否匹配调用方handle(...)签名 vs 调用处实参类型/顺序9聚焦失败测试复现Pest 子集php artisan test --filterName10接线层与领域层分离验证 fakes::fake()/shouldRun()断言上游是否触达handle需要强调的适用前提本文基于当前仓库状态——lorisleiva/laravel-actions ^2.10.22.x 语义、Laravel 事件自动发现开启、artisan 命令由内核目录批量加载。若 Coolify 后续升级框架版本或关闭事件自动发现shouldDiscoverEvents返回false并要求显式$listen映射第五节模式三的排查方式需要相应调整。小结troubleshooting.md 给出的是一套“先分诊、后深挖”的纪律四项快速检查排除低级错误五类故障模式指引首查位置路由文件、队列/Horizon 配置、事件自动发现机制、$signature、内核加载路径再用聚焦测试 fake 隔离把故障钉死在接线层或领域层之一。对 Coolify 这样的多入口HTTP 队列 事件 命令行 调度Laravel 应用而言把“接线诊断”与“领域逻辑验证”分成两个互不混叠的步骤是缩短 Action 类故障定位时间的关键。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考