折腾AList和小雅这套东西前前后后不下七八次每次换机器、换环境都要重新过一遍流程。这次趁着换了一台性能更好的小主机把完整的安装过程重新梳理了一遍从零开始一直到能正常看电影、听音乐所有步骤都实测跑通。这篇记录就当是给自己留个备份也给正在纠结AList和小雅怎么装的朋友一条能直接照抄的路子。先简单交代一下背景免得有人看晕。AList是一个开源的多网盘文件列表程序可以把你分散在阿里云盘、夸克网盘、百度网盘、OneDrive等地方的资源统一挂载到一个网页目录里通过统一接口管理和访问。小雅则是社区里对xiaoyaliu/alist这个docker镜像的俗称它基于AList做了大量预配置内置了各类网盘资源的聚合目录拉起来就能用省去了自己一个个找资源、配挂载的麻烦。两者配合起来等于在自己服务器上搭了一个私人媒体资源总入口。这套方案适合谁适合家里有NAS或小主机、想把自己散落在各个网盘里的资源集中管理的人也适合想给家人搭一个能直接点开就播的影视库的人。不需要太高的技术门槛懂一点Linux命令、会复制粘贴跟着步骤走基本都能跑通。1. 项目概述与方案选型思考1.1 先搞清楚AList和小雅分别是什么AList本质上是一个文件列表服务它不存储文件本身只负责把各种存储后端统一成一套可视化的目录结构。你用浏览器打开AList的页面就能像操作本地文件夹一样浏览网盘里的文件在线预览图片、视频、音频也支持一键生成直链分享或者通过WebDAV协议把它挂载到电脑、手机、播放器上。它支持的存储后端非常多社区一直保持更新这也是它比很多同类项目生命力更强的原因。小雅则是一个做好的“成品包”。它把AList、多个网盘资源、定时更新脚本、媒体串流服务打包进一个docker镜像运行起来之后你不需要自己费劲找资源、配挂载它已经帮你聚合好了大量影视、音乐、书籍、软件类的目录打开网页就能点播。小雅这个名称其实来自项目维护者的网名社区里习惯简称为“小雅”实际镜像名是xiaoyaliu/alist。1.2 小雅和AList到底是什么关系这里要重点说清楚一个容易混淆的点小雅内部就运行着一个AList实例。你可以理解成AList是引擎小雅是装好引擎的成品车你上车就能开不用自己再去调校。小雅镜像把AList程序、资源目录配置、网盘token脚本、媒体串流组件都整合到一起启动后通过内置的AList向用户提供网页访问和WebDAV接口。但小雅并不是万能的。它默认帮你聚合的是网盘里的公共资源目录如果你想挂载自己的个人网盘、自己的家庭照片、自己的文档还是要回到AList的逻辑里自己添加存储。所以实际使用中小雅和单独部署的AList是互补关系小雅负责开箱即用的资源独立的AList负责你自己的私有数据。1.3 我为什么最终选了“小雅独立AList”双跑方案在方案选型上我纠结过几种搭配只装AList灵活性最强想挂什么网盘就挂什么但所有存储都靠自己配资源也要一个个自己找折腾成本高。只装小雅开箱即用资源目录现成但想加自己的网盘、想定制目录结构操作起来不太顺手。小雅和AList一起跑小雅管公共资源独立AList管私有存储两个容器互不干扰各干各的。最终我选了第三种。实际跑下来发现两个容器占用的资源都不大小雅大约占100MB内存单独AList也就几十MB对小主机来说完全没压力。而且两个服务端口不同访问入口清楚维护起来也不容易搞混。2. 安装前的环境准备2.1 硬件和系统要求这几点别忽略先说硬件。AList和小雅本身对性能要求不高只要是x86架构或者ARM架构的Linux机器都能跑树莓派、ARM开发板也没问题。真正影响体验的是内存和硬盘内存建议至少2GB小雅跑起来之后AList进程加上媒体串流组件大约占150MB左右如果容器数量多2GB会更稳。硬盘的话小雅镜像本身不大但数据卷里会缓存一些索引和封面文件建议留出至少10GB空间长期使用50GB会更从容。系统方面Debian、Ubuntu、CentOS这些主流发行版都可以内核不需要特殊配置。如果你用的是群晖、威联通这类NAS系统只要支持Docker套件基本就是装好Docker后跟着下面的命令走。我自己测试的环境是Ubuntu 22.04小主机是x86平台命令在Debian 12上也都验证过。2.2 安装Docker和Docker Compose这一步是整套方案的地基。如果系统里还没有Docker先执行下面几条命令安装。以Ubuntu/Debian为例最稳妥的方式是使用官方安装脚本curl -fsSL https://get.docker.com | bash -s docker脚本执行完后启动Docker服务并设置开机自启systemctl enable --now docker验证是否安装成功docker version看到Client和Server两段都正常输出版本号就说明Docker装好了。然后安装Docker Compose插件虽然下面大部分操作可以用docker命令完成但Compose管理容器启动参数更方便也推荐一并装上apt install docker-compose-plugin装完之后验证一下docker compose version国内服务器拉取Docker Hub镜像经常会超时这一步尤其要提前处理。编辑Docker的守护进程配置文件vim /etc/docker/daemon.json写入国内镜像加速地址{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com, https://docker.nju.edu.cn ] }保存后重启Dockersystemctl restart docker注意镜像加速地址有时会失效如果发现拉取镜像还是超时去搜一下当前可用的加速地址替换即可这一步不影响后面的安装流程。2.3 端口规划和目录规划安装之前先规划好端口免得装到一半发现端口冲突。我实际用到的端口如下服务端口说明AList主界面5244独立AList的网页访问入口小雅AList界面5678小雅内置AList的网页入口小雅媒体串流5344供播放器直连的串流端口目录规划同样重要。我习惯把Docker数据集中放在一个目录下方便备份和迁移mkdir -p /data/docker/alist mkdir -p /data/docker/xiaoya/data/docker/alist用来存放独立AList的配置数据/data/docker/xiaoya存放小雅的数据卷两个互不干扰。这样做的最大好处是某一天想升级容器或者迁移到新机器直接把这两个目录打包搬走就行不用重新配置。3. AList本体安装与配置3.1 用一条Docker命令跑起AListAList官方提供了Docker镜像部署非常简单。在规划好的目录下执行docker run -d \ --namealist \ --restartalways \ -v /data/docker/alist:/opt/alist/data \ -p 5244:5244 \ -e PUID0 \ -e PGID0 \ -e UMASK022 \ xhofe/alist:latest这条命令里的几个参数要说明一下。-d表示后台运行--restartalways保证容器挂掉或服务器重启后自动拉起这步对长期运行非常重要可以避免手动去启动容器。-v把宿主机的/data/docker/alist目录挂载到容器内的/opt/alist/dataAList的所有配置、数据库都写在这个目录里数据持久化就靠它。-p 5244:5244把容器的5244端口映射到宿主机浏览器直接访问 http://服务器IP:5244 就能打开AList界面。PUID和PGID这两个环境变量是关于文件权限的。设为0表示以root身份运行容器内的进程这样挂载目录的读写权限不会出幺蛾子。如果要追求安全性可以创建一个专用用户传入用户的UID和GID但对家庭自用场景来说用0最省心。3.2 初始化管理员账号和密码AList首次启动后管理员密码是随机生成的不会直接显示在界面上。需要进容器里执行命令查看docker exec -it alist ./alist admin random执行完会输出一段类似“Successfully created the admin user and the initial password is: xxxxxx”的信息冒号后面的就是初始密码。拿到密码后打开 http://服务器IP:5244 用admin和这串密码登录。登录进去第一件事建议先到“个人资料”或“设置”里改掉密码同时把密码保存到密码管理器里因为AList不会再次显示它。登录后的界面是英文的想换成中文就到“个人资料”里把语言切换成简体中文系统会记住这个设置换设备或换浏览器也不用重新设置。3.3 挂载夸克网盘的操作实例AList装好后最核心的操作就是添加存储。我这里以挂载夸克网盘为例把整个流程拆开讲因为它的cookie获取方式对新手来说是最容易踩坑的环节。首先在AList左侧菜单点“管理”进入后台后找到“存储”菜单点击“添加”按钮驱动类型下拉选择“夸克网盘”。接下来需要填三个关键参数挂载路径、Cookie、根文件夹ID。挂载路径可以随便填比如/夸克网盘这个路径就是你之后在AList首页看到的目录名。Cookie则需要打开夸克网盘的网页版用浏览器登录自己的账号然后按F12打开开发者工具切到“控制台”Console标签页执行下面这段代码document.cookie执行后输出的字符串就是当前登录态的Cookie把它完整复制出来粘贴到AList的Cookie输入框里。根文件夹ID是选填的如果留空默认从网盘根目录开始挂载。保存之后回到AList首页如果刚才填写的路径出现在左侧目录树里并且能正常列出文件就说明挂载成功了。如果显示“获取目录失败”或类似报错绝大部分原因是Cookie不完整建议把网页版退出登录再重新登录一次重新获取Cookie。注意夸克网盘的Cookie有效期不固定短则几天长则一两个月。如果某天突然发现挂载目录打不开了优先怀疑Cookie失效重新获取并更新即可不用动其他配置。同样的套路添加阿里云盘、百度网盘、OneDrive等也都是到“存储”里添加对应驱动再填各自需要的参数核心逻辑是一样的。4. 小雅的安装与配置4.1 拉取小雅镜像并启动容器小雅的镜像名是xiaoyaliu/alist这个镜像是持续更新的默认标签latest即可。运行命令如下docker run -d \ --namexiaoya \ --restartalways \ -p 5678:80 \ -p 5344:2345 \ -v /data/docker/xiaoya:/data \ -e TZAsia/Shanghai \ xiaoyaliu/alist:latest命令中-p 5678:80把小雅内置的AList界面映射到宿主机的5678端口访问 http://服务器IP:5678 就是小雅的网页入口。-p 5344:2345是把小雅的媒体串流端口映射到5344这个端口专门给Infuse、nPlayer这类播放器直连使用。TZAsia/Shanghai把容器时区设置为北京时间避免日志时间和本地对不上。镜像体积大约200MB视网速不同拉取可能需要几分钟耐心等待即可。启动完成后查看容器状态docker ps | grep xiaoya看到STATUS一栏是Up就说明容器在正常运行。4.2 配置阿里云盘Token这类关键参数小雅启动后数据卷/data/docker/xiaoya下会自动生成几个关键文件这些文件保存着小雅运行所需的配置。用ls命令查看ls -l /data/docker/xiaoya正常情况下会看到mytoken.txt、myopentoken.txt、temp_transfer_folder_id.txt这几个文件。小雅通过读取这些文件里的内容来访问阿里云盘资源所以要让小雅正常出资源必须在启动后把这三个文件配置好。第一个是mytoken.txt里面放的是阿里云盘的refresh_token。获取方法浏览器登录阿里云盘网页版后按F12打开开发者工具在“控制台”里执行一段获取refresh_token的脚本把输出的字符粘贴到mytoken.txt文件里。这个token的作用是让服务器能拿到访问网盘文件的权限。第二个是myopentoken.txt里面放的是阿里云盘开放平台的token。需要去阿里云盘开放平台注册一个应用创建应用后获取App ID和App Secret再通过API换取token。这个流程稍微麻烦一点但阿里云盘开放平台的控制台里有完整的说明文档跟着走一遍就能拿到。第三个是temp_transfer_folder_id.txt这个最简单。在阿里云盘网页版里新建一个文件夹比如叫“xiaoya”进入这个文件夹后浏览器地址栏URL的最后一段字符串就是文件夹ID复制到temp_transfer_folder_id.txt里即可。三个文件都填写完毕后重启小雅容器让配置生效docker restart xiaoya4.3 小雅的数据卷里到底有哪些东西这里额外补充一下小雅数据卷的结构因为这个直接关系到排查问题的效率。数据卷/data/docker/xiaoya下除了刚才说的三个配置文件还有几个目录值得注意dav目录存放WebDAV相关的文件小雅通过236端口或镜像内配置向外界提供WebDAV访问。log目录小雅的运行日志排查问题时会用到。各类json/txt文件记录资源目录的索引、更新状态等由小雅的定时任务自动维护。小雅内部有定时更新机制会定期拉取远程资源索引所以资源目录会持续变化不需要你手动干预。如果发现资源目录长时间不更新先看log目录下的日志有没有报错大概率是token失效了。新版小雅还支持通过xiaoyahelper这个辅助脚本做完整模式部署脚本会自动处理token配置、定时更新、媒体库刮削等一系列操作比纯手工配置省心不少。脚本的使用方式是在服务器上执行bash -c $(curl -s https://xiaoyahelper.zengge99.eu.org/aliyun_clear.sh | tail -n 2)执行后按提示选择模式即可。不过我的建议是第一次安装还是手动走一遍流程搞清楚每个配置项的含义之后再决定要不要用脚本自动化不然出了问题你连排查的方向都没有。4.4 验证小雅是否正常运行配置完成后打开浏览器访问 http://服务器IP:5678 如果能看到小雅的AList登录或浏览界面就说明小雅的网页服务已经正常。随便点进一个影视目录点开一个视频文件如果能在网页上直接播放说明整个链路是通的小雅从阿里云盘拉取文件流通过内置AList推送给浏览器。这一步有两点要留意一是首次加载封面图或视频缓冲需要几秒钟这是正常现象二是有部分资源本身比较大网页播放器可能转圈较久建议后续用专用播放器连接体验会好很多。如果页面打不开优先检查容器状态和端口映射docker logs xiaoya --tail 50看日志末尾有没有报错比如端口占用、网络异常等。大部分启动问题都能从日志里找到明确线索。5. 常见问题与排查实录5.1 小雅容器不断重启怎么办这个现象很典型docker ps看到的状态字段一直是Restarting或者Up几秒又掉下来。排查思路只有一条先看日志。docker logs xiaoya --tail 100如果日志里出现“Address already in use”说明5678或5344端口被其他程序占用。用netstat查一下是哪个进程占的netstat -tlnp | grep -E 5678|5344可以改映射端口比如把5678改成5679修改方式是删除容器后用新的端口参数重新创建docker rm -f xiaoya docker run -d --namexiaoya --restartalways -p 5679:80 -p 5344:2345 -v /data/docker/xiaoya:/data -e TZAsia/Shanghai xiaoyaliu/alist:latest如果日志里出现libc、权限类的错误优先检查数据卷目录的读写权限chmod -R 777 /data/docker/xiaoya再重启容器大概率能解决。5.2 资源能打开但播放特别卡顿小雅资源本身是走阿里云盘直链的网络正常情况下不会太卡。卡顿的原因一般有三种。第一种是服务器出口带宽不够。如果你的小主机是家庭宽带的公网IP上行带宽本身就是不对称的外网访问时串流自然受限。这种情况只能开会员提速或者换到有更好带宽的机房。第二种是播放器没走对端口。用播放器连接小雅时串流地址一定要用小雅的媒体串流端口5344而不是AList的5678端口。用错端口会导致播放器反复转圈看似在缓冲实际根本没拿到数据流。第三种是本地播放器的解码能力不足。有些高清资源对解码要求高换个播放器试试就能区分是网络问题还是解码问题。我自己的经验是安卓用nPlayer苹果用InfuseWindows上不用折腾播放器直接用网页或者PotPlayer就行。5.3 Token失效的判断与处理token失效是小雅使用过程中最高频的问题。判断方法非常简单小雅页面能打开但点进任何目录都显示加载失败或文件列表为空或者日志里反复出现401/403错误基本就可以断定是token过期了。处理方式是重新获取对应token更新到mytoken.txt或myopentoken.txt里然后重启容器。为了避免频繁处理token失效我一般会在日历里设置一个每月提醒定时检查一次token状态总比突然播不了再手忙脚乱地处理强。另外不建议在小雅页面里手动点击“修复”之类的按钮因为新版小雅的修复逻辑有时会清掉你手动配置的参数反而把环境搞乱。5.4 播放器连接小雅的几种姿势网页直接播放是最简单的但体验上限不高特别是遇到大文件或需要外挂字幕的时候就比较吃力。我实测下来体验最好的是用播放器走WebDAV协议连接。以Infuse为例添加媒体服务器时选择WebDAV地址填http://服务器IP:5344/dav用户名和密码跟小雅的AList账号一致。连上之后小雅里的影视目录会以媒体库的形式展示出来自动抓取海报、简介、演员信息观影体验跟商业流媒体平台差不多。nPlayer的设置套路类似也是添加WebDAV服务器填入地址、账号、密码即可。这里有个小技巧连接参数里端口务必要填5344不是WebDAV默认的端口漏了这一步连接大概率失败。5.5 安装配置速查表项目内容AList镜像xhofe/alist:latest独立AList端口5244独立AList数据目录/data/docker/alist小雅镜像xiaoyaliu/alist:latest小雅页面端口5678小雅串流端口5344小雅数据目录/data/docker/xiaoya小雅关键文件mytoken.txt、myopentoken.txt、temp_transfer_folder_id.txtWebDAV地址http://IP:5344/dav日志查看命令docker logs 容器名 --tail 100这套配置表基本覆盖了日常维护会用到的主要信息建议截图保存。等跑过一段实际使用期遇到问题回头对照这张表排查比临时翻命令要快得多。我在实际使用中最深的体会是AList和小雅这套方案的价值不仅在于聚合网盘更在于它把“资源获取”和“资源管理”这两件事彻底分开了。小雅负责省心AList负责可控两者结合之后日常看片我基本只打开播放器不用再打开浏览器翻网页自己的文件和素材则走独立的AList入口目录结构清清楚楚。这个搭配我已经稳定跑了半年多除了toke偶发失效基本没遇到别的大问题。