Coolify 中 Laravel Nightwatch 观测配置参考：采样、过滤与脱敏实战指南

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/coolifyLaravel Nightwatch 是 Laravel 官方出品的应用监控与可观测性服务其配置的核心在于三个环节采样Sampling决定捕获哪些请求入口、过滤Filtering决定剔除哪些噪音事件、脱敏Redaction决定如何改写事件中携带的敏感数据。本文以 Coolify 项目自带的.cursor/skills/configure-nightwatch/reference.md速查文档为主体结合 Coolify 对 Nightwatch 的真实集成方式给出按事件类型组织的配置参数速查表、生产环境推荐预设、可直接复制的常用代码模式以及一套配置后的验证清单帮助你在一线生产负载下平衡可观测性、性能与隐私三者的关系。Nightwatch 在 Coolify 中的集成方式在进入具体配置之前先厘清本项目Coolify中 Nightwatch 是如何被引入与启用的以便把下文的环境变量配置落到实处。依赖引入laravel/nightwatch包在 composer.json 中声明当前锁定版本为^1.28.6说明 Coolify 作为 Laravel 应用直接依赖了官方 Nightwatch 包。总开关配置Coolify 在 config/constants.php 中定义了nightwatch.is_nightwatch_enabled其值读取自NIGHTWATCH_ENABLED环境变量默认false。也就是说Nightwatch 默认处于关闭状态需要显式开启。后台 Agent 的启动方式在 Docker 部署中Coolify 通过 s6-overlay 管理进程。对应脚本位于 docker/production/etc/s6-overlay/s6-rc.d/nightwatch-agent/run开发环境对应 docker/development/etc/s6-overlay/s6-rc.d/nightwatch-agent/run当.env中出现NIGHTWATCH_ENABLEDtrue时执行php artisan nightwatch:agent否则保持休眠。测试环境的显式关闭在 phpunit.xml 中设置了NIGHTWATCH_ENABLEDfalse避免测试产生遥测数据。因此在 Coolify 这类自托管 Laravel 应用中启用 Nightwatch第一步就是在.env中设置NIGHTWATCH_ENABLEDtrue并配置 Agent 凭证随后本文介绍的所有NIGHTWATCH_*采样/过滤/脱敏变量才会生效。前提说明Nightwatch 本身属于 Laravel 云服务生态采集的数据最终会写入 Nightwatch 仪表盘。下文所有环境变量与 API 均以文档与当前依赖^1.28.6覆盖的能力为准。数据采集流水线采样 → 过滤 → 脱敏Nightwatch 的事件处理遵循固定三段流水线理解这张流程图是掌握全部配置项的前提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采样Sampling发生在请求、命令、定时任务等入口点层面。只有当入口点被采样命中时才会生成整条 trace 以及依附其上的全部子事件。因此采样率控制的是整条链路的捕获概率代价是链路完整性一旦丢弃即整体丢失。过滤Filtering发生在入口点已采样、事件已生成之后。此时按事件类型逐条剔除噪音例如缓存命中日志、某张内部表的查询、群发邮件等。过滤只丢单条事件不影响同一条 trace 的其他事件。脱敏Redaction发生在事件即将入库之前。与过滤不同脱敏保留事件本身只改写其中的敏感字段如把 URL 中的secret替换为***、把 User-Agent/IP 抹尾保证数据仍在、隐私已除。按事件类型的配置总览表reference.md 给出了一张按事件类型组织的速查表覆盖了采样方式、过滤方式与脱敏字段三个维度是实际调参时最常用的入口事件类型采样方式过滤方式脱敏对象RequestsHTTP 请求NIGHTWATCH_REQUEST_SAMPLE_RATE、路由中间件不适用Headers、payload、URL、IPCommandsArtisan 命令NIGHTWATCH_COMMAND_SAMPLE_RATE、事件监听器不适用命令参数Queries数据库查询继承父上下文rejectQueries()、NIGHTWATCH_IGNORE_QUERIESSQL 语句Cache缓存事件继承父上下文rejectCacheKeys()、rejectCacheEvents()、NIGHTWATCH_IGNORE_CACHE_EVENTSCache keyJobs队列任务继承父上下文、Queue::beforerejectQueuedJobs()不适用Mail邮件继承父上下文rejectMail()、NIGHTWATCH_IGNORE_MAIL邮件主题Notifications通知继承父上下文rejectNotifications()、NIGHTWATCH_IGNORE_NOTIFICATIONS不适用Outgoing Requests出站 HTTP 请求继承父上下文rejectOutgoingRequests()、NIGHTWATCH_IGNORE_OUTGOING_REQUESTSURLExceptions异常NIGHTWATCH_EXCEPTION_SAMPLE_RATE不适用异常消息阅读该表的三个要点继承父上下文的含义Queries、Cache、Jobs、Mail、Notifications、Outgoing Requests 本身没有独立的全局采样率它们是否被采集取决于其所属入口request/command是否被采样命中需要解耦时可对 Jobs 单独采样见下文解耦队列任务采样。过滤只在有对应类型时才生效如 Requests 与 Exceptions 不提供整类丢弃式过滤因为异常通常永远要采而 Cache、Mail 等噪音源则有整类关闭的环境变量。脱敏默认值不同Requests 的 Headers 默认自动脱敏Authorization、Cookie、X-XSRF-TOKEN等敏感头Request payload 捕获默认关闭其余类型的脱敏默认需要显式开启。采样配置控制采哪些入口采样位于流水线第一环决定是否生成整条 trace。入口点包括请求、命令与定时任务。当入口点命中采样其下全部事件都会被采集。全局采样率环境变量# 默认 100% 采样捕获所有请求/命令 NIGHTWATCH_REQUEST_SAMPLE_RATE0.1 # 建议生产环境先取 10% 的请求 NIGHTWATCH_COMMAND_SAMPLE_RATE1.0 # 捕获全部命令 NIGHTWATCH_EXCEPTION_SAMPLE_RATE1.0 # 异常永远捕获采样率取值范围为0.0从不采样到1.0全量采样之间的小数0.01即 1%、0.1即 10%。生产环境建议从请求0.1起步再根据实际流量与事件配额quota按需下调或上调。基于路由的采样Sample 中间件全局采样率无法区分管理后台必须全量记录、健康检查完全不必记录这类诉求此时应使用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(float)指定比例、Sample::always()恒定采样、Sample::never()恒定排除。对依赖探活/负载均衡的应用健康检查与心跳接口建议一律Sample::never()既省配额又无信息价值。未匹配路由404/机器人流量的低比例采样大量 404 与爬虫流量最容易撑爆事件配额却几乎没有排查价值。可在fallback路由上附加低采样率Route::fallback(fn () abort(404)) -middleware(Sample::rate(0.01)); // 1% sampling for unmatched routes该写法把兜底路由的采样压低到 1%既不彻底丢失恶意扫描的可观测信号又不至于被噪音淹没。动态采样按运行时条件决定当采样条件取决于运行时状态如用户角色、请求属性时可在自定义中间件中调用Nightwatch::sample()动态拉高采样与之相对的还有Nightwatch::dontSample()见下文命令采样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); } }命令采样排除噪音命令后台调度器Laravel Scheduler的管家式命令如schedule:finish、horizon:snapshot每次调度周期都会触发频率极高却无观测价值。可监听CommandStarting事件将其排除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(); } }); }考虑到 Coolify 同时启用了 Horizon 与调度器见 config/constants.php 中horizon.is_horizon_enabled与is_scheduler_enabled默认开启的配置像horizon:snapshot、schedule:run这类高频调度命令在真实部署中同样会持续产生采样入口属于该排除模式的典型适用场景。框架/内部命令的采集Nightwatch 默认自动忽略框架内部命令与 vendor 自带命令。若希望把这些命令也纳入观测如排查依赖包命令的耗时需显式开启Nightwatch::captureDefaultVendorCommands();过滤配置剔除已采样事件中的噪音过滤发生在采样命中之后用于剔除特定单条事件从而压低配额消耗。按类型划分如下。数据库查询整类关闭查询采集适用于查询量巨大且不在乎 SQL 明细的场景NIGHTWATCH_IGNORE_QUERIEStrue按 SQL 模式精确过滤常用场景是过滤队列表、缓存表自身产生的读写。注意 SQL 方言差异——PostgreSQL 使用into jobsMySQL 使用反引号from cachepublic function boot(): void { // 过滤 job 表查询PostgreSQL Nightwatch::rejectQueries(function (Query $query) { return str_contains($query-sql, into jobs); }); // 过滤 cache 表查询MySQL Nightwatch::rejectQueries(function (Query $query) { return str_contains($query-sql, from cache) || str_contains($query-sql, into cache); }); }缓存事件整类关闭缓存事件缓存命中/未命中通常是最庞大的噪音源之一NIGHTWATCH_IGNORE_CACHE_EVENTStrue按 key 过滤支持三种条目——精确字符串、正则表达式需用/pattern/包裹如 session ID、带前缀的 key 族或直接通过回调按需判定Nightwatch::rejectCacheKeys([ my-app:users, // 精确匹配 /^my-app:posts:/, // 正则以 my-app:posts: 开头 /^[a-zA-Z0-9]{40}$/, // 正则40 位会话 ID ]);回调式过滤适合规则无法用key 前缀表达的复杂场景Nightwatch::rejectCacheEvents(function (CacheEvent $cacheEvent) { return str_starts_with($cacheEvent-key, temp:); });邮件事件整类关闭邮件采集NIGHTWATCH_IGNORE_MAILtrue按主题过滤适合剔除营销/广播类邮件只保留事务性邮件Nightwatch::rejectMail(function (Mail $mail) { return str_contains($mail-subject, Newsletter); });通知事件整类关闭通知采集NIGHTWATCH_IGNORE_NOTIFICATIONStrue按通道过滤例如只关心 Slack/邮件这类外部通道排除写库的database通道通知Nightwatch::rejectNotifications(function (Notification $notification) { return $notification-channel database; });出站 HTTP 请求整类关闭出站请求采集NIGHTWATCH_IGNORE_OUTGOING_REQUESTStrue按 URL 过滤适合剔除对埋点/统计类域名如analytics.example.com的调用噪音Nightwatch::rejectOutgoingRequests(function (OutgoingRequest $request) { return str_contains($request-url, analytics.example.com); });队列任务按任务类名过滤将低优先级任务从采集范围剔除Nightwatch::rejectQueuedJobs(function (QueuedJob $job) { return $job-name App\Jobs\LowPriorityJob; });解耦队列任务采样Jobs 默认继承父上下文由派发它的入口采样决定。若希望高价值任务即使由低采样入口派发也予以采集或反过来希望控制后台任务的采集成本可在Queue::before钩子中为队列任务单独设置采样率public function boot(): void { Queue::before(fn () Nightwatch::sample(rate: 0.5)); }脱敏配置保留事件、抹除敏感字段脱敏与过滤的关键区别在于脱敏后事件仍然会被记录与入库只是内容被改写。凡是可能携带 PII、token、凭据的字段都应优先考虑脱敏而非丢弃这样既能定位问题又不泄露数据。请求脱敏Headers / payload / URL / IP敏感 Header 默认自动脱敏Authorization、Cookie、X-XSRF-TOKEN无需任何配置即被内置规则处理。如需扩展名单通过环境变量追加# 自定义需要脱敏的 Header NIGHTWATCH_REDACT_HEADERSAuthorization,Cookie,Proxy-Authorization,X-API-Key请求 payload默认不采集NIGHTWATCH_CAPTURE_REQUEST_PAYLOAD默认关闭。需要捕获请求体时先显式开启再声明脱敏字段名单# 开启 payload 捕获 NIGHTWATCH_CAPTURE_REQUEST_PAYLOADtrue # 自定义需要脱敏的 payload 字段 NIGHTWATCH_REDACT_PAYLOAD_FIELDSpassword,password_confirmation,ssn,credit_card程序化脱敏URL 与 IP 无法通过名单式配置覆盖需用回调改写Nightwatch::redactRequests(function (Request $request) { $request-url str_replace(secret, ***, $request-url); $request-ip preg_replace(/\d$/, ***, $request-ip); });查询脱敏SQL 语句SQL 中可能内联临时凭据或敏感查询条件可在入库前改写 SQL 文本Nightwatch::redactQueries(function (Query $query) { $query-sql str_replace(secret_token, ***, $query-sql); });缓存 key 脱敏缓存 key 常内嵌用户 ID如user:42属于典型的 PII 载体Nightwatch::redactCacheEvents(function (CacheEvent $cacheEvent) { $cacheEvent-key str_replace(user:, user:***:, $cacheEvent-key); });reference.md 中还给出了正则可变写的等价模式preg_replace(/user:\d/, user:***, $cacheEvent-key)两种写法可任选——前者简单直白后者能覆盖任意位数的用户 ID。命令参数脱敏命令参数中极易出现--password、--token这类明文敏感项Nightwatch::redactCommands(function (Command $command) { $command-command preg_replace(/--password\S/, --password***, $command-command); });异常消息脱敏异常消息可能回显 SQL、路径或内部变量对含secret的消息做替换Nightwatch::redactExceptions(function (Exception $exception) { $exception-message str_replace(secret, ***, $exception-message); });邮件主题脱敏发票号、订单号等业务敏感信息常出现在邮件主题中Nightwatch::redactMail(function (Mail $mail) { $mail-subject str_replace(Invoice #, Invoice ***, $mail-subject); });出站请求 URL 脱敏调用第三方 API 时api_key、token等往往以查询参数形式暴露在 URL 中Nightwatch::redactOutgoingRequests(function (OutgoingRequest $outgoingRequest) { $outgoingRequest-url preg_replace(/api_key\w/, api_key***, $outgoingRequest-url); });生产环境推荐预设reference.md 针对三种典型负载给出了可直接套用的预设组合。所有NIGHTWATCH_*变量都应写入应用或容器的.env在 Coolify 中即为NIGHTWATCH_ENABLEDtrue同处的环境文件。高流量应用激进采样 强力过滤# 保守采样 NIGHTWATCH_REQUEST_SAMPLE_RATE0.01 # 1% 的请求 NIGHTWATCH_COMMAND_SAMPLE_RATE0.1 # 10% 的命令 NIGHTWATCH_EXCEPTION_SAMPLE_RATE1.0 # 异常始终捕获 # 过滤噪音事件 NIGHTWATCH_IGNORE_CACHE_EVENTStrue NIGHTWATCH_IGNORE_QUERIEStrue # 或改用程序化方式精确过滤高流量场景的取舍逻辑请求只采 1%、命令采 10%但异常采样率保持1.0——因为异常是排障的核心信号量级小、价值高任何时候都不应因采样而丢失缓存事件这类纯噪音直接整类关闭。隐私敏感应用默认少采集 强脱敏# 关闭敏感数据采集 NIGHTWATCH_CAPTURE_REQUEST_PAYLOADfalse NIGHTWATCH_REDACT_HEADERSAuthorization,Cookie,Proxy-Authorization,X-XSRF-TOKEN # 或在 AppServiceProvider 中使用脱敏 API 做程序化处理对处理用户个人信息PII的应用payload 采集保持默认关闭不开启NIGHTWATCH_CAPTURE_REQUEST_PAYLOAD并显式把认证类 Header 全部列入脱敏名单更细粒度的 URL/IP/字段改写则交给AppServiceProvider::boot()中的Nightwatch::redactRequests(...)等回调上文脱敏一节给出的所有回调均写于此。均衡配置推荐起步值# 采样率 NIGHTWATCH_REQUEST_SAMPLE_RATE0.1 NIGHTWATCH_COMMAND_SAMPLE_RATE1.0 NIGHTWATCH_EXCEPTION_SAMPLE_RATE1.0 # 用程序化方式过滤明显噪音缓存/特定查询见上文 Filtering 节 # 按需脱敏 PII见上文 Redaction 节这是新接入 Nightwatch 时最稳妥的起点请求 10% 采样足以描绘流量形态命令与异常全量保留保证排障无损过滤与脱敏先以最小集跑通再根据仪表盘的噪音占比逐步加码。配置后的验证清单配置不是一次性动作改完采样/过滤/脱敏规则后应逐项核对reference.md 给出了如下检查清单采样率与流量规模匹配高流量下请求采样是否过载/过低噪音事件已被过滤缓存事件、特定查询等是否已剔除敏感数据已脱敏PII、token、凭据是否仍有泄漏异常始终被捕获排障信号不因采样丢失在开发环境以NIGHTWATCH_REQUEST_SAMPLE_RATE1.0全量验证规则在 Nightwatch 仪表盘监控事件配额消耗其中开发环境全量采样1.0 生产环境低采样是最重要的验证手法先在开发环境让所有规则 100% 暴露确认过滤与脱敏符合预期后再上线到生产的小比例采样。常见组合模式示例reference.md 最后给出三个高度可复制的组合示例基本覆盖了降噪 隐私的绝大多数诉求。过滤健康检查并降低采样探活接口与真实业务请求混在一起会拉高采样基数且探活本身无需任何观测价值Route::get(/health, fn() [status ok]) -middleware(Sample::never());排除内部 / vendor 查询自监控类查询telescope、pulse 等观测组件的表读写会形成观测自身造成的噪音循环Nightwatch::rejectQueries(fn($q) str_contains($q-sql, telescope) || str_contains($q-sql, pulse) );保护缓存 key 中的用户数据将user:12345这类含用户 ID 的缓存 key 改写为user:***Nightwatch::redactCacheEvents(fn($e) $e-key preg_replace(/user:\d/, user:***, $e-key) );小结本文以.cursor/skills/configure-nightwatch/reference.md为核心骨架把 Laravel Nightwatch 的配置拆解为采样→过滤→脱敏三段流水线并逐事件类型落地Requests/Commands/Exceptions 拥有独立采样率Queries/Cache/Mail/Notifications/Jobs/Outgoing Requests 主要依赖过滤与脱敏三组生产预设高流量、隐私敏感、均衡起步与配置后验证清单可直接照搬。在 Coolify 中启用时只需在.env设置NIGHTWATCH_ENABLEDtrue随包自带的 Agent 便会被 s6 启动脚本拉起再按上文对采样率、过滤规则与脱敏名单逐项调优即可同时兼顾可观测性、性能与隐私合规。若需查阅更完整的官方说明可继续阅读同目录的 .cursor/skills/configure-nightwatch/SKILL.md其中指向的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考