番茄小说搜索失效排查：Tomato-Novel-Downloader 从空结果到备用接口实战复盘

番茄小说搜索失效排查Tomato-Novel-Downloader 从空结果到备用接口实战复盘【免费下载链接】Tomato-Novel-Downloader番茄小说下载器不精简版项目地址: https://gitcode.com/gh_mirrors/to/Tomato-Novel-DownloaderTomato-Novel-Downloader 的搜索失效排查从一次什么都搜不到开始。这个番茄小说下载器的搜索入口在某一版本后对多数用户失效输入关键词没有结果而下载主链路完全正常。这篇文章按时间线还原整个排查过程先复现、再定位到上游接口的设备签名依赖最后用两个参数更少的端点把搜索能力拉回可用。故障现场用户侧反馈集中在同一条路径上能下载、不能搜索。Web 端与 TUI 端的搜索同时失效说明问题不在某一种界面实现而在共同的搜索上游。谁使用 Web UI 或 TUI 的普通用户在什么操作下首页搜索框输入关键词如剑来按回车或在 TUI 输入框键入书名后回车看到什么表现Web 端列表停在加载态接口返回空itemsTUI 状态栏提示搜索失败同一版本直接输入 book_id 下载完全正常同一网络下官方 App 内搜索正常。最后一条是关键对照App 正常、程序不正常且 book_id 直连下载不受影响问题范围被压缩到搜索接口调用方式本身。排查路径四步定位搜索接口异常第一步排除本地与客户端因素在稳定复现的网络环境用 curl 直接请求原搜索接口。响应状态是 200但结果数组为空同样的参数放到 App 的请求链路上却能返回数据。这一步排除了本地网络、代理配置和程序自身逻辑把嫌疑指向上游。第二步抓取上游实际校验行为对比 App 发出的搜索请求与程序发出的请求发现原接口要求七个 x-* 头部x-signature、x-timestamp、x-device-id、x-app-version、x-network-type、x-carrier、x-tt-token。程序此前依赖的官方客户端负责生成这些头其中x-tt-token与设备指纹强绑定。空结果出现在签名头缺失或过期的请求上而完整签名的请求仍有数据——这排除了接口整体下线的假设。第三步追到设备注册依赖x-tt-token的上游来源是设备注册服务log.snssdk.com。该域名用于设备注册与广告分发长期被公司网、校园网、DNS 过滤和 AdGuard 一类规则拦截这一点在 src/prewarm_state.rs 的提示文案里早有记录IID 注册需要访问该域名拦截后注册失败。排查到此把两段孤立的线索接上了签名失败不是算法变了而是拿不到能生成签名的设备身份。第四步确认根因转攻替代端点根因可以收敛为一句话搜索依赖设备签名链而签名链的起点设备注册域名在大量真实网络里不可达。继续逆向签名生成规则代价高且不稳定转向绕开签名的端点更实际。破局点x-* 签名链为什么会在空结果上隐身这个案例里信息量最大的不是接口本身而是失败形态。上游风控失败通常不会返回 401 或 403而是 200 加空列表——对调用方来说这和没有搜到这本书长得一样排查极易卡在是不是没这本书上。机制拆开看是三层串联第一层设备注册。程序启动时需要向log.snssdk.com完成设备注册拿到后续签名所需的设备身份。这一域名因为用途设备注册/广告分发天然在各类过滤名单里第二层签名生成。七个 x-* 头中x-signature对时间戳、设备标识做联合签名x-tt-token直接来自注册产物。任何一层缺位签名链都断掉第三层服务端静默降级。签名不可信的请求被当作低可信流量处理返回合法的空结果而非报错。所以搜索失效的真实语义是设备身份缺失。这也是 src/ui/tui/mod.rs 里已有IID 注册失败请放行 log.snssdk.com提示的原因——提示针对的是下载预热而搜索走的是同一条签名链故障面比提示覆盖的范围更大。社区测试还发现把x-signature相关头全部去掉、只保留aid1967offset0q{keyword}请求新端点即可稳定拿到结果说明签名校验只挂在旧入口上。落地细节两个替代端点的取舍社区测试确认了当前版本下可用的两个端点https://novel.snssdk.com/api/novel/channel/homepage/search/search/v1/保留device_platformandroidparent_enterfromnovel_channel_search.tab.aid1967offset0q{keyword}参数形态响应结构与旧接口更接近适合做解析兼容的过渡主选https://api-lf.fanqiesdk.com/api/novel/channel/homepage/search/search/v1/仅需aid1967offset0q{keyword}参数最简作为无参数依赖的兜底。维度原接口七头签名新端点fanqiesdk必需参数aid、offset、q 7 个 x-* 头aid、offset、q设备注册依赖有log.snssdk.com无被过滤网络下可用性低高失效形态200 空列表未观察到实现上做了四个决定搜索请求按端点列表顺序重试首个 5xx 或空响应立即切换不做指数退避以免拖长用户等待旧的官方签名路径保留在 Cargo.toml 的official-api特性之后不删除给旧环境留回退面关键词经查询参数表提交由客户端自动百分号编码中文与特殊字符不手工拼 URL并发沿用 Web 路由里已有的信号量上限 2见 src/ui/web/routes/search.rs搜索整体失败时返回 502 与错误文案界面提示搜索服务暂不可用book_id 直连下载不受影响。回归验证验证项与通过标准中英文关键词各一组如剑来、urban两端点均返回非空列表title 与 author 字段齐全offset 翻页0/20/40第二页起无整页重复特殊字符关键词含、空格请求不被截断结果正常并发 10 次搜索无上游 429信号量限流生效手动切断 fanqiesdk 端点请求在超时内回落 snssdk 端点结果仍可返回no-official-api构建搜索接口明确返回需要 official-api 特性的错误提示而非静默空列表。同类项目避坑清单搜索、下载、预热共享上游时按功能拆分故障域搜索断掉不该让下载链路陪着不可用。对上游接口做空结果率与状态码巡检风控型故障不报错监控不盯合法的空就永远等用户报障。外部接口调用保持可配置、可整体替换端点 URL 与参数表放配置层而不是散在业务代码里。解析层容忍字段缺失按多候选键取数参考 src/network_parser/network.rs 里多键位回退的写法上游换字段不至于全链路崩。把上游风控/域名被拦截写进常见错误提示本项目对 log.snssdk.com 的拦截提示就省下了大量往返排查时间。这次修复把搜索从依赖设备注册改成了依赖两个无签名的公开端点故障面变小监控点变简单入口恢复可用。【免费下载链接】Tomato-Novel-Downloader番茄小说下载器不精简版项目地址: https://gitcode.com/gh_mirrors/to/Tomato-Novel-Downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考