Invidious 技术解读：23.8k star 的 YouTube 替代前端，为什么三年了还杀不死

2018 年 8 月，开发者 Omar Roth 在 GitHub 上传了第一个版本的 Invidious。这个用 Crystal 语言写的网页应用提供了一件事：换一个界面看 YouTube，页面里没有广告、没有追踪脚本，订阅列表和播放历史存在你自己的服务器上，而不是 Google 的数据库里。八年后的现在，这个仓库有 23819 颗 star，仍然在按月发版。

它到底是什么

Invidious 是一个开源（AGPLv3 协议）的 YouTube「替代前端」。所谓替代前端，就是一个自己搭的网页界面，部署在你控制的服务器上，界面背后仍然读取 YouTube 的视频和元数据。它不调用 YouTube 官方 API，而是直接抓取网页解析出数据，官方称这套抓取层为 Invidious Developer API。

对使用者来说，它的能力清单如下：无广告、无追踪、注册不需要 Google 账号、订阅与播放记录存在实例自己的数据库里、不依赖 JavaScript 也能播放（DASH 高清流除外）、自带 RSS 输出、界面支持包括简体中文在内的几十种语言。Freetube、Yattee 等开源客户端，以及大量「自动重定向」类隐私插件，都把 Invidious 实例当作默认数据源。

Invidious 播放器界面

这个项目最特别的经历发生在 2023 年 6 月。YouTube 法务团队向 Invidious 核心开发者 Samantaz Fox 发出函件，要求 7 天内下架项目。开发者在 issue #3872 里公开了全文，并给出了拒绝的理由：Invidious 从未同意过 YouTube 的服务条款，也没有使用官方 API，函件引用的 API 服务条款对本项目并不适用。随函公布的还有一条后路：万一 GitHub 仓库被平台下架，代码有完整的 Gitea 镜像（gitea.invidious.io），项目可以继续。三年过去，仓库还在原地，2026 年 8 月 5 日发布了 v2.20260804 版本，8 月 28 日仍有代码合入。

那次法律行动的背景，是 YouTube 在 2023 年 5 月启动的「广告拦截器实验」：检测到浏览器开广告拦截就限制播放。平台收紧第三方访问的同一时期，Reddit 也在对第三方客户端收取高额 API 费用，Apollo 等客户端因此关停。Invidious 的应对方式是把鸡蛋分散：官方文档主推自托管，任何人都可以在自己服务器上跑一套完整实例，公共实例挂了不影响私有部署。

当前的架构：三个容器

invidious 本体是一个 Crystal 语言的 Web 应用，负责界面渲染、用户账号、订阅数据。它把视频播放里最麻烦的部分剥离给了独立组件 invidious-companion：一个基于 youtubei.js 的服务，专门处理 YouTube 内部接口的请求签名和 PO Token 获取，这两样是 2024 年以来 YouTube 反爬升级后绕不开的环节。数据层是 PostgreSQL 14，存用户、订阅、播放列表。

Invidious 订阅页界面

镜像发布策略有一个细节：官方镜像只发在 Quay（quay.io/invidious/invidious），不发 Docker Hub，理由写在文档第一行——Quay 本身是开源软件，Docker Hub 不是。生产环境的 docker-compose 拉起三个服务：

yaml

services:
  invidious:
    image: quay.io/invidious/invidious:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      INVIDIOUS_CONFIG: |
        db:
          dbname: invidious
          user: kemal
          password: kemal
          host: invidious-db
          port: 5432
        check_tables: true
        hmac_key: "自动生成的密钥"
        invidious_companion_key: "另一个密钥"

  companion:
    image: quay.io/invidious/invidious-companion:latest
    environment:
      - SERVER_SECRET_KEY=与上面配套的密钥
    cap_drop:
      - ALL
    read_only: true
    security_opt:
      - no-new-privileges:true

  invidious-db:
    image: docker.io/library/postgres:14

companion 容器以 drop 所有 Linux capabilities、只读文件系统、禁止提权的方式运行，这是自托管服务里少见的严格配置。companion 需要访问 YouTube 内部接口拿签名，这一步在一个权限最小化的沙箱里完成，Web 层的数据库凭据对它不可见。

自托管时的关键配置项集中在 config.example.yml（1045 行，每项都有注释）：domain 和 https_only 在反向代理终结 TLS 的部署里必须填写，否则会话 cookie 静默失效，表现为无法登录、无法保存偏好；external_port 在监听 3000 但对外是 443 时要设为 443；registration_enabled 控制是否开放注册，公开实例通常关掉；默认界面语言和内容地区在 default_user_preferences 段设置。

隐私的边界在哪里

「无追踪」的准确边界值得拆开看。Invidious 自身不收集用户数据，实例日志默认只记 URL、状态码和响应耗时。但视频流默认直接从 Google 的 CDN（googlevideo.com）拉取，意味着 Google 能看到你的 IP 和浏览器特征。不想暴露的话，在偏好设置里打开「Proxy videos」，实例会充当中继，你的 IP 对 Google 不可见，代价是实例的出口带宽。

换句话说，这个项目隔离的是 Google 的账号体系和行为画像（看什么、什么时候看、看多久）；IP 层面的可见性默认仍然存在，需要靠实例中继来消除。选择公共实例等于把信任交给实例管理员，因为管理员技术上可以记录访问来源；选择自托管则把这份信任收回到自己手里，这也是项目文档反复强调自托管的原因。

公共实例生态的现实

官方 API（api.invidious.io/instances.json）当前列出 11 个实例，其中 7 个以 HTTPS 正常服务，uptime 在 97% 到 100% 之间。这个数字说明了这个生态的两种现实：一方面，活跃公共实例只剩个位数，字幕功能在热门实例上经常损坏，原因是 Google 对字幕接口限流；另一方面，列表里的实例大多稳定运行一年以上，inv.nadeko.net 这类实例的 uptime 是 99.35%。

功能上也有限制：480p 以上的画质（DASH 流）需要 JavaScript 且默认关闭，因为 DASH 必须经过实例代理，带宽成本高；音乐 MV 类内容常被 Google 按地区限制，需要开代理模式或换实例。这些边界在官方 FAQ 里写得直白，不承诺全能。

为什么它还活着

一个 2023 年被平台法务点名、创始人 2020 年就退出的项目，至今保持月度发版，靠的是三件事：不碰官方 API 的技术路线让下架令失去了最直接的抓手；AGPLv3 加 Gitea 镜像让代码无法被真正消灭；自托管优先的架构让「封禁公共实例」打不死私有部署。9 月 2 日，这个仓库单日新增 577 颗 star。

对想部署的读者，官方文档 docs.invidious.io 的安装页给了完整的三容器 compose 文件，一条 docker compose up 就能跑起来。对只是想用的人，instances.invidious.io 列着当前可用的公共实例。视频内容、推荐算法、创作者生态都在 Google 手里，Invidious 换掉的只有入口这一层：一个不登录 Google 账号、不被记录行为画像的观看方式。这个入口八年前是可选的，现在依然可选。

来源：Invidious GitHub 仓库 · issue #3872: YouTube legal team contacted us · Invidious 官方文档 · Wikipedia: Invidious