sakshamgorey/laravel-maintenance-signal

# Laravel 维护信号 为 Laravel 维护模式响应添加一个可配置的 HTTP header，以便 uptime 监控工具能够区分计划内维护和真正的故障停机。 ## 为什么需要它 普通的 `503 Service Unavailable` 状态是模糊的。外部监控工具无法确切知道应用是处于 Laravel 计划内维护模式，还是真的发生了故障。 不带 header 的 `503` 表示真正的故障停机或未知错误。 带有 header 的 `503` 表示计划内的 Laravel 维护。 该扩展包通过将 Laravel 的维护 middleware 替换为一个小型子类，仅在 Laravel 维护响应中添加该 header。 ## 安装 ``` composer require saksham/laravel-maintenance-signal ``` ## 发布配置 ``` php artisan vendor:publish --tag=maintenance-signal-config ``` ## 用法 ### Laravel 11、12 和 13 在 `bootstrap/app.php` 中，将 Laravel 的默认维护 middleware 替换为该扩展包的 middleware： ``` use Illuminate\Foundation\Application; use Illuminate\Foundation\Configuration\Middleware; use Saksham\MaintenanceSignal\Http\Middleware\PreventRequestsDuringMaintenance as MaintenanceSignalMiddleware; return Application::configure(basePath: dirname(__DIR__)) ->withRouting( web: __DIR__.'/../routes/web.php', commands: __DIR__.'/../routes/console.php', health: '/up', ) ->withMiddleware(function (Middleware $middleware): void { $middleware->use([ \Illuminate\Foundation\Http\Middleware\InvokeDeferredCallbacks::class, \Illuminate\Http\Middleware\TrustProxies::class, \Illuminate\Http\Middleware\HandleCors::class, MaintenanceSignalMiddleware::class, \Illuminate\Http\Middleware\ValidatePostSize::class, \Illuminate\Foundation\Http\Middleware\TrimStrings::class, \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class, ]); }) ->create(); ``` ### Laravel 10 在 `app/Http/Kernel.php` 中，将： ``` \Illuminate\Foundation\Http\Middleware\PreventRequestsDuringMaintenance::class, ``` 替换为： ``` \Saksham\MaintenanceSignal\Http\Middleware\PreventRequestsDuringMaintenance::class, ``` ## 配置 ``` MAINTENANCE_SIGNAL_ENABLED=true MAINTENANCE_SIGNAL_HEADER=X-Laravel-Maintenance-Mode MAINTENANCE_SIGNAL_VALUE=active ``` 默认配置： ``` return [ 'enabled' => env('MAINTENANCE_SIGNAL_ENABLED', true), 'header' => env('MAINTENANCE_SIGNAL_HEADER', 'X-Laravel-Maintenance-Mode'), 'value' => env('MAINTENANCE_SIGNAL_VALUE', 'active'), ]; ``` ## 响应示例 ``` php artisan down --retry=60 --refresh=15 ``` ``` HTTP/1.1 503 Service Unavailable Retry-After: 60 Refresh: 15 X-Laravel-Maintenance-Mode: active ``` ## Uptime 监控示例 通用逻辑： ``` if status == 503 and header X-Laravel-Maintenance-Mode == active: suppress alert else if status >= 500: alert ``` Better Stack： ``` Treat a 503 response with X-Laravel-Maintenance-Mode: active as planned maintenance. Alert on 5xx responses missing that header. ``` UptimeRobot： ``` Use a keyword/header monitor where available, or route webhook alerts through the generic logic above. ``` Pingdom： ``` Use a custom check or alert integration that inspects response headers before notifying. ``` AI 代理： ``` Agents that triage incidents can treat X-Laravel-Maintenance-Mode: active as planned maintenance instead of an unknown outage. ``` 通用 curl： ``` curl -I https://example.com ``` 预期结果： ``` HTTP/2 503 x-laravel-maintenance-mode: active ``` ## 安全说明 该 header 仅表示应用正有意处于维护模式。它不会泄露密钥、路径、异常详情或服务器内部信息。 ## 测试 ``` composer test ``` ## 许可证 MIT

标签：ffuf, Laravel, OpenVAS, PHP, Syscall, Web开发, 中间件, 系统可用性, 运维监控