用 Stremio 做一个自己的影视聚合 Addon:从想法到线上的完整复盘
用 Stremio 做一个自己的影视聚合 Addon:从想法到线上的完整复盘
记录一个历经迭代十余轮、被各种”玄学问题”折磨的技术项目。
涉及 Node.js / Stremio Addon 协议 / HLS 清洗 / Vercel 部署 / IP 屏蔽与代理降级。
缘起
在用 Stremio 看片的时候,总是要装好几个第三方 Addon 才能覆盖想看的资源。Cinemeta 提供 IMDb 元数据但没有国内源,一些小众 Addon 只接一两个站点。如果一个 Addon 能把暴风、非凡、量子这些都聚合起来,并且能在 Cinemeta 的影片页直接出流,会省不少事,后续可以追加更多源,具有相当的通用性。
于是有了这个项目:CatVod Multi-Source,一个多源聚合的 Stremio Addon。
最初的设想很简单:
- 每个源独立 catalog,用户能直接搜
- 在 Cinemeta 页面点某一集,Addon 自动去各源找对应资源
- 源站的 m3u8 里插了广告,顺手洗掉
却着实遇到很多坑,尤其是后期还遇到ip被屏蔽的问题,不得以自建hls-proxy来解决。
第一部分:先把协议啃透
Stremio Addon 协议本身不难,但它有几个坑点是文档里没写清楚、必须踩过才知道的。
manifest 里的 resources 有两种形式
1 | "resources": ["catalog", "meta", "stream"] |
和:
1 | "resources": [ |
第一种是简写,第二种是”高级形式”,可以为每个 resource 单独覆写 types 和 idPrefixes。关键点:如果只用简写形式,Stremio 会向你的 Addon 发所有类型的 stream 请求,包括你根本不支持的。用 idPrefixes: ["tt"] 能让 Stremio 只在请求外部 IMDb id 时调用你的 Addon。
这个细节决定了通路 2(外部 meta 拉流)能不能工作。
catalog 的 extra.search 是匹配中的关键
/catalog/series/bfzy-series/search=庆余年.json —— 请求路径里带着 search=,这个参数来自 manifest 里 catalog 的 extra 声明:
1 | "extra": [ |
坑点:catalog id 是 bfzy-series,但实际请求路径是 /catalog/series/bfzy-series/search=xxx.json,id 段里带 /。Express 4 的 /:id.json 只匹配单段,匹配不到,会 404。必须用正则路由:
1 | app.get(/^\/catalog\/(movie|series)\/(.+)\.json$/, async (req, res) => { |
这个 bug 我调了半天,一直以为是自己路由写错了,最后看了 Stremio 的实际请求才发现原因。
剧集的 video id 格式
电影直接是 tt1234567,但剧集的 stream 请求是 tt1234567:2:5(季:集)。解析时:
1 | function parseStreamId(id) { |
一开始我只做了 tt 的判断,忘了内部 id(bfzy:series:27312:1:2)也是同样的格式。改的时候把两处统一了。
第二部分:源站接口不是标准 API
三个源(暴风、非凡、量子)都是 MacCMS v10 的站点。理论上都应该支持:
- 搜索:
/api.php/provide/vod/?ac=search&wd={keyword} - 详情:
/api.php/provide/vod/?ac=detail&ids={vod_id}
实际探测下来,三个源各有各的脾气。
搜索字段不完整
暴风和量子的 ac=search 返回全字段,非凡返回的只有几个字段:
1 | bfzy: itemKeys = [vod_id, vod_name, vod_year, vod_pic, type_name, ...] ← 全 |
结论:搜索只能用于候选定位,所有完整信息必须走 detail。所以内部架构从一开始就是 search → 拿 id → 并发 detail,而不是”search 直接返回完整对象”。
播放地址有直链和 share 两种形态
暴风的 vod_play_url 是完整直链:
1 | 第01集$https://p.bvvvvvvvvv1f.com/video/qingyuniandiyiji/第01集/index.m3u8 |
非凡的 feifan 线路和量子的 liangzi 线路是 share 页面:
1 | 第01集$https://vip.ffzy-online2.com/share/116b896114ff71245852cace1f9f69c5 |
但非凡的 ffm3u8 线路、量子的 lzm3u8 线路是直链。
share 页需要二次解析:访问 share URL 拿到 HTML,里面 <script> 里有 const url = "/xxx/index.m3u8?sign=xxx",提取出来拼 origin 才是真实 m3u8。
一开始我以为所有源都是直链,代码写完才发现非凡/量子的 share 线路拉到的 HTML 直接喂给清洗器,报”不是 m3u8”。这个坑让我加了 shareResolver.js 模块。
1 | const URL_VAR_RE = /(?:const\s+url|url)\s*=\s*["']([^"']+?\.m3u8[^"']*)["']/; |
季集信息不在结构字段里
MacCMS 原生没有独立的 vod_season / vod_episode 字段,季集信息全在标题里:vod_name = "庆余年第二季粤语",分集标题 第01集。
所以内部模型的 season / episode 必须从标题解析:
1 | // "庆余年第二季粤语" → { baseName: "庆余年", season: 2, lang: "粤语" } |
匹配打分时 baseName 参与标题相似度,season 参与季匹配。如果把”粤语”这种后缀也算进标题,相似度会莫名其妙地变低。
第三部分:匹配打分器
通路 2 的核心是匹配:TMDB 给中文元数据,各源返回一堆候选,怎么判断哪条是对的?
相似度算法
字符 bigram Dice 系数。比 Levenshtein 更适合中文短字符串,因为不用考虑编辑操作顺序。
1 | export function diceSimilarity(a, b) { |
权重设计
1 | const DEFAULT_WEIGHTS = { |
测试用例:
| TMDB meta | 候选 | 分数 | 级别 |
|---|---|---|---|
| 庆余年 (2024, s2) | 庆余年第二季粤语 | 1.000 | high |
| 庆余年 (2024, s2) | 庆余年第一季 (2019) | 0.700 | medium |
| 庆余年 (2024, s2) | 庆余年之大夏战狼 | 0.622 | medium |
| 庆余年 (2024, s2) | 流浪地球 | 0.100 | low |
季不匹配扣分是合理的:用户想看第二季,第一季是错的。标题相似度高但季不同的候选必须降级到 medium,不能被强行选中。
别强行透传
设计原则:低于 0.60 直接返回空,0.60–0.85 记录到日志但不返回单条。
如果强行返回低置信的候选,用户点开发现是另一部片,体验比”没找到”还差。
第四部分:HLS 清洗
源站的 m3u8 里插了广告。清洗规则大概是:
1 | #EXT-X-DISCONTINUITY |
广告被”切”成一个独立的 DISCONTINUITY 区间,时长通常是固定值(3 秒、6.666667 秒等)。
三类规则
config/adRules.json 里每个源配一组 regex:
- 正则:完整匹配一段(如
#EXT-X-DISCONTINUITY\r*\n*#EXTINF:3\.000000,[\s\S]*?#EXT-X-DISCONTINUITY) - 纯数字:自动编译为
#EXTINF:?17\.19匹配该时长(社区大量规则直接写"17.19") - 纯字面量:命中
#EXTINF行含该词的片段(如"更多")
编译逻辑:
1 | export function compileRule(raw) { |
三层保护
清洗有个隐患:正则写得太激进会误删正常片段,用户看到的视频会变短、跳帧。
所以加了风险检测:
1 | const DEFAULT_HLS_CONFIG = { |
高风险时原样返回原始清单(只做绝对化不删片段),至少能播。
master playlist 递归
部分源(量子、非凡)返回的是 master m3u8:
1 | #EXTM3U |
子清单是相对路径。如果不处理,播放器拉子清单时就绕过了我们的清洗。
所以 master 的每个子清单入口都要改写为 /hls/clean:
1 | const params = new URLSearchParams({ url: abs.href }); |
关键细节:父清单的 query(?sign=xxx)必须继承到子清单,否则子清单可能 403。
不中转分片
这是整个项目的核心约束:只改 m3u8 清单,ts 分片绝对化后播放器直连源站。
好处:
- 服务器不需要承担分片流量
- 广告清洗只发生一次(拉清单时)
- 播放体验接近直连
代价:
- 分片层的防盗链无法处理(需 Referer/UA 的分片,播放器带不了)
- 一旦清单拉不到,整条流就废了(后面第五部分会讲怎么降级)
第五部分:Vercel 部署的至暗时刻
本地跑得好好的,部署到 Vercel 后 /manifest.json 返回 404。然后是三天的拉锯战。
坑 1:入口文件被自动探测混淆
Vercel 对 Express 应用有零配置检测。它按字典顺序找入口:
1 | app.js / index.js / server.js / main.js |
一开始我把入口放在 api/index.js,Vercel 不认识。改成 src/app.js(导出工厂函数 createApp),Vercel 选它了但又报 Can't detect way to handle request——它要的是”导出的 app 实例”,不是工厂函数。
最终的解法:在项目根目录建 server.js,**直接 import express**:
1 | import express from "express"; |
即使 createApp 内部也 import 了 express,入口文件本身必须有这一行——Vercel 是靠扫描入口文件文本来判断是不是 Express 应用的。
坑 2:vercel.json 的 rewrites 是个陷阱
看了很多教程说要用 rewrites 把请求转发到 api/index:
1 | { |
配合 api/index.js(Express 应用塞进去)看起来能工作。但本地 vercel dev 会报 NO_RESPONSE_FROM_FUNCTION,反复试都不行。
最后发现新版的 Vercel 支持零配置 Express 应用,根本不需要 rewrites。server.js 放在根目录、vercel.json 里只留 functions.includeFiles 就够了:
1 | { |
includeFiles 是必须的,因为 fs.readFileSync 读 config/sources.json,Vercel 的静态分析追不到这个运行时路径,不 include 的话打包产物里没有这个文件。
还有一个细节:includeFiles 是字符串不是数组。文档里写的不清楚,第一次写成 ["config/**"] 直接报错 includeFiles should be string。
坑 3:/configure 静态页
配置页想走 Vercel 的 CDN 直出,用了 rewrite:
1 | { "source": "/configure", "destination": "/public/configure.html" } |
结果 404。因为 public/ 目录本身就是静态根,对外暴露的 URL 是 /configure.html 而不是 /public/configure.html。destination 多写了 public/ 前缀。
但即使在 rewrite 里修对了({ "source": "/configure", "destination": "/configure.html" }),本地 vercel dev 还是会 Cannot GET /configure——某些情况下 Vercel 的 dev server 对”由 Express 服务”的项目,rewrite 优先级行为跟线上不一致。
最终方案:直接在 Express 里接管静态文件,不依赖 rewrite:
1 | const PUBLIC_DIR = path.resolve(__dirname, "../public"); |
这样本地和线上行为一致,不用再纠结 Vercel 的行为。
第六部分:IP 屏蔽——从”以为搞定了”到”原来这么复杂”
项目跑通、能出流、能在 Stremio 播放,看起来结束了。直到某天发现:
暴风的流在线上全线 404,本地却一切正常。
第一次排查
看 Vercel 日志:
1 | [ERROR] [hls] fetch failed https://p.bvvvvvvvvv1f.com/.../index.m3u8: HTTP 404 |
本地同样 URL curl 是 200。第一反应是 UA/Referer 没带对。
在 Vercel 函数里 log 出发出的请求头:
1 | req-headers: Accept=*/* | User-Agent=Mozilla/5.0 ... | Referer=https://bfzyapi.com/ |
请求头完全正确。那为什么 404?
第二个猜想:源站屏蔽了数据中心 IP
为了验证,写了一个诊断脚本,把服务端实际发出的每一次请求(含 request headers、response status/headers/body-head)都打到 /debug/hls-clean 的 fetchAttempts 字段里。
然后拿 Vercel 发出去的请求头,本地用同样的请求头 curl 同一个 URL:
1 | curl -A "Mozilla/5.0 ..." -e "https://bfzyapi.com/" "https://p.bvvvvvvvvv1f.com/..." |
本地 200,服务端 404,请求头完全一致。结论:Vercel 的出站 IP 被源站屏蔽了。
而且是伪装成 404 的屏蔽(而不是 403),源站假装”资源不存在”,比”拒绝”更隐蔽。
验证数据中心 IP 被广泛屏蔽
试了几个方案:
- Cloudflare Worker 代理:部署了
MHSanaei/HLS-Proxy-Worker,请求同一个 m3u8,也是 404。 - Vercel 换 Region:从 iad1 换到 hkg1(香港),还是 404。
- 住宅 IP 代理:成功。但成本高($10-50/月),不适合个人项目。
结论:源站屏蔽的是”数据中心 IP 段”这个大类,Vercel、Cloudflare、AWS 都在名单里。只有住宅 IP(家宽出口)能过。
第七部分:三层降级——把”IP 屏蔽”变成工程问题
在找到最终方案之前,先做的是降级:如果清单拉不到,不要返回空清单(用户看到黑屏),而是307 重定向到原始 URL,让播放器直连源站。
1 | if (r.type === "error") { |
如果分片层没被屏蔽,用户可能还能播放(虽然广告没过滤);如果分片也被屏蔽,播放器直接报错,比”能加载但黑屏”体验更清晰。
最终方案:自建清单代理
找到的关键洞察是:代理只需要拉清单,分片仍然直连源站。
- 清单一共 200KB,每天请求量也不大
- 分片是几百 GB 的流量,绝对不能走代理
- 源站屏蔽的是”清单接口”,分片接口对数据中心 IP 是放行的
于是做了一个极简代理服务(部署在家里的宽带出口 + Cloudflare Tunnel):
1 | GET https://hls.wangqifei.eu.org/m3u?url=<encoded>&referer=<...>&ua=<...> |
代理收到请求后:
- 从家宽出去拉源站 m3u8
- 把 ts 相对路径转成绝对 URL
- 原样返回 m3u8 文本
项目里改 fetchManifest.js,加了一层代理优先:
1 | async function tryFetchStage({ targetUrl, requestHeaders, stage, ... }) { |
为什么直连优先,而不是代理优先?
- 不是所有源都屏蔽 Vercel。ffzy、lz 直连是通的。
- 代理多一跳只会增加延迟。
- 代理资源应该作为”救援层”,只在直连失败时使用。
为什么不双保险(既传 query 也传 HTTP 头)?
代理接口约定是 ?ua=...&referer=...,通过 query 传。如果同时传 HTTP 头,代理可能优先用 HTTP 头,导致 Referer 变成 https://hls.wangqifei.eu.org/...(源站看到的 Referer 是代理域名),反而 403。单一渠道更干净。
完整链路
1 | /hls/clean |
每一层的尝试(request headers、response status、body head)都记录在 fetchAttempts 里,/debug/hls-clean 能看到完整链路,无需猜。
第八部分:把降级变成主路——HLS Clean 独立项目
降级只是保底,不是解法
第七部分的三层降级让 bfzy 的流”能播了”,但仔细想一下会发现一个尴尬的事实:降级之后广告还在。
307 重定向把播放器直接甩回源站原始 URL,用户拿到的是未经清洗的清单,广告分片原封不动地播出来。更麻烦的是,因为 bfzy 的清单接口对数据中心 IP 全线 404,Vercel 那一层的清洗逻辑对 bfzy 实际上是死代码——连清单都拉不到,就没有东西可清。
所以第三层降级不是终点,它只是把”服务挂掉”变成了”服务能用但功能残缺”。真正要做的是:把清单拉取挪到一个能过源站封锁的出口。
为什么现成的方案都不行
第一个想法当然是”换个代理”。试了 MHSanaei/HLS-Proxy-Worker,部署到 Cloudflare Worker,同一个 bfzy m3u8,Worker 返回 404。又试了 Vercel 换 region,从 iad1 换到 hkg1,还是 404。
到这一步已经很清楚了:源站屏蔽的不是某个云厂商,而是”数据中心 IP 段”这个大类。Vercel、Cloudflare、AWS 都在名单里,换哪个都一样。这条结论反过来说明:要找的不是”更好的云”,而是”不是云的 IP”。
住宅 IP 能过。但住宅代理服务动辄 $10–50/月,对个人项目来说成本不成比例。恰好家里有条宽带,出口就是住宅 IP,加上之前 cloudflared 的 Tunnel 环境还在,于是决定自建。
一个反直觉的结论:在这类场景下,自建代理比大厂方案更稳定。不是因为自建质量高,而是因为源站封锁的是 IP 类型,不是 IP 质量。
只代理清单,不代理分片
这是整个方案能成立的前提。算一笔账就明白:
- 一集电视剧的清单约 40–200KB,一天请求几百次,流量以 MB 计
- 同一集的分片是几百 MB 到 GB,走代理直接压垮家宽上行
所以代理的边界划得很死:只接收 /m3u 请求,拉取清单文本,清洗后返回。分片永远由播放器直连源站。
1 | GET https://hls.wangqifei.eu.org/m3u?url=<encoded>&referer=<...>&ua=<...> |
这也带来一个天然的好处:清洗只发生一次。播放器拿到清单后,每次加载分片都是直接和源站打交道,代理的负载与播放时长无关,只与清单请求次数相关。
代价同样明确:分片层的防盗链处理不了。如果源站要求分片请求也带特定 Referer,播放器带不了,只能等它 403。好在大部分 maccms 站点的防盗链只卡清单接口,分片接口对公网是放行的——这个假设在实测中成立。
通用清洗:从”源站专属规则”退回到”多弱信号组合”
CatVod 里每个源有一套专属的 adRules.json,靠精确的正则匹配 #EXT-X-DISCONTINUITY 包裹的广告块。这套规则搬到通用代理上就不合适了——HLS Clean 面对的是任意源站,不可能给每个源站配规则。
重新设计的目标是:不依赖任何源站私有标记,只用 HLS 协议本身的信号和统计规律。
| 信号 | 判定 | 性质 |
|---|---|---|
| CUE / SCTE35 | #EXT-X-CUE-OUT ~ #EXT-X-CUE-IN 区间,或含 #EXT-X-SCTE35 标记 |
强信号,出现即删 |
| 短时长簇 | 连续 ≥3 个分片短于中位数 × 0.5,且绝对值 < 4s | 弱信号 |
| 重复指纹 | 同一 hostname + pathname 在清单中出现 ≥2 次 |
弱信号 |
| 路径占比 | 某路径前缀的分片数占比 < 34%,且主路径占比 > 66% | 弱信号 |
| 时长众数 | 按 #EXT-X-DISCONTINUITY 分组,某组时长显著偏离众数且占比 ≥95% |
弱信号 |
组合规则只有一条:强信号直删,弱信号必须组合命中。
这么设计的原因是,单独任何一个弱信号都可能在正常内容里出现——一部剧里有几个超短分片很正常,某一段用不同路径存储也正常。只有多个信号同时指向同一批分片,才值得判定为广告。
举个反例:catvod 样本里那批广告,路径占比信号是命中的(广告路径占比 0.5%,正片 99.5%),但短时长、重复指纹、时长众数都不命中。按组合规则,它不会被删。这不是缺陷,是取舍——宁可漏删几条广告,也不能误删正片让用户看短了。
master m3u8 的保护:2 行代码避免一次误伤
有一个看起来不起眼、实际上很致命的问题:如果源站返回的是 master m3u8(含 #EXT-X-STREAM-INF),那么子清单行会被当作普通 URI 进入广告判定。假如某个子清单的路径恰好是 /ads/hd.m3u8,就会被 /(ad|ads|advert|promo|banner)/ 这条通用正则命中,子清单一删,整个视频就废了。
更糟的情况是:大部分 master m3u8 都既没有 #EXT-X-ENDLIST 也没有 #EXT-X-DISCONTINUITY,本来会被安全跳过条件兜住。但极少数源站会在 master 里也带上 ENDLIST,这条兜底就失效了。
所以加了一道前置判断:
1 | def filter_ads(text: str) -> str: |
两行代码,零开销,把一类可能毁掉整条流的误伤彻底规避。如果这个判断要等上线后被用户投诉才发现,代价会大得多。
全量 URI 重写:被忽略的 KEY 和 MAP
代理最容易挂的地方不是清洗逻辑,而是重写不完整。最初的实现只处理了”分片行”,对其他行一律按注释保留:
1 | if s.startswith('#'): |
结果就是:
1 |
这两行里的 URI="key.bin" 和 URI="init.mp4" 是相对路径,原样保留后播放器会向代理域名请求,必然是 404。
- 加密流:拿不到 key,解密失败,直接挂
- fMP4 流:拿不到 init 段,整个视频解不出来,直接挂
- 多音轨:
#EXT-X-MEDIA:URI="audio.m3u8"拿不到子清单,音轨缺失
这类问题有一个共同特征:普通 TS 明文流一切正常,一旦碰到加密或 fMP4 就全线报错。如果不做这类源站的测试,问题会一直到用户反馈才暴露。
最终的实现把重写范围扩大到了所有携带 URI 的位置:
| 位置 | 处理方式 |
|---|---|
| 分片行 | 整体重写为绝对地址 |
子清单行(#EXT-X-STREAM-INF 下一行) |
整体重写为绝对地址 |
标签内 URI="..." 属性 |
正则重写,覆盖 KEY / MAP / MEDIA / SESSION-KEY / I-FRAME-STREAM-INF / PART / PRELOAD-HINT |
用标准库 urljoin 而不是手写字符串拼接,hd/index.m3u8 和 ../hd/index.m3u8 都能按 RFC 3986 正确解析,不会出现”路径拼接少一个斜杠”这类错误。
双重编码:一个”浏览器不行 VLC 行”的怪现象
这个问题在实测中非常迷惑人。分片地址重写完成之后,VLC 播放完全正常,浏览器里所有 .ts 请求全部 404。对比两边的请求就明白了:
| 客户端 | 请求路径 |
|---|---|
| VLC | /video/heigediyiji/%E7%AC%AC01%E9%9B%86/0000007.ts |
| 浏览器 | /video/heigediyiji/%C3%A7%C2%AC%C2%AC01%C3%A9%C2%9B%C2%86/0000007.ts |
浏览器发出的是双重编码。原因在于重写后的清单里还保留着原始中文(第01集),HLS.js 解析清单时如果没有严格按 charset=utf-8 处理,会把 UTF-8 字节按 Latin-1 解读成乱码字符(第),再编码一次就变成 %C3%A7%C2%AC%C2%AC。源站当然不认识这个路径。
VLC 之所以没事,是因为它自己做了一次宽容的编码处理——这类”浏览器不行 VLC 行”的差异很容易被误判为”浏览器兼容性 bug”。
解法是把编码前移到重写阶段:
1 | def rewrite_uri(uri, base_url): |
quote 的 safe 参数里包含 %,已经编码过的路径不会被二次编码;中文则统一转成 %E7%AC%AC01%E9%9B%86。重写后整份清单纯 ASCII,无论播放器用什么编码解析,结果都一致。
Referer 兜底:一个便宜但有效的兼容层
CatVod 里的 Referer 是精确配置的,因为面对的源站已知。HLS Clean 面对未知源站,用户不传 Referer 就是不带,源站只要校验 Referer 就 403。
所以加了一条自动兜底:用户未显式传 Referer 时,用 m3u 地址本身的 scheme://host/ 作为 Referer。
1 | if not has_referer and target_url: |
这个兜底的命中率不低。大部分防盗链的校验逻辑是”Referer 必须来自本站或同域”,用源站自己的 origin 通常能过。比起让用户每次手动填 Referer,这条兜底至少能让大部分源站默认可用。少数要求特定站点作为 Referer 的,用户再显式传 &referer= 覆盖即可。
保活:无 systemd 环境下的 pm2 约束
HLS Clean 跑在 Bohrium 科研云的容器里,2C 4G,Ubuntu 22.04,没有独立公网 IP,也没有 systemd。对外暴露靠 Cloudflare Tunnel:
1 | Stremio / 浏览器 |
两个进程都交给 pm2 管理,容器重启后 pm2 resurrect 一条命令恢复。但这里踩过一个挺隐蔽的坑。
cloudflared 最初是用 bash -c "cloudflared tunnel run ..." 包装启动的。pm2 的重启计数悄悄涨到了 276——看起来像是 cloudflared 在崩溃重启,但日志里什么都看不到。原因是新版 cloudflared 对 edge-ip-version 的类型校验变严(要求字符串,YAML 里裸写 4 会被解析成整数),进程启动即退出;而 bash -c 的包装层让这个错误没被 pm2 捕获,pm2 只能看到”进程退出”,看不到”为什么退出”。
修复涉及两件事:
- 把 YAML 里的
edge-ip-version: 4改成edge-ip-version: "4" - 把 pm2 的启动方式从
bash -c换成直接管理二进制:pm2 start /usr/local/bin/cloudflared -- tunnel run ...
改完后 restarts: 0,uptime 稳定增长。这类问题在所有文档里都找不到,只能靠 pm2 describe 里的重启计数自己发现。
实测数据
| 指标 | 实测值 |
|---|---|
server.py 纯 CPU 处理(1600+ 分片) |
10–30 ms |
server.py 总响应耗时(容器内首字节) |
0.93 – 2.01 s |
| 瓶颈来源 | 上游源站网络响应 |
处理时间可以忽略不计,整体耗时几乎完全来自上游。这也解释了一个容易被误解的现象——加上去广告逻辑之后,接口并没有变慢。因为去广告本身只占几毫秒,用户感知的延迟 99% 来自拉取上游清单。
如果未来觉得慢,方向是给上游清单加短时缓存(30 秒 TTL),而不是优化本地代码。
与 CatVod 的分工
两个项目不是替代关系,而是分层:
| 项目 | 定位 | 部署位置 | 适用场景 |
|---|---|---|---|
| CatVod Multi-Source | Stremio Addon,多源聚合 + 匹配 + 清洗 | Vercel | 主力入口,ffzy / lz 直连可用 |
| HLS Clean | 通用 M3U 代理 + 去广告 | 家宽 + Cloudflare Tunnel | bfzy 的救援层,以及任意源的通用清洗 |
CatVod 的 fetchManifest.js 里做的是”直连优先,代理救援”——只有直连失败才走 HLS Clean。因为不是所有源都封锁数据中心 IP,多一跳只会增加延迟。HLS Clean 的价值不在”替代直连”,在”直连失败时的兜底”。
但 HLS Clean 本身被设计成了通用工具,不绑定 CatVod。任何需要清洗 m3u8 的场景——其他播放器、其他 Addon、直接把 URL 贴进浏览器——都能用同一个接口。
这一部分的反思
1. 降级方案救不了功能残缺
第七部分的三层降级让服务”没挂”,但用户拿到的仍然是带广告的流。真正解决问题需要把执行位置前移到”能过源站封锁的出口”,而不是在原来的位置上做更多补救。
2. 出口 IP 是这类项目里被低估的变量
所有”为什么本地能跑线上不行”的问题,第一反应都是代码有问题。实际上大部分时候是服务端出口 IP 被屏蔽。这个认知一旦建立,排查路径会短很多——直接对比本地和服务端的请求头,如果完全一致还 404,就不要在代码上纠结了。
3. 通用工具和专用工具的取舍是结构性的
CatVod 的规则精确,清洗效果好,但每加一个源就要配一套规则。HLS Clean 的规则宽松,清洗效果一般,但一套规则能覆盖所有源。在能”给每个源配规则”的地方用专用工具,在”不知道会碰到什么源”的地方用通用工具——这两种策略不冲突,应该并存。
4. 可观测性比功能更重要
pm2 describe 的 restarts: 276 这一行数字,比任何日志都更有价值。它提示了”这里有东西在反复崩溃”,虽然当时还不知道崩溃的原因,但至少知道该往哪看。能不能发现问题,比能不能解决问题更根本。
第九部分:缓存与一致性
L1 + L2 分层
- L1 内存:进程内 Map,零延迟,防瞬时并发
- L2 Upstash Redis:跨实例共享,冷启动恢复
- 冷却降级:连续 3 次 Redis 超时 > 500ms → 60 秒纯 L1 运行
1 | const l1 = new Map(); |
这个设计的初衷:本地网络到 Upstash 经常 500ms+ 超时,如果没有降级机制,每次请求都会卡顿 500ms 才走 L1。冷却机制让”Redis 不可用”变成一个自动恢复的状态,而不是每次都要等超时。
负缓存与穿透保护
- 空数组不写缓存(
setJSON过滤[]),避免”本来没数据却缓存了一周” - 负缓存用对象标记:
{ __negative: true, reason: "not-found" },getJSON遇到时返回null - 适用场景:TMDB 404 → 1 小时;share 解析失败 → 3 分钟
没做负缓存之前,有个无效的 imdbid(tt0000000)被反复请求,每次都打 TMDB,五秒一次,日志里刷了上百条 404, no cache。加了负缓存后,1 小时只打一次。
第十部分:调试与可观测性
traceId 贯穿全链路
每个请求进来自动生成 16 位 traceId,通过 AsyncLocalStorage 传递到 logger,所有日志自动带上:
1 | 2026-11-15 03:13:16.089 |
配合响应头 x-trace-id,可以从客户端拿一个 traceId,在服务端日志里 grep 出完整链路。这在排查”为什么这个请求没出流”的时候节省了大量时间。
三个层次的调试
层次 1:/debug/sources —— 各源健康
1 | { "id": "bfzy", "ok": true, "ms": 736, "count": 20 } |
层次 2:/debug/match —— 匹配链路全透明
1 | { |
层次 3:/debug/hls-clean —— 清洗过程 + 源站原始响应
1 | { |
fetchAttempts 是这次 IP 屏蔽问题排查的关键——**没有它,我只能猜”是不是 UA 不对、Referer 不对、还是超时”**。有了它,一眼看出是直连 404、代理 200。
回归测试
写了一个 50+ 项的测试脚本 scripts/regression-test.js,覆盖:
- manifest 结构
- 3 源 × 2 类型的 catalog 搜索
- 内部 id / IMDb id 两种 meta 请求
- 内部 id / IMDb id 两种 stream 请求
- 端到端播放:拉
/hls/clean→ 解析 → 拉第一个 ts 分片 → 验证 200/206 - HLS 清洗:原始大小 / 清洗后大小 / 命中规则
- 调试接口
跑一次 3-5 分钟,能在每次改代码后快速验证没有破坏核心链路。这个投入完全值得——没有它,我可能早就因为某次改动把 catalog 弄挂了还不知道。
第十一部分:数据与实测
耗时(Vercel hkg1 区域)
| 接口 | 耗时 |
|---|---|
catalog 单源搜索 |
500-1200ms |
meta 内部 id |
500-800ms |
meta IMDb 映射(TMDB 命中缓存) |
500-700ms |
stream 内部 id(单源 detail) |
300-800ms |
stream IMDb(三源并行 + 匹配) |
1500-3000ms |
stream IMDb(TMDB 缓存命中 + 三源搜索缓存命中) |
200-500ms |
hls/clean 直连成功 |
800-1800ms |
hls/clean 代理(bfzy) |
1500-4000ms |
stream 通路耗时集中在:TMDB(首次 800ms)+ 三源 search(最慢源 ~1200ms)+ 高置信 detail(500ms)。三源并行已经是 Promise.allSettled,总耗时 ≈ 最慢源。
清洗效果
bfzy《肖申克的救赎》HD 中字:
- 原始:2163 片段
- 清洗后:2136 片段
- 删除 27 个广告片段(1.2%)
- 命中规则:
#EXTINF.*?\s+.*?adjump.*?\.ts
缓存命中率
引入 L1 + L2 后,本地开发时首次冷启动后:
- TMDB 元数据:命中率 > 95%(7 天 TTL)
- 源 search:命中率 > 70%(30 分钟 TTL,同一批测试关键词反复请求)
- 源 detail:命中率 > 80%
- share 解析:命中率 > 60%(3 分钟 TTL,播放器反复拉清单时)
线上因为实例多,L1 命中率低一些,主要靠 L2。Redis 免费额度 500K commands/月,日活几百的用户完全够用。
第十二部分:反思
做对的事
1. 探测先行,不要猜接口
在写 adapter 之前先跑探针脚本,把搜索、详情、分享页、防盗链都摸清楚,然后才写代码。这避免了几次”写完发现字段名不对”的返工。
2. 降级是设计的一部分,不是事后补丁
三层拉取降级、清洗风险降级、Redis 冷却降级——每一层都考虑了”上游不可用”的情况。上线后遇到 IP 屏蔽,因为已经有 307 兜底,服务没完全挂掉。
3. 可观测性从第一天开始
从第一个接口起就带 traceId,从第一个 fetch 起就记录 attempts。后面排查问题时,大部分时间花在”看日志”上,而不是”加日志”上。
4. 保持配置与代码分离
源地址、广告规则、UA、超时——都在 config/*.json 里。后来加了配置页(?cfg=base64url)也不动核心代码。新增源的工作量从”改代码”变成”加两行 JSON”。
做错的事
1. 一开始低估了 Vercel 的”零配置”魔法
花了两天在 api/ 目录、rewrites、入口文件命名上试错。如果一开始就查 “Vercel Express deployment”,官方文档明确说”server.js 在根目录、直接 import express、不要 api 目录”,能省大量时间。
2. 对”源站屏蔽”的认知太晚
线上 404 时,第一反应是”我代码有问题”。如果一开始就知道”数据中心 IP 被国内源站屏蔽”是普遍现象,会更快定位到问题本质。
3. 过度设计了分布式锁
一开始写了 SET NX EX 的分布式锁,但项目里根本没有需要”多实例只执行一次”的场景。加了后没任何地方调用,纯粹是”看到别人写了我也写”。后来删掉了,只保留 Inflight 去重(并发请求同一 key 只穿透一次),才是这个项目真正需要的。
如果重做
- 协议层先用最小可运行版本跑通(
/manifest+/stream+ 硬编码一条流),确认 Stremio 能装、能播,再往上叠功能 - 先做
server.js+vercel dev验证,不要用api/目录 - 探针脚本先跑一周,把每个源的脾气都摸清,再动 adapter
- 调试接口和 health 脚本同步做,不要等”出了问题才加”
结语
这个项目从”想把几个源聚合起来”变成了一个涉及协议、清洗、匹配、缓存、部署、代理的小系统。核心代码量不大(约 4000 行,含配置和测试),但各种踩坑记录比代码本身更长。
最有价值的收获不是”做出了一个能用的 Addon”,而是:
- 面对不确定的外部依赖,先探测再决策
- 降级是必须的,不是可选的
- 可观测性是排查问题的前提,不是奢侈品
- Vercel / Cloudflare 这类平台的”零配置”很好用,但边界行为必须自己踩过才知道
最后,这类项目涉及第三方影视资源,仅用于技术研究。生产环境如果有大量用户访问,带宽成本和合规风险都需要认真评估。
如果你也在做类似的项目,欢迎交流踩坑经验。
*Code: [github.com/…/catvod]*(暂未开源)
Stack: Node.js 18 · Express 4 · Upstash Redis · TMDB API · Vercel · Cloudflare Tunnel
