Local Deep Research 通知丢弃原因精确化重构从exception到webhook_failed/invalid_url的透明化诊断【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research本技术指南深入解析 Local Deep ResearchLDR通知系统一次重要的可观测性重构issue #5110 及其后续 #5113NotificationManager在通知被丢弃时返回的NotificationResult/NotificationReason现在能够精确区分webhook 投递真正失败、URL 在调度前被安全验证拒绝、egress 策略拒绝与服务器级开关关闭等不同原因。读者读完本文将掌握 LDR 通知投递的完整生命周期、全部 8 种丢弃原因的含义与触发条件、相关源码实现与测试验证以及在实际部署中如何借助日志与结构化结果快速定位通知丢失的根因。背景为什么需要精确的丢弃原因LDR 的通知系统通过 Apprise。在重构之前send_notification只返回一个布尔值失败原因被笼统地归为exception运维人员无法区分是 webhook 端点本身挂了dead endpoint、HTTP 4xx/5xx、网络中断还是 URL 在发送前就被安全校验拒绝不可解析、被 SSRF 防护拦截或者是 egress 策略拒绝了该 URL而策略根本没有被真正评估又或者是服务器级别的出站总开关未打开issue #5110 的核心诉求就是让丢弃原因诚实、精确、可操作。本次变更changelog.d/5110.bugfix.md与后续跟进changelog.d/notification-invalid-url-followup.bugfix.md共同完成了这一目标。结构化结果NotificationResult与NotificationReason重构的核心是引入两个公共类型并在notifications包的__all__中导出src/local_deep_research/notifications/init.pyNotificationReason字符串枚举精确描述通知未发出的原因NotificationResult冻结 dataclass携带sent、reason、detail三个字段。枚举值完整说明NotificationReason定义于 src/local_deep_research/notifications/manager.py共 8 个取值枚举值字符串值含义SENTsent通知已成功投递SERVER_DISABLEDserver_disabled服务器级出站总开关关闭env-onlyEVENT_DISABLEDevent_disabled该事件类型在用户设置中被关闭UNCONFIGUREDunconfigured用户未配置notifications.service_urlEGRESS_DENIEDegress_denied被 egress 策略拒绝INVALID_URLinvalid_urlURL 在调度前被拒绝不可解析或未通过安全验证WEBHOOK_FAILEDwebhook_failedwebhook 投递真实失败重试耗尽EXCEPTIONexception意外的、无法归类到上述类别的运行时错误字段与向后兼容NotificationResult定义于同一文件的 L51-L66dataclass(frozenTrue) class NotificationResult: sent: bool reason: NotificationReason detail: str def __bool__(self) - bool: return self.sent其中__bool__保留了旧的布尔契约——所有if manager.send_notification(...):风格的调用方无需任何修改即可继续工作而reasondetail则为队列辅助函数queue_helpers和错误上报器error_reporter提供可用于日志的精确原因。detail是对运维人员友好的简短补充说明但刻意保持静态、不插值不包含 URL、token、异常消息以避免凭据经日志/UI 二次泄露。webhook_failed真正发生的投递失败本次变更最重要的语义修正之一只有投递层确认失败才标记为webhook_failed不再与通用的exception混为一谈。触发链路SendError 只在重试耗尽后抛出在 manager.py 的 except SendError 分支 中WEBHOOK_FAILED只由SendError触发。而SendError的抛出位置被严格限定在NotificationService._send_with_retry的重试终点src/local_deep_research/notifications/service.pyretry( stopstop_after_attempt(3), waitwait_exponential(multiplier1, min0.5, max10), retryretry_if_not_exception_type( (ValueError, RuntimeError, SecurityBlockError) ), reraiseTrue, ) def _send_with_retry(...):重试策略为最多 3 次、指数退避0.5s → 1.0s → 2.0sTenacity 配置下上限 10s用于吸收瞬时网络故障。关键设计点可重试的瞬时失败死端点、HTTP 4xx/5xx、网络中断→ 3 次重试后仍失败才抛SendError→ 映射为webhook_failed不可重试的安全拒绝被显式排除在重试谓词之外fail fast不做 3 次重试ValueErrorpin 在发送时刻检测到的 SSRF 重绑定rebind to private/metadataRuntimeError即dns_pinning.NotificationGuardUnavailableErrorDNS-pin shim 未安装的 fail-closed 拒绝SecurityBlockErrorasync_mode/tag 不变式被违反的 fail-closed 拒绝。这意味着webhook_failed的语义被收窄为纯粹的投递失败已确认的 SSRF/DNS-rebind 安全拦截会经由SecurityBlockErrorServiceError子类映射为INVALID_URL而非WEBHOOK_FAILED见 service.py 的 except ValueError 分支 与 manager.py 的 except SecurityBlockError 分支绝不会被误标为可重试的 webhook 故障。静态 detail 防泄露WEBHOOK_FAILED的 detail 固定为webhook delivery failed after retries不使用异常消息插值——因为SendError的异常消息可能包裹 URL/token而logger.exception已经记录了完整堆栈供运维查看manager.py L482-L490。对应测试 tests/notifications/test_manager.pytest_webhook_failed_when_delivery_raises_senderror验证了这一映射。invalid_url调度前被拒绝的 URL新增原因这是本次变更新增的丢弃原因覆盖三类在真正派发之前就被拒绝的情形不可解析的 URL 片段缺少 scheme、或包含未编码的空格/反斜杠/控制字符如discord://x garbage、slack://t/x/y\。parse_notification_url_list检测到invalid_fragment非None时直接返回INVALID_URLmanager.py L331-L359。配置了但解析出零个 URLnotifications.service_url仅含分隔符如,同样属于无效配置而非策略拒绝manager.py L361-L380。URL 安全验证拒绝NotificationService.send()通过NotificationURLValidator.validate_multiple_urls在派发前做 SSRF 校验私有/内网 IP、云元数据 IP、不安全协议、被禁参数等被拒绝时抛ServiceError→ 映射为INVALID_URLmanager.py L518-L540。Appriseadd()失败Apprise 拒绝了某个 scheme 分区不可解析或不支持的 scheme此时返回INVALID_URL而非声称所有 URL 都失败——注意_dispatch在第一个add()失败的分区就返回False后续合法分区根本未被尝试因此不能谎报一个都没成功manager.py L436-L458。与egress_denied的边界策略从未被咨询INVALID_URL与EGRESS_DENIED的关键区别在于不可解析的 URL 永远不会进入 egress 策略的逐 URL 评估循环因此把它报为egress_denied会误导运维去放宽一个从未被咨询过的策略issue #5110 的核心缺陷。相关测试包括test_unparseable_service_url_is_invalid_url_not_egress_deniedtest_separator_only_service_url_is_invalid_url_not_egress_deniedtest_whitespace_mixed_malformed_url_is_invalid_url_not_egress_deniedtest_invalid_url_when_apprise_accepts_no_urls。行为变更提醒本次修复引入一处明确的行为变更见 changelog.d/notification-invalid-url-followup.bugfix.md只要notifications.service_url中任一条目包含非法未编码字符空格、反斜杠、控制字节整个设置就以invalid_url拒绝。此前这些条目虽也在派发前被拒绝但运维看到的 reason 可能是误导性的egress_denied。修复方式是百分号编码该字符或将值拆分为多个逗号分隔的 URL。注意条目周围的空白包括非 ASCII 空白如粘贴引入的U00A0不换行空格仍会被安全裁剪不受影响。egress_denied的细节细分两种截然不同的失败当 egress 策略介入后_filter_urls_by_egress_policy可能返回两种都是 falsy 但语义完全不同的结果manager.py L642-L769返回值语义日志/detail空字符串策略被评估并拒绝了每一个 URLall configured URLs refused by egress policyNone策略无法评估系统 fail-closed 拒绝全部egress policy could not be evaluatedNone的典型触发是快照存在但context_from_snapshot抛PolicyDeniedError/ValueError——例如策略配置错误。此前的实现用裸except落到return service_urls等于在策略配置错误时fail-open放行所有 URL现在改为拒绝全部并明确告知运维策略无法评估让修复方向正确见 manager.py L703-L714 的注释。该区分对定时/排队通知scheduled/queued notifications和NotificationManager.test_service均生效对应测试 tests/notifications/test_manager.py。另外_filter_urls_by_egress_policy在PRIVATE_ONLY作用域下会拒绝无法可靠验证为本地目标的非 HTTP(S) 供应商 scheme如discord://、mailto://并以scheme://host[:port]的脱敏形式记录被拒 webhook——只记录策略决策所依据的主机部分绝不记录完整 URL其中可能含凭据见 manager.py L744-L760。server_disabled的 detail 修正不再撒谎说 is not setserver_disabled的detail文案被修正当出站通知因环境变量被显式禁用时不再声称该环境变量is not set。当前实现manager.py L258-L275if not self._outbound_allowed: logger.warning( Notification refused: outbound notifications are disabled at the server level. Set LDR_NOTIFICATIONS_ALLOW_OUTBOUNDtrue to enable. ... ) return NotificationResult( sentFalse, reasonNotificationReason.SERVER_DISABLED, detail( outbound notifications are disabled at the server level (LDR_NOTIFICATIONS_ALLOW_OUTBOUND) ), )需要强调的是这个开关是服务器级、仅环境变量LDR_NOTIFICATIONS_ALLOW_OUTBOUND默认关闭不可通过用户可写的设置 API 翻转——forceTrue只能绕过用户级事件开关与速率限制无法绕过此总开关。关闭原因与残余风险Apprise 的 DNS-rebinding TOCTOU 窗口详见 SECURITY.md 的 Notification Webhook SSRF 一节与 docs/NOTIFICATIONS.md 的 Server-Side Opt-In Required 章节。对应测试 tests/notifications/test_manager.py 断言SERVER_DISABLED映射。test_service与Send Test Notification端点的同步修正本次变更确保测试路径与真实发送路径对丢弃原因的判断保持一致manager.py test_service L561-L640不可解析的片段与零 URL 条目被归为invalid_url类错误不再提示用户将 Egress Scope 设为 Unprotected——那会引导用户放宽一个从未被咨询过的策略只有当策略确实被评估并拒绝时才提示 egress 相关错误若策略本身无法评估返回独立的提示check the egress policy settings (policy.egress_scope)。配套的跟进修复还强化了测试端点本身见 changelog.d/notification-invalid-url-followup.bugfix.md任何无法分割为无歧义条目的 service URL 都会被拒绝而不是拿尾部片段代替原条目进行验证传给 Apprise 的是已解析的条目列表而非原始字符串从而把 Apprise 自身的 URL 分割器移出校验路径service.py test_service L746-L974并通过len(temp_apprise) len(url_entries)的解析器差分守卫 fail-closed防走私仅拒绝注册目标多于已验证目标的方向。此外NotificationManager.test_service目前只被测试套件调用线上/api/notifications/test-url路由直接构造NotificationService不经过 manager 的 egress 预检见 manager.py L571-L578 的说明注释。日志与安全片段内容永不入日志所有涉及不可解析片段的分支都遵循同一安全原则绝不记录任何派生自片段内容的信息——连脱敏形式也不记。原因在 manager.py L335-L343 有详细解释对 token-in-authority 的 Apprise scheme如slack://xoxb-SECRET/T00/B00连scheme://host的脱敏形式都会保留第一个 authority 段——而那个段本身就是密钥。因此日志只记录fragment_length片段长度与entries_parsed已解析条目数足以诊断问题又不泄露凭据。同时invalid_url审计日志不再记录片段的任何形式egress 策略审计日志则记录被拒 webhook 的scheme://host而非完整 URL。对应测试 tests/notifications/test_manager.py 断言invalid_url丢弃日志不含片段的任何派生内容。总结丢弃原因速查与运维实践最终send_notification的返回结果可以按以下顺序排查与 manager.py send_notification 的检查顺序一致server_disabled→ 运维设置LDR_NOTIFICATIONS_ALLOW_OUTBOUNDtrueevent_disabled→ 检查用户侧事件开关notifications.on_event速率限制 → 抛RateLimitError保留为异常而非NotificationResult值见 manager.py L36-L38unconfigured→ 配置notifications.service_urlinvalid_url→ 检查 URL 的可解析性与安全验证SSRF 拦截、Appriseadd()拒绝、非法字符egress_denied→ 区分全部被策略拒绝调整策略/URL与策略无法评估修复策略配置本身webhook_failed→ webhook 端点本身故障检查端点可用性与网络exception→ 意外的运行时错误查阅logger.exception的完整堆栈。这套精确的丢弃原因体系NotificationResult/NotificationReason均已从notifications包公开导出见 src/local_deep_research/notifications/init.py不仅让日志含policy_auditTrue绑定的审计日志清晰可读也让队列辅助函数与错误上报器能够针对不同原因采取不同策略是 LDR 通知系统可观测性与安全性的一次实质性提升。【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10 search engines - arXiv, PubMed, your private documents. Everything Local Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考