WangQiFei

Keefer


思想提纯
  • 首页
  • 归档
  • 标签
  • 关于
  •     

© 2026  by  Wangqifei

用 Stremio 做一个自己的影视聚合 Addon:从想法到线上的完整复盘

发布于 2026-11-16 02:11 stremio 

用 Stremio 做一个自己的影视聚合 Addon:从想法到线上的完整复盘

记录一个历经迭代十余轮、被各种”玄学问题”折磨的技术项目。
涉及 Node.js / Stremio Addon 协议 / HLS 清洗 / Vercel 部署 / IP 屏蔽与代理降级。


缘起

在用 Stremio 看片的时候,总是要装好几个第三方 Addon 才能覆盖想看的资源。Cinemeta 提供 IMDb 元数据但没有国内源,一些小众 Addon 只接一两个站点。如果一个 Addon 能把暴风、非凡、量子这些都聚合起来,并且能在 Cinemeta 的影片页直接出流,会省不少事,后续可以追加更多源,具有相当的通用性。

于是有了这个项目:CatVod Multi-Source,一个多源聚合的 Stremio Addon。

最初的设想很简单:

  1. 每个源独立 catalog,用户能直接搜
  2. 在 Cinemeta 页面点某一集,Addon 自动去各源找对应资源
  3. 源站的 m3u8 里插了广告,顺手洗掉

却着实遇到很多坑,尤其是后期还遇到ip被屏蔽的问题,不得以自建hls-proxy来解决。


第一部分:先把协议啃透

Stremio Addon 协议本身不难,但它有几个坑点是文档里没写清楚、必须踩过才知道的。

manifest 里的 resources 有两种形式

1
"resources": ["catalog", "meta", "stream"]

和:

1
2
3
4
5
"resources": [
"catalog",
"meta",
{ "name": "stream", "types": ["movie", "series"], "idPrefixes": ["tt"] }
]

第一种是简写,第二种是”高级形式”,可以为每个 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
2
3
4
"extra": [
{ "name": "search", "isRequired": false },
{ "name": "skip", "isRequired": false }
]

坑点:catalog id 是 bfzy-series,但实际请求路径是 /catalog/series/bfzy-series/search=xxx.json,id 段里带 /。Express 4 的 /:id.json 只匹配单段,匹配不到,会 404。必须用正则路由:

1
2
3
4
5
6
app.get(/^\/catalog\/(movie|series)\/(.+)\.json$/, async (req, res) => {
const type = req.params[0];
const idPart = req.params[1]; // "bfzy-series/search=庆余年"
const [id, ...extraParts] = idPart.split("/");
// ...
});

这个 bug 我调了半天,一直以为是自己路由写错了,最后看了 Stremio 的实际请求才发现原因。

剧集的 video id 格式

电影直接是 tt1234567,但剧集的 stream 请求是 tt1234567:2:5(季:集)。解析时:

1
2
3
4
5
6
7
8
9
10
11
function parseStreamId(id) {
const parts = String(id).split(":");
if (parts.length >= 3) {
const a = parts[parts.length - 2];
const b = parts[parts.length - 1];
if (/^\d+$/.test(a) && /^\d+$/.test(b)) {
return { baseId: parts.slice(0, -2).join(":"), season: Number(a), episode: Number(b) };
}
}
return { baseId: id, season: null, episode: null };
}

一开始我只做了 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
2
3
bfzy: itemKeys = [vod_id, vod_name, vod_year, vod_pic, type_name, ...]  ← 全
ffzy: itemKeys = [vod_id, vod_name, type_name, vod_remarks] ← 严重裁剪
lz: itemKeys = [vod_id, vod_name, vod_year, vod_pic, ...] ← 全

结论:搜索只能用于候选定位,所有完整信息必须走 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
2
const URL_VAR_RE = /(?:const\s+url|url)\s*=\s*["']([^"']+?\.m3u8[^"']*)["']/;
// 提取 share 页面里的 m3u8 路径

季集信息不在结构字段里

MacCMS 原生没有独立的 vod_season / vod_episode 字段,季集信息全在标题里:vod_name = "庆余年第二季粤语",分集标题 第01集。

所以内部模型的 season / episode 必须从标题解析:

1
2
// "庆余年第二季粤语" → { baseName: "庆余年", season: 2, lang: "粤语" }
// "第01集" → { episode: 1 }

匹配打分时 baseName 参与标题相似度,season 参与季匹配。如果把”粤语”这种后缀也算进标题,相似度会莫名其妙地变低。


第三部分:匹配打分器

通路 2 的核心是匹配:TMDB 给中文元数据,各源返回一堆候选,怎么判断哪条是对的?

相似度算法

字符 bigram Dice 系数。比 Levenshtein 更适合中文短字符串,因为不用考虑编辑操作顺序。

1
2
3
4
5
6
7
8
9
10
11
12
13
export function diceSimilarity(a, b) {
if (!a || !b) return 0;
if (a === b) return 1;
const bigrams = (s) => {
const set = new Set();
for (let i = 0; i < s.length - 1; i++) set.add(s.slice(i, i + 2));
return set;
};
const A = bigrams(a), B = bigrams(b);
let inter = 0;
for (const x of A) if (B.has(x)) inter++;
return (2 * inter) / (A.size + B.size);
}

权重设计

1
2
3
4
5
6
7
8
9
10
11
12
const DEFAULT_WEIGHTS = {
title: 0.5, // 标题相似度
year: 0.2, // 年份强校验
type: 0.1, // 电影/剧集类型
season: 0.2, // 季匹配
aliasBonus: 0.1, // 多别名且标题相似度 > 0.7 时加分
};

const DEFAULT_THRESHOLDS = {
high: 0.85, // 直接返回
medium: 0.60, // 返回候选
};

测试用例:

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
2
3
4
5
6
#EXT-X-DISCONTINUITY
#EXTINF:3.000000
https://xxx.com/adjump/001.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.4
https://xxx.com/0000001.ts ← 正常分片

广告被”切”成一个独立的 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
2
3
4
5
6
7
8
9
10
11
12
export function compileRule(raw) {
const s = String(raw).trim();
if (/^\d+(?:\.\d+)?$/.test(s)) {
const esc = s.replace(/\./g, "\\.");
return new RegExp(`#EXTINF:\\s*${esc}[^\\n]*\\n[^\\n]*(?:\\n|$)`, "g");
}
if (s.startsWith("#") || /[\\*+?()[\]{}|^$]/.test(s)) {
return new RegExp(s, "g");
}
const esc = s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
return new RegExp(`#EXTINF[^\\n]*${esc}[^\\n]*\\n[^\\n]*(?:\\n|$)`, "g");
}

三层保护

清洗有个隐患:正则写得太激进会误删正常片段,用户看到的视频会变短、跳帧。

所以加了风险检测:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const DEFAULT_HLS_CONFIG = {
maxReduction: 0.3, // 片段减少 > 30% → 高风险
maxHits: 50, // 命中 > 50 条 → 中风险
};

export function detectRisk(original, cleaned, hits, config) {
const before = countSegments(original);
const after = countSegments(cleaned);
if (before === 0) return { risk: "low" };
if (after === 0) return { risk: "high", reason: "all-removed" };
const reduction = (before - after) / before;
if (reduction > config.maxReduction) {
return { risk: "high", reason: `reduction=${(reduction * 100).toFixed(1)}%` };
}
return { risk: "low" };
}

高风险时原样返回原始清单(只做绝对化不删片段),至少能播。

master playlist 递归

部分源(量子、非凡)返回的是 master m3u8:

1
2
3
#EXTM3U
#EXT-X-STREAM-INF:PROGRAM-ID=1,BANDWIDTH=800000
2000k/hls/mixed.m3u8

子清单是相对路径。如果不处理,播放器拉子清单时就绕过了我们的清洗。

所以 master 的每个子清单入口都要改写为 /hls/clean:

1
2
3
const params = new URLSearchParams({ url: abs.href });
if (sourceId) params.set("src", sourceId);
out.push(`${addonBaseUrl}/hls/clean?${params.toString()}`);

关键细节:父清单的 query(?sign=xxx)必须继承到子清单,否则子清单可能 403。

不中转分片

这是整个项目的核心约束:只改 m3u8 清单,ts 分片绝对化后播放器直连源站。

好处:

  • 服务器不需要承担分片流量
  • 广告清洗只发生一次(拉清单时)
  • 播放体验接近直连

代价:

  • 分片层的防盗链无法处理(需 Referer/UA 的分片,播放器带不了)
  • 一旦清单拉不到,整条流就废了(后面第五部分会讲怎么降级)

第五部分:Vercel 部署的至暗时刻

本地跑得好好的,部署到 Vercel 后 /manifest.json 返回 404。然后是三天的拉锯战。

坑 1:入口文件被自动探测混淆

Vercel 对 Express 应用有零配置检测。它按字典顺序找入口:

1
2
app.js / index.js / server.js / main.js
以及 src/ 下的同名变体

一开始我把入口放在 api/index.js,Vercel 不认识。改成 src/app.js(导出工厂函数 createApp),Vercel 选它了但又报 Can't detect way to handle request——它要的是”导出的 app 实例”,不是工厂函数。

最终的解法:在项目根目录建 server.js,**直接 import express**:

1
2
3
4
5
import express from "express";
import { createApp } from "./src/createApp.js";

const app = createApp();
export default app;

即使 createApp 内部也 import 了 express,入口文件本身必须有这一行——Vercel 是靠扫描入口文件文本来判断是不是 Express 应用的。

坑 2:vercel.json 的 rewrites 是个陷阱

看了很多教程说要用 rewrites 把请求转发到 api/index:

1
2
3
4
5
{
"rewrites": [
{ "source": "/(.*)", "destination": "/api/index" }
]
}

配合 api/index.js(Express 应用塞进去)看起来能工作。但本地 vercel dev 会报 NO_RESPONSE_FROM_FUNCTION,反复试都不行。

最后发现新版的 Vercel 支持零配置 Express 应用,根本不需要 rewrites。server.js 放在根目录、vercel.json 里只留 functions.includeFiles 就够了:

1
2
3
4
5
6
7
{
"functions": {
"server.js": {
"includeFiles": "config/**,public/**"
}
}
}

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
2
3
4
5
const PUBLIC_DIR = path.resolve(__dirname, "../public");
app.use(express.static(PUBLIC_DIR, { index: false }));
app.get("/configure", (_req, res) => {
res.sendFile(path.join(PUBLIC_DIR, "configure.html"));
});

这样本地和线上行为一致,不用再纠结 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
2
curl -A "Mozilla/5.0 ..." -e "https://bfzyapi.com/" "https://p.bvvvvvvvvv1f.com/..."
# → 200

本地 200,服务端 404,请求头完全一致。结论:Vercel 的出站 IP 被源站屏蔽了。

而且是伪装成 404 的屏蔽(而不是 403),源站假装”资源不存在”,比”拒绝”更隐蔽。

验证数据中心 IP 被广泛屏蔽

试了几个方案:

  1. Cloudflare Worker 代理:部署了 MHSanaei/HLS-Proxy-Worker,请求同一个 m3u8,也是 404。
  2. Vercel 换 Region:从 iad1 换到 hkg1(香港),还是 404。
  3. 住宅 IP 代理:成功。但成本高($10-50/月),不适合个人项目。

结论:源站屏蔽的是”数据中心 IP 段”这个大类,Vercel、Cloudflare、AWS 都在名单里。只有住宅 IP(家宽出口)能过。


第七部分:三层降级——把”IP 屏蔽”变成工程问题

在找到最终方案之前,先做的是降级:如果清单拉不到,不要返回空清单(用户看到黑屏),而是307 重定向到原始 URL,让播放器直连源站。

1
2
3
4
5
if (r.type === "error") {
res.set("X-HLS-Degraded", "1");
res.set("X-HLS-Error", String(r.reason || "fetch-failed").slice(0, 200));
return res.redirect(307, String(url));
}

如果分片层没被屏蔽,用户可能还能播放(虽然广告没过滤);如果分片也被屏蔽,播放器直接报错,比”能加载但黑屏”体验更清晰。

最终方案:自建清单代理

找到的关键洞察是:代理只需要拉清单,分片仍然直连源站。

  • 清单一共 200KB,每天请求量也不大
  • 分片是几百 GB 的流量,绝对不能走代理
  • 源站屏蔽的是”清单接口”,分片接口对数据中心 IP 是放行的

于是做了一个极简代理服务(部署在家里的宽带出口 + Cloudflare Tunnel):

1
GET https://hls.wangqifei.eu.org/m3u?url=<encoded>&referer=<...>&ua=<...>

代理收到请求后:

  1. 从家宽出去拉源站 m3u8
  2. 把 ts 相对路径转成绝对 URL
  3. 原样返回 m3u8 文本

项目里改 fetchManifest.js,加了一层代理优先:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
async function tryFetchStage({ targetUrl, requestHeaders, stage, ... }) {
// 尝试拉取,返回 { ok, text }
}

export async function fetchManifestWithMeta(url, opts) {
// 第 1 层:直连
const direct = await tryFetchStage({ targetUrl: url, stage: "direct", ... });
if (direct.ok) return { ok: true, text: direct.text, viaProxy: false };

// 第 2 层:代理
if (USE_PROXY) {
const proxy = await tryFetchStage({
targetUrl: buildProxyUrl(url, { ua, referer }),
stage: "proxy", ...
});
if (proxy.ok) return { ok: true, text: proxy.text, viaProxy: true };
}

// 第 3 层交给路由层:307 重定向
return { ok: false, text: null, attempts };
}

为什么直连优先,而不是代理优先?

  • 不是所有源都屏蔽 Vercel。ffzy、lz 直连是通的。
  • 代理多一跳只会增加延迟。
  • 代理资源应该作为”救援层”,只在直连失败时使用。

为什么不双保险(既传 query 也传 HTTP 头)?

代理接口约定是 ?ua=...&referer=...,通过 query 传。如果同时传 HTTP 头,代理可能优先用 HTTP 头,导致 Referer 变成 https://hls.wangqifei.eu.org/...(源站看到的 Referer 是代理域名),反而 403。单一渠道更干净。

完整链路

1
2
3
4
/hls/clean
├─ 直连源站 → 200 → 返回(ffzy / lz)
├─ 直连失败 → 代理 → 200 → 返回(bfzy)
└─ 代理也失败 → 307 重定向(保底让播放器直连原始 URL)

每一层的尝试(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
2
3
4
5
def filter_ads(text: str) -> str:
# Master m3u8 直接跳过,避免误删子清单
if '#EXT-X-STREAM-INF' in text or '#EXT-X-MEDIA:' in text:
return text
...

两行代码,零开销,把一类可能毁掉整条流的误伤彻底规避。如果这个判断要等上线后被用户投诉才发现,代价会大得多。

全量 URI 重写:被忽略的 KEY 和 MAP

代理最容易挂的地方不是清洗逻辑,而是重写不完整。最初的实现只处理了”分片行”,对其他行一律按注释保留:

1
2
3
4
if s.startswith('#'):
out.append(line) # ← 问题在这里
else:
out.append(rewrite_uri(s, base_url))

结果就是:

1
2
#EXT-X-KEY:METHOD=AES-128,URI="key.bin"
#EXT-X-MAP:URI="init.mp4"

这两行里的 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
2
3
4
5
6
def rewrite_uri(uri, base_url):
abs_uri = urljoin(base_url, uri)
parts = urlsplit(abs_uri)
safe_path = quote(parts.path, safe="/%") # ← 关键
return urlunsplit((parts.scheme, parts.netloc, safe_path,
parts.query, parts.fragment))

quote 的 safe 参数里包含 %,已经编码过的路径不会被二次编码;中文则统一转成 %E7%AC%AC01%E9%9B%86。重写后整份清单纯 ASCII,无论播放器用什么编码解析,结果都一致。

Referer 兜底:一个便宜但有效的兼容层

CatVod 里的 Referer 是精确配置的,因为面对的源站已知。HLS Clean 面对未知源站,用户不传 Referer 就是不带,源站只要校验 Referer 就 403。

所以加了一条自动兜底:用户未显式传 Referer 时,用 m3u 地址本身的 scheme://host/ 作为 Referer。

1
2
3
4
if not has_referer and target_url:
parts = urlsplit(target_url)
if parts.scheme and parts.netloc:
final["Referer"] = f"{parts.scheme}://{parts.netloc}/"

这个兜底的命中率不低。大部分防盗链的校验逻辑是”Referer 必须来自本站或同域”,用源站自己的 origin 通常能过。比起让用户每次手动填 Referer,这条兜底至少能让大部分源站默认可用。少数要求特定站点作为 Referer 的,用户再显式传 &referer= 覆盖即可。

保活:无 systemd 环境下的 pm2 约束

HLS Clean 跑在 Bohrium 科研云的容器里,2C 4G,Ubuntu 22.04,没有独立公网 IP,也没有 systemd。对外暴露靠 Cloudflare Tunnel:

1
2
3
4
5
6
7
8
9
10
11
12
13
Stremio / 浏览器
│ HTTPS
▼
https://hls.wangqifei.eu.org
│ Cloudflare 边缘
▼
cloudflared(容器内,pm2 守护)
│ http://localhost:50001
▼
server.py(Python 标准库,零依赖)
│ HTTPS(自动带 UA + 兜底 Referer)
▼
上游 m3u8

两个进程都交给 pm2 管理,容器重启后 pm2 resurrect 一条命令恢复。但这里踩过一个挺隐蔽的坑。

cloudflared 最初是用 bash -c "cloudflared tunnel run ..." 包装启动的。pm2 的重启计数悄悄涨到了 276——看起来像是 cloudflared 在崩溃重启,但日志里什么都看不到。原因是新版 cloudflared 对 edge-ip-version 的类型校验变严(要求字符串,YAML 里裸写 4 会被解析成整数),进程启动即退出;而 bash -c 的包装层让这个错误没被 pm2 捕获,pm2 只能看到”进程退出”,看不到”为什么退出”。

修复涉及两件事:

  1. 把 YAML 里的 edge-ip-version: 4 改成 edge-ip-version: "4"
  2. 把 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
const l1 = new Map();
let redisFailCount = 0;
let redisCooldownUntil = 0;

async function getJSON(key) {
const l1Hit = l1Get(key);
if (l1Hit !== null) return l1Hit;

if (redisAvailable()) {
try {
const v = await withTimeout(upstash.get(key), 500);
recordRedisOk();
if (v !== null) { l1Set(key, v, 60); return v; }
} catch (e) {
recordRedisFail();
}
}
return null;
}

这个设计的初衷:本地网络到 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 [INFO] [req:a9b2d6] [stream] imdb tt27995113 → bfzy hit "黑鸽第一季" score=1

配合响应头 x-trace-id,可以从客户端拿一个 traceId,在服务端日志里 grep 出完整链路。这在排查”为什么这个请求没出流”的时候节省了大量时间。

三个层次的调试

层次 1:/debug/sources —— 各源健康

1
{ "id": "bfzy", "ok": true, "ms": 736, "count": 20 }

层次 2:/debug/match —— 匹配链路全透明

1
2
3
4
5
6
7
8
9
10
11
{
"meta": { "name": "肖申克的救赎", "year": "1994" },
"candidates": {
"bfzy": {
"ranked": [
{ "vod_name": "肖申克的救赎", "score": 0.9, "level": "high",
"breakdown": { "title": 1, "year": 1, "type": 0, "season": 0.5 } }
]
}
}
}

层次 3:/debug/hls-clean —— 清洗过程 + 源站原始响应

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"type": "media",
"originalSegments": 706,
"cleanedSegments": 688,
"hits": [{ "rule": "#EXTINF.*?adjump", "removed": 18 }],
"fetchAttempts": [
{
"stage": "direct",
"request": { "headers": { "User-Agent": "...", "Referer": "..." } },
"response": { "status": 404, "bodyHead": "<html>404 Not Found</html>" }
},
{
"stage": "proxy",
"response": { "status": 200 }
}
]
}

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”,而是:

  1. 面对不确定的外部依赖,先探测再决策
  2. 降级是必须的,不是可选的
  3. 可观测性是排查问题的前提,不是奢侈品
  4. Vercel / Cloudflare 这类平台的”零配置”很好用,但边界行为必须自己踩过才知道

最后,这类项目涉及第三方影视资源,仅用于技术研究。生产环境如果有大量用户访问,带宽成本和合规风险都需要认真评估。

如果你也在做类似的项目,欢迎交流踩坑经验。


*Code: [github.com/…/catvod]*(暂未开源)
Stack: Node.js 18 · Express 4 · Upstash Redis · TMDB API · Vercel · Cloudflare Tunnel

Visitors

 

下一篇: 飞智 冰原狼2手柄使用说明 

© 2026  by  Wangqifei