Coolify 中的 Laravel Nightwatch 观测配置实战采样、过滤与脱敏三阶段策略【免费下载链接】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本文围绕 Coolify 仓库中的 Nightwatch 配置技能文档SKILL.md展开系统讲解 Laravel Nightwatch 的三阶段事件采集模型——采样Sampling、过滤Filtering、脱敏Redaction并覆盖全部九种事件类型的配置参数、环境变量与代码示例。读完后你将能够在生产环境按流量规模调整采样率、精准过滤噪音事件、对 PII 与凭据做脱敏并结合 Coolify 仓库中 s6-overlay 的 agent 部署方式把 Nightwatch 完整地跑起来。Nightwatch 是什么Coolify 如何引入它Laravel Nightwatch 是 Laravel 生态中的开发环境可观测性工具用于采集请求、命令、数据库查询、缓存操作、队列任务、邮件、通知、出站 HTTP 请求和异常等运行时事件。Coolify 在其 Laravel 12 应用中引入了该包composer.json 中声明依赖为laravel/nightwatch: ^1.28.6AGENTS.md 的生态清单中确认laravel/nightwatch (NIGHTWATCH) - v1运行环境为 PHP 8.5boost.json 将configure-nightwatch注册为项目的 Agent 技能之一同时nightwatch_mcp: false即未启用其 MCP 扩展说明该配置知识以技能文档形式随仓库分发技能文档自身SKILL.md也声明Nightwatch 官方文档是所有配置项的最终权威来源本文档提供的是实践指导与常见模式具体环境变量和 API 行为以官方文档为准。事件采集的三阶段模型Nightwatch 对事件的处理分为三个明确阶段理解这个模型是后面所有配置的前提采样Sampling——决定哪些入口请求、命令、定时任务触发完整 trace 采集。采样命中后该入口产生的所有关联事件都会被记录。过滤Filtering——在采样之后把特定事件查询、缓存、邮件等从采集中剔除用于降噪和节省配额。脱敏Redaction——事件保留但对其内容做修改移除或混淆敏感信息。文档给出的数据流如下Request/Command/Scheduled Task | v [Sampling?] ----NO---- Drop entire trace | YES v Events generated | v [Filtering?] ----YES--- Drop specific event | NO v [Redaction] ---------- Store modified data三个阶段的关键区别在于作用粒度采样是全有或全无miss 掉就丢掉整条 trace过滤是逐事件丢弃脱敏则是事件保留、内容净化。采样配置Sampling采样决定哪些入口触发完整 trace 采集。技能文档建议生产环境请求采样从0.110%起步再根据流量与需求调整。全局采样率环境变量# 默认100% 采样所有请求/命令都被采集 NIGHTWATCH_REQUEST_SAMPLE_RATE0.1 # 推荐10% 的请求 NIGHTWATCH_COMMAND_SAMPLE_RATE1.0 # 采集全部命令 NIGHTWATCH_EXCEPTION_SAMPLE_RATE1.0 # 异常永远采集三个采样率相互独立请求、命令、异常各自一个开关其中异常建议保持1.0保证排查问题时信息不缺失。路由级采样Route-Based Sampling通过Sample中间件对特定路由应用不同采样率use Illuminate\Support\Facades\Route; use Laravel\Nightwatch\Http\Middleware\Sample; // 管理后台路由 100% 采样 Route::middleware(Sample::rate(1.0))-prefix(admin)-group(function () { // All admin routes sampled fully }); // API 路由 5% 采样 Route::middleware(Sample::rate(0.05))-prefix(api)-group(function () { // API routes sampled sparingly }); // 关键端点永远采样 Route::post(/checkout, [CheckoutController::class, process]) -middleware(Sample::always()); // 健康检查永不采样 Route::get(/health, [HealthController::class, check]) -middleware(Sample::never());Sample::rate()、Sample::always()、Sample::never()三个静态方法覆盖了按比例 / 全量 / 排除三种典型诉求。Coolify 自身的路由文件routes/web.php、routes/api.php中目前未使用这些中间件上述示例是文档给出的标准用法。未匹配路由的采样404 与爬虫流量往往量很大且价值低建议用 fallback 路由单独压低采样率Route::fallback(fn () abort(404)) -middleware(Sample::rate(0.01)); // 未匹配路由只采样 1%动态采样基于运行时条件用户角色、请求属性动态决定采样use Closure; use Illuminate\Http\Request; use Laravel\Nightwatch\Facades\Nightwatch; class SampleAdminRequests { public function handle(Request $request, Closure $next) { if ($request-user()?-isAdmin()) { Nightwatch::sample(); // 管理用户的请求永远采样 } return $next($request); } }即在前置中间件里调用Nightwatch::sample()强制本次请求进入采样实现按身份而非按路由的观测策略。命令采样与排除特定命令通过监听CommandStarting事件排除不需要观测的命令如schedule:finish、horizon:snapshot这类框架周期性任务use Illuminate\Console\Events\CommandStarting; use Illuminate\Support\Facades\Event; use Laravel\Nightwatch\Facades\Nightwatch; public function boot(): void { Event::listen(function (CommandStarting $event) { if (in_array($event-command, [schedule:finish, horizon:snapshot])) { Nightwatch::dontSample(); } }); }Vendor 命令Nightwatch 默认忽略框架/内部vendor命令以减少噪音。如果确实需要采集可显式开启Nightwatch::captureDefaultVendorCommands();过滤配置Filtering过滤用于在采样命中之后剔除特定事件降低噪音与配额消耗。每类事件都提供一刀切环境变量和程序化回调两种手段。数据库查询全部禁用查询采集NIGHTWATCH_IGNORE_QUERIEStrue按 SQL 模式过滤特定查询use Laravel\Nightwatch\Facades\Nightwatch; use Laravel\Nightwatch\Records\Query; public function boot(): void { // 过滤 job 表查询PostgreSQL 风格 Nightwatch::rejectQueries(function (Query $query) { return str_contains($query-sql, into jobs); }); // 过滤缓存表查询MySQL 风格 Nightwatch::rejectQueries(function (Query $query) { return str_contains($query-sql, from cache) || str_contains($query-sql, into cache); }); }回调接收Laravel\Nightwatch\Records\Query记录判断其sql属性即可。缓存事件全部禁用NIGHTWATCH_IGNORE_CACHE_EVENTStrue按键模式过滤支持精确匹配与正则以/包裹的字符串视为正则Nightwatch::rejectCacheKeys([ my-app:users, // 精确匹配 /^my-app:posts:/, // 正则以 my-app:posts: 开头 /^[a-zA-Z0-9]{40}$/, // 正则会话 ID 形态 ]);或用回调对完整缓存事件做判断use Laravel\Nightwatch\Records\CacheEvent; Nightwatch::rejectCacheEvents(function (CacheEvent $cacheEvent) { return str_starts_with($cacheEvent-key, temp:); });邮件事件全部禁用NIGHTWATCH_IGNORE_MAILtrue按主题过滤特定邮件use Laravel\Nightwatch\Records\Mail; Nightwatch::rejectMail(function (Mail $mail) { return str_contains($mail-subject, Newsletter); });通知事件全部禁用NIGHTWATCH_IGNORE_NOTIFICATIONStrue按通知渠道过滤例如只排除 database 渠道的站内通知use Laravel\Nightwatch\Records\Notification; Nightwatch::rejectNotifications(function (Notification $notification) { return $notification-channel database; });出站 HTTP 请求全部禁用NIGHTWATCH_IGNORE_OUTGOING_REQUESTStrue按目标 URL 过滤例如排除对 analytics 服务的调用use Laravel\Nightwatch\Records\OutgoingRequest; Nightwatch::rejectOutgoingRequests(function (OutgoingRequest $request) { return str_contains($request-url, analytics.example.com); });队列任务按任务类名过滤特定 Jobuse Laravel\Nightwatch\Records\QueuedJob; Nightwatch::rejectQueuedJobs(function (QueuedJob $job) { return $job-name App\Jobs\LowPriorityJob; });解耦 Job 采样Decoupling Job Sampling队列任务天然运行在与产生它的请求不同的进程/上下文中可以把 Job 的采样率与父上下文解耦通过Queue::before钩子独立设定use Illuminate\Support\Facades\Queue; public function boot(): void { Queue::before(fn () Nightwatch::sample(rate: 0.5)); }即每次 Job 执行前以 50% 概率采样不受原请求是否被采样的影响。对 Coolify 这类大量使用队列的系统其 app/Jobs 下定义了上百个 Job该机制可以让后台任务链路的观测覆盖不再依赖入口请求的采样命中。脱敏配置Redaction脱敏与过滤的本质区别事件仍然被保留trace 里能看到发生了什么但敏感内容被替换或混淆从而兼顾可观测性与隐私。请求脱敏请求头默认自动脱敏Authorization、Cookie、X-XSRF-TOKEN可用环境变量自定义脱敏头清单# 自定义需要脱敏的请求头 NIGHTWATCH_REDACT_HEADERSAuthorization,Cookie,Proxy-Authorization,X-API-Key请求体payload采集默认关闭显式开启后需同步配置脱敏字段# 开启 payload 采集 NIGHTWATCH_CAPTURE_REQUEST_PAYLOADtrue # 自定义需脱敏的 payload 字段 NIGHTWATCH_REDACT_PAYLOAD_FIELDSpassword,password_confirmation,ssn,credit_card程序化脱敏可以处理 URL、IP 等结构化属性use Laravel\Nightwatch\Facades\Nightwatch; use Laravel\Nightwatch\Records\Request; Nightwatch::redactRequests(function (Request $request) { $request-url str_replace(secret, ***, $request-url); $request-ip preg_replace(/\d$/, ***, $request-ip); });其他事件类型的脱敏查询改写 SQL 文本use Laravel\Nightwatch\Records\Query; Nightwatch::redactQueries(function (Query $query) { $query-sql str_replace(secret_token, ***, $query-sql); });缓存改写键名use Laravel\Nightwatch\Records\CacheEvent; Nightwatch::redactCacheEvents(function (CacheEvent $cacheEvent) { $cacheEvent-key str_replace(user:, user:***:, $cacheEvent-key); });命令掩盖命令行中的敏感参数use Laravel\Nightwatch\Records\Command; Nightwatch::redactCommands(function (Command $command) { $command-command preg_replace(/--password\S/, --password***, $command-command); });异常净化异常消息use Laravel\Nightwatch\Records\Exception; Nightwatch::redactExceptions(function (Exception $exception) { $exception-message str_replace(secret, ***, $exception-message); });邮件改写主题use Laravel\Nightwatch\Records\Mail; Nightwatch::redactMail(function (Mail $mail) { $mail-subject str_replace(Invoice #, Invoice ***, $mail-subject); });出站请求净化 URL 中的查询参数use Laravel\Nightwatch\Records\OutgoingRequest; Nightwatch::redactOutgoingRequests(function (OutgoingRequest $outgoingRequest) { $outgoingRequest-url preg_replace(/api_key\w/, api_key***, $outgoingRequest-url); });各事件类型配置速查技能配套的速查表reference.md汇总了每类事件的采样、过滤、脱敏三个维度的可用手段事件类型采样过滤脱敏RequestsNIGHTWATCH_REQUEST_SAMPLE_RATE、路由中间件不适用请求头、payload、URL、IPCommandsNIGHTWATCH_COMMAND_SAMPLE_RATE、事件监听不适用命令参数Queries随父上下文rejectQueries()、NIGHTWATCH_IGNORE_QUERIESSQL 语句Cache随父上下文rejectCacheKeys()、rejectCacheEvents()、NIGHTWATCH_IGNORE_CACHE_EVENTS缓存键Jobs随父上下文、Queue::beforerejectQueuedJobs()不适用Mail随父上下文rejectMail()、NIGHTWATCH_IGNORE_MAIL邮件主题Notifications随父上下文rejectNotifications()、NIGHTWATCH_IGNORE_NOTIFICATIONS不适用Outgoing Requests随父上下文rejectOutgoingRequests()、NIGHTWATCH_IGNORE_OUTGOING_REQUESTSURLExceptionsNIGHTWATCH_EXCEPTION_SAMPLE_RATE不适用异常消息从这张表可以读出三阶段模型的完整映射只有入口型事件请求、命令、异常拥有独立采样开关其余派生事件查询、缓存、邮件等都随父上下文——父 trace 被采样才谈得上采集它们因此压低请求采样率是控制数据总量的第一杠杆过滤 脱敏则是精细化的第二、三杠杆。生产环境预设方案reference.md 给出三套可直接套用的生产预设高流量应用保守采样 激进的噪音过滤# 保守采样 NIGHTWATCH_REQUEST_SAMPLE_RATE0.01 # 1% 请求 NIGHTWATCH_COMMAND_SAMPLE_RATE0.1 # 10% 命令 NIGHTWATCH_EXCEPTION_SAMPLE_RATE1.0 # 异常永远采集 # 过滤噪音事件 NIGHTWATCH_IGNORE_CACHE_EVENTStrue NIGHTWATCH_IGNORE_QUERIEStrue # 或改用程序化方式过滤特定查询隐私优先应用禁用敏感数据 强化头脱敏# 禁用敏感数据采集 NIGHTWATCH_CAPTURE_REQUEST_PAYLOADfalse NIGHTWATCH_REDACT_HEADERSAuthorization,Cookie,Proxy-Authorization,X-XSRF-TOKEN # 或在 AppServiceProvider 中做程序化脱敏均衡配置推荐起点# 采样率 NIGHTWATCH_REQUEST_SAMPLE_RATE0.1 NIGHTWATCH_COMMAND_SAMPLE_RATE1.0 NIGHTWATCH_EXCEPTION_SAMPLE_RATE1.0 # 程序化过滤明显的噪音事件 # 按需对 PII 做脱敏配置完成后的验证清单按 reference.md 的清单逐项确认采样率与流量规模匹配高流量用 0.01常规 0.1 起步噪音事件已过滤缓存事件、特定查询表敏感数据已脱敏PII、token、凭据异常保持 100% 采集保障排障能力在开发环境用NIGHTWATCH_REQUEST_SAMPLE_RATE1.0验证全量链路可用在 Nightwatch 面板持续观察事件配额用量。常见组合模式reference.md 还沉淀了三个高频组合场景1. 过滤健康检查 压低采样——探针类端点既无观测价值又高频Route::get(/health, fn() [status ok]) -middleware(Sample::never());2. 排除内部观测框架自身的查询——避免观测工具观测自己造成的递归噪音例如 telescope、pulse 表的读写Nightwatch::rejectQueries(fn($q) str_contains($q-sql, telescope) || str_contains($q-sql, pulse) );3. 保护缓存键中的用户数据——用户 ID 出现在缓存键里时做脱敏而非过滤保住哪个键被访问的结构信息Nightwatch::redactCacheEvents(fn($e) $e-key preg_replace(/user:\d/, user:***, $e-key) );Coolify 仓库中的 Nightwatch 落地方式以上配置项在 Coolify 仓库里的实际接入方式可以从源码与部署脚本中得到印证1. 总开关默认关闭。config/constants.php 定义了NIGHTWATCH_ENABLED的读取且默认值为falsenightwatch [ is_nightwatch_enabled env(NIGHTWATCH_ENABLED, false), ],即 Nightwatch 在 Coolify 中是可选能力不配置NIGHTWATCH_ENABLEDtrue时完全不启用。2. 生产镜像通过 s6-overlay 托管 agent 进程。docker/production/etc/s6-overlay/s6-rc.d/nightwatch-agent/run 的启动脚本逻辑是cd /var/www/html if grep -qE ^NIGHTWATCH_ENABLEDtrue .env 2/dev/null; then echo INFO Nightwatch is enabled, starting... exec php artisan nightwatch:agent fi echo INFO Nightwatch is disabled, sleeping. exec sleep infinity即容器内该服务始终存在但只有.env中显式NIGHTWATCH_ENABLEDtrue时才真正执行php artisan nightwatch:agent否则进程进入sleep infinity空转——与上一条配置默认值形成呼应。该服务在 s6 的依赖拓扑中被列为 user 服务组成员见 docker/production/etc/s6-overlay/s6-rc.d/user/contents.d 下的 nightwatch-agent 条目与horizon、scheduler-worker等并列。3. 开发镜像额外做容器角色隔离。开发环境的同名脚本docker/development/etc/s6-overlay/s6-rc.d/nightwatch-agent/run在检查环境变量之前还先通过coolify_container_has_role判断当前容器的COOLIFY_CONTAINER_ROLE是否包含worker、nightwatch或nightwatch-agent角色不满足则直接 sleep避免多容器开发拓扑中每个容器都起一个 agent。对应测试 tests/Feature/ContainerRoleScriptTest.php 验证了horizon,scheduler,nightwatch,flux这类逗号分隔角色串能正确匹配nightwatch角色并断言生产镜像的三个服务脚本horizon、nightwatch-agent、scheduler-worker中不含角色辅助逻辑——即角色隔离只存在于开发镜像保持生产镜像精简。4. 技能文档的 Agent 化分发。boost.json 把configure-nightwatch列入 skills 清单意味着在 Coolify 仓库内工作时编码 Agent 会自动激活这份配置技能来指导 Nightwatch 相关变更技能文档本身SKILL.md 与 reference.md就是本文所依据的全部配置知识。小结Nightwatch 的调优本质上是在观测价值 / 数据成本 / 隐私合规三者之间做分层决策入口层用采样率控制 trace 总量请求、命令、异常三个独立开关 路由/中间件/动态采样细化事件层用reject*()回调和NIGHTWATCH_IGNORE_*环境变量剔除噪音内容层用redact*()回调和环境变量净化 PII 与凭据。Coolify 仓库则以NIGHTWATCH_ENABLED默认 false s6-overlay 常驻服务 开发镜像角色隔离的方式把整套能力做成可选、可验证、可回退的部署形态——这也是自托管 PaaS 接入开发环境可观测性时值得参考的工程模式。【免费下载链接】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），仅供参考