结论先说：Tube Archivist（8,562 星，GPL-3.0）是目前把「订阅 YouTube 频道、自动下载、可搜索归档、离线播放」串得最完整的一个自托管方案。它用 Docker 一把梭起三个容器——本体、Elasticsearch、Redis，装好后在网页里订阅频道、点下载就行。代价也摆在明处：Elasticsearch 吃内存，小规模测试也要留 2GB，中大型库建议 4GB 起；而且它只负责帮你归档自己有权保存的内容，版权与平台规则的边界得自己守住。
这篇是我按官方 README 与 docker-compose.yml 逐项核对后写的实操：从主机准备、改配置、启动、订阅下载，到最常见的三个坑（vm.max_map_count、Elasticsearch 权限、磁盘写满变只读）。照着走，一台有 Docker 的小主机半小时左右能跑起来。项目单篇介绍见本站：YouTube 订阅太多追不过来？Tube Archivist：8,562 星的自托管媒体库。
Tube Archivist 适合谁？先对一下需求
它解决的是「收藏夹越攒越乱、想找的视频翻不出来」的问题：频道订阅进来后，视频元数据进 Elasticsearch 索引，标题、简介、字幕都能搜；看过没看过有标记；还能建自己的播放列表。如果你只是偶尔存一两个视频，浏览器插件或 yt-dlp 一条命令就够了，不必为它专门起 Elasticsearch。但如果你固定追十几个频道、想长期留档、还想在手机浏览器里随时翻，这个投入就值。
第一步：主机准备，别跳过内核参数
官方要求先装好 Docker。Elasticsearch 在 Docker 里跑，要求宿主机内核参数 vm.max_map_count 至少 262144，没设的话容器起不来、日志里会报相关错误。先执行一次临时设置，再按系统做永久设置：
sudo sysctl -w vm.max_map_count=262144
Ubuntu Server 上把 vm.max_map_count = 262144 写进 /etc/sysctl.conf；Arch 系则新建 /etc/sysctl.d/max_map_count.conf 写同一行。磁盘也要提前留够：Elasticsearch 索引在磁盘占用超过 95% 时会切成只读，要降到 90% 以下才恢复；视频本身更吃空间，先估好频道总量再开下载，别等下到一半才发现盘满了。
第二步：拿官方 compose 文件，改好 6 个必填项
到仓库根目录取 docker-compose.yml（develop 分支当前版），三个服务分别是 tubearchivist（镜像 bbilly1/tubearchivist，端口 8000）、archivist-redis 与 archivist-es（镜像 bbilly1/tubearchivist-es，仅 amd64；其他架构用官方 Elasticsearch 9.5.5 镜像，版本号以 compose 文件里写明的为准）。必填环境变量都在文件里列明了，改下面这几处：
TA_HOST=http://你的主机名或IP:8000 TA_USERNAME=你的初始用户名 TA_PASSWORD=你的初始密码 ELASTIC_PASSWORD=给 Elasticsearch 的密码（两个服务里要填同一个） REDIS_CON=redis://archivist-redis:6379 TZ=Asia/Shanghai
TA_HOST 要写你实际访问的地址（含协议和端口），写错会导致登录后跳转异常。两个密码支持加 _FILE 后缀走 secret 文件传参，公开主机上别把明文密码随手贴到群里。端口冲突时改映射左侧就行，比如 9000:8000 就把界面挪到 9000 端口，容器内端口不动。
第三步：启动，确认三个容器都健康
docker compose up -d docker compose ps docker compose logs -f tubearchivist
第一次启动要拉镜像、等 Elasticsearch 初始化，多等一会儿再打开 http://主机IP:8000。页面底部会显示当前版本号，官方还会在页脚提示新版本：升级只跟一两个版本以内最稳，跨太多版本官方不保证，升级前务必看 release notes 里标出的破坏性变更，新增的环境变量要同步补进 compose 文件。Elasticsearch 权限报错是最常见的拦路虎：日志里出现 Unable to access 'path.repo' 或 failed to obtain node locks，多半是挂载目录的宿主机权限不对，停掉容器后对挂载点执行 chown 1000:0 -R /挂载路径 再启动——1000:0 是容器内 Elasticsearch 进程的 UID/GID。
第四步：先定下载格式，再订阅频道
进设置页，第一件事是把 Download Format 定下来：默认下载最高可用画质；要在 iOS、macOS 或部分浏览器里直接播，得指定兼容格式，官方给的例子是：
bestvideo[vcodec*=avc1]+bestaudio[acodec*=mp4a]/mp4
然后到 Channels 页订阅频道，到 Downloads 页点 Rescan subscriptions，把订阅频道的新视频推进下载队列；也可以点 Add to download queue 手动加视频 ID、链接、频道或播放列表，最后点 Start download。下载完的视频在界面里直接播，已看/未看状态自动记。字幕、SponsorBlock、评论下载这些能力在设置里按需开，别一上来全开，先把主流程跑通。
问：下载失败、有的视频下不下来怎么办？
先分清是 Tube Archivist 的问题还是 yt-dlp 的问题：官方 README 写明了，yt-dlp 下不来的视频，Tube Archivist 也下不来。先看容器日志里的具体报错，再看是不是 age-gated 或需要登录的内容——项目支持把浏览器 cookies 传给 yt-dlp，这类视频先按文档配 cookies 再试。格式问题则回头检查 Download Format：不是所有编码都与所有浏览器兼容，换上面那个兼容格式组合再下一条试。还不行就去仓库 issues 里搜报错原文，这个项目 2021 年建库、2,734 个 commit，常见报错基本都有人踩过。
问：装在 NAS 或 ARM 机器上行吗？
行，但有两个前提。官方文档另有 Unraid、Synology、Podman 的用户指引，群晖、绿联这类 NAS 按文档走 Docker 即可；ARM 机器注意 Elasticsearch 镜像：bbilly1/tubearchivist-es 只提供 amd64，ARM 上改用官方 Elasticsearch 镜像并按 compose 文件里的版本号对齐（当前写明 9.5.5）。内存是硬门槛：2GB 只是小规模测试的起步线，频道一多、索引一大就得往 4GB 以上加，NAS 上先确认内存余量再开。
日常维护：更新、备份、别让它裸奔
更新节奏官方建议至少每月一次，更新后看页脚版本号确认。备份要两手抓：视频文件在 media 卷里，索引与元数据在 Elasticsearch 卷里，只拷视频不备索引，恢复后等于重建；有条件的用 Elasticsearch 快照功能定期备一份。安全上它默认带登录，别把 8000 端口直接暴露到公网；要远程访问就走反向代理加 HTTPS，官方支持转发鉴权（TA_ENABLE_AUTH_PROXY）与 LDAP，家里自用、局域网访问是最省心的姿态。最后提醒一句：只归档自己有权保存、平台规则允许的内容，批量搬运他人频道内容再分发，版权与封号风险都在自己身上。
站长点评：我挑 Tube Archivist 写这篇长文，是因为它把「订阅—下载—检索—播放」做成了一个闭环，而不是又一个只能下载的命令行工具。它的真实成本是 Elasticsearch：内存、磁盘、权限三件事，装之前想清楚，装之后就顺了。先拿一个小频道试跑一周，下载格式、订阅节奏、磁盘增长心里有数了，再把主力频道搬进来。
懒得一步步折腾？这几个工具本站有现成部署包
站长把 n8n、Immich、Stirling-PDF 的部署过程打包好了：docker-compose、一键脚本、中文说明一应俱全，下载解压就能跑，单包 9.9 元、三包合集 19.9 元。