一、LibreTV 是什么？为什么你需要自己搭一个

入门

LibreTV 是一个免费开源的在线影视搜索与观看平台。你可以把它理解成一个「视频聚合搜索页」——它自己不生产内容，而是帮你把散落在各个视频网站的资源聚合在一起，输入片名就能直接搜索并播放，全程无需注册登录。

有人可能会问：网上现成的影视站那么多，为什么还要自己搭一个？原因很简单：第三方站点随时可能关停、跑路或被屏蔽。自己部署一个，相当于把「搜索工具」掌握在自己手里，数据在自己名下，访问地址由自己控制，稳定性和安全性都更有保障。

本教程会带你从零开始，走完部署、配置、使用的完整流程。全程不需要写代码，跟着操作即可。

需要提前说明的是：LibreTV 仅供个人学习和研究使用。项目作者明确要求部署者必须设置访问密码（PASSWORD），且不得将实例用于商业用途或公开分享。请遵守这些要求。

二、部署前的准备工作

入门

在动手之前，你需要准备两样东西：

1. 一个 GitHub 账号：LibreTV 的代码托管在 GitHub 上，部署时需要把你的仓库和部署平台关联起来。注册是免费的，网址是 github.com。
2. 一个部署平台账号：推荐使用 Vercel（vercel.com），它对个人开发者免费额度足够用，而且部署过程几乎全自动。也可以用 Cloudflare Pages 或 Docker，后面会分别介绍。

这两样都不需要花钱，也不需要你有编程基础。整个过程就像「把一份现成的菜谱交给厨师去做」——你只需要提供原料（代码仓库）和厨房（部署平台），剩下的交给平台自动完成。

三、方式一：Vercel 一键部署（推荐新手）

入门

Vercel 是一个网站托管平台，你只需要把代码仓库交给它，它会自动完成构建、部署和域名分配。整个过程只需要点几下鼠标。

第一步：Fork 代码仓库

打开 LibreTV 的 GitHub 仓库（github.com/LibreSpark/LibreTV），点击页面右上角的 Fork 按钮，把项目复制到自己的 GitHub 账号下。

第二步：导入 Vercel

登录 Vercel 后，点击 Add New > Project，然后选择你刚才 Fork 的 LibreTV 仓库，点击 Import。

第三步：设置密码变量

这一步最关键。在 Vercel 的项目配置页面，找到 Environment Variables（环境变量）区域，添加一个变量：

• Key 填写：PASSWORD
• Value 填写：你自己设定的一串密码，比如 mypassword123

这个密码是访问你的影视站时必须输入的，相当于你给网站加了一把锁。

第四步：点击 Deploy 部署

点击 Deploy 按钮，等待 1-2 分钟，Vercel 会自动完成所有构建工作。部署完成后，Vercel 会给你分配一个免费的域名，格式类似 libretv-xxxx.vercel.app。

部署完成后，打开分配的域名，输入你设置的密码，就能看到 LibreTV 的搜索界面了。

四、方式二：Docker 部署（适合有服务器用户）

进阶 · 推荐细读

如果你已经有一台云服务器，用 Docker 部署会更灵活——数据完全掌控在自己手里，不依赖第三方平台。

前置条件：需要一台能联网的 Linux 服务器（如 Ubuntu、Debian），并且已经安装好 Docker（一种把软件打包成「集装箱」、随处可运行的工具）。如果你还没装 Docker，可以在服务器上执行：

curl -fsSL https://get.docker.com | sh

安装完成后，执行下面的命令启动 LibreTV：

docker run -d \
  --name libretv \
  --restart unless-stopped \
  -p 8899:8080 \
  -e PASSWORD=your_password \
  bestzwei/libretv:latest

这条命令的意思是：从 Docker 镜像仓库拉取 LibreTV 的镜像，在后台运行，把容器的 8080 端口映射到服务器的 8899 端口，并设置访问密码为 your_password（请改成你自己的密码）。

启动后，在浏览器里访问 http://你的服务器IP:8899，输入密码即可使用。

如果你更喜欢用 Docker Compose（一种通过配置文件批量管理多个容器的工具），可以创建一个 docker-compose.yml 文件，内容如下：

services:
  libretv:
    image: bestzwei/libretv:latest
    container_name: libretv
    ports:
      - "8899:8080"
    environment:
      - PASSWORD=your_password

然后在同一目录下执行 docker compose up -d，效果和上面的 docker run 命令完全一样。

注意：--restart unless-stopped 参数很关键，它保证服务器重启后 LibreTV 会自动跟着启动，省去手动操作的麻烦。

五、配置详解：密码、端口和数据持久化

进阶 · 推荐细读

LibreTV 的配置项不多，核心就一个：PASSWORD 环境变量。但有几个细节值得留意。

PASSWORD 变量

这是唯一必须设置的变量，也是项目的安全底线。如果你不设置它，LibreTV 会拒绝启动或无法正常使用。密码建议设置得复杂一些，至少 8 位以上，包含字母和数字。

端口映射

在 Docker 部署中，-p 8899:8080 表示把容器内部的 8080 端口暴露到服务器的 8899 端口。如果你服务器上 8899 端口已经被占用，可以改成其他端口，比如：

-p 9000:8080

改完后访问地址就变成 http://你的服务器IP:9000。

数据持久化

LibreTV 本身不存储用户数据，所以不需要挂载数据卷。但如果你后续想备份配置，可以在设置页面里手动导出备份。

六、功能导览：搜索、播放与设置

入门

部署完成后，打开你的 LibreTV 网址，输入密码进入主界面。整体界面非常简洁，核心功能就三个：

1. 搜索影视

在首页的搜索框里输入片名，点击搜索，LibreTV 会从多个视频源同时检索，展示可播放的结果列表。整个过程通常只需要几秒钟。

2. 在线播放

点击搜索结果，页面会跳转到播放器界面。播放器支持常见的视频格式，也支持切换清晰度和播放速度。如果某个视频源失效了，可以返回搜索结果，换一个源试试。

3. 个性化设置

在设置页面里，你可以调整界面主题、默认播放源、搜索语言等参数。设置完成后记得点击保存。

七、常见问题排查

进阶 · 推荐细读

1. 部署后打开页面是空白或报错

最常见的原因是 PASSWORD 变量没有设置成功。请回到部署平台的设置页面，确认环境变量里确实有 PASSWORD 这一项，并且值不是空的。

2. 页面能打开，但搜索不到结果

这通常是视频源暂时不可用导致的。建议先清除浏览器 Cookie，然后按 Ctrl + F5（Windows）或 Command + Shift + R（Mac）强制刷新页面，再试一次。

3. 想换一个域名访问

Vercel 分配的默认域名是 xxx.vercel.app。如果你有自己的域名，可以在 Vercel 的项目设置里添加自定义域名，并按照提示配置 DNS 解析记录。

4. 如何更新到最新版本

如果你用的是 Vercel 部署，在 Fork 的仓库里点击 Sync fork 按钮，把主仓库的更新同步过来，Vercel 会自动检测到变更并重新部署。用 Docker 部署的话，执行：

docker pull bestzwei/libretv:latest
docker restart libretv

八、运维进阶：绑定域名与自动同步

深入 · 老手可选

绑定自定义域名

如果你有自己的域名，建议绑定到 LibreTV 上，这样访问地址更专业也更好记。在 Vercel 的 Settings > Domains 里添加你的域名，然后去你的域名服务商后台，添加一条 CNAME 解析记录，指向 Vercel 分配的地址。

开启自动同步

LibreTV 项目更新比较频繁，为了及时获取新功能和修复，建议在你 Fork 的仓库里启用 GitHub Actions 自动同步功能。项目自带了一个同步配置文件（.github/workflows/sync.yml），你只需要在 GitHub 仓库的 Actions 页面确认它处于启用状态即可。

提醒：项目作者明确表示会拉黑所有通过 Pull Bot 自动发起同步请求的账号，所以不要用第三方同步工具，直接用项目自带的 Actions 就好。

日常备份

LibreTV 本身不存用户数据，所以备份需求不大。但如果你在设置里做了个性化配置，可以在设置页面导出备份文件，存到本地或网盘，方便以后恢复。

到这里，你已经完成了 LibreTV 从部署到日常维护的全部流程。整个过程真正需要动手的地方其实只有两步：设置密码和点击部署。剩下的交给平台就好。如果在使用中遇到其他问题，不妨先去项目仓库的 Issues 页面搜一搜，大部分问题都有人遇到并解决过了。

项目信息

参考链接

• GitHub 仓库
• 项目主页

延伸阅读

想继续探索？这些同领域的教程可能也适合你：

• 「server」中文使用教程