1. 项目概述与核心价值如果你和我一样手头管理着好几个不同平台的网盘——比如百度网盘存着工作资料阿里云盘放着个人收藏的电影OneDrive同步着日常文档夸克网盘里还有些朋友分享的资源——那你肯定也烦透了来回切换客户端、重复登录下载的麻烦。更别提有些网盘对非会员的下载速度限制简直让人抓狂。几年前为了解决这个痛点我开始寻找一种能把所有网盘“聚合”起来像访问本地文件夹一样浏览和管理它们的方案直到我遇到了AList。AList本质上是一个开源的、支持多种存储后端的文件列表程序。你可以把它理解为一个“万能文件管理器代理”。它自己不存文件但它能帮你把分散在各个角落的网盘、对象存储、本地目录甚至FTP服务器统统“挂载”到一个统一的Web界面上。通过这个界面你可以直接在线预览视频、文档、图片生成直链分享给他人甚至通过WebDAV协议将这些虚拟的目录映射到你电脑的本地磁盘上。这意味着在Windows的资源管理器或Linux的文件管理器里你能看到一个名为“我的所有网盘”的驱动器点进去就是所有网盘内容的聚合视图复制粘贴文件就像操作本地文件一样直观。这个项目的核心价值远不止是“方便”二字。对于轻度用户它解决了多平台管理的碎片化问题对于影音爱好者它相当于搭建了一个私人的在线媒体库配合播放器直接串流观看对于团队协作它可以作为统一的文件分发和预览入口而对于开发者或运维人员将网盘挂载为本地磁盘后可以直接用命令行工具或脚本对云端文件进行批量操作自动化程度大大提升。无论是Linux服务器还是Windows个人电脑部署AList的过程已经非常成熟接下来我就结合自己多次部署的经验带你从零开始搞定它。2. 部署方案选型与前期准备在真正动手之前我们需要根据使用场景选择最合适的部署方式。AList的部署非常灵活主要分为直接安装和容器化部署两种路径。我的建议是如果你是在个人电脑Windows/macOS/Linux桌面版上使用追求简单快捷首选直接安装如果你是在服务器通常是Linux上部署希望环境隔离、管理方便、易于迁移和升级那么Docker是不二之选。2.1 直接安装 vs. Docker容器化部署直接安装指的是从AList的GitHub Releases页面下载对应操作系统和CPU架构的预编译二进制文件直接运行。它的优点是“开箱即用”依赖极少通常只需要一个可执行文件。在Windows上你下载一个alist-windows-amd64.zip解压后双击alist.exe就能跑起来在Linux上下载对应版本赋予执行权限后运行./alist server即可。这种方式非常轻量适合快速体验和单机使用。Docker部署则是将AList及其运行环境打包在一个独立的容器中。你需要先安装Docker引擎。它的优势非常明显环境一致性无论你的宿主机系统是什么版本、装了哪些库容器内的AList运行环境都是一模一样的彻底杜绝了“在我机器上好好的”这类问题。隔离性AList的运行不会影响宿主机的其他服务所有配置和数据都封装在容器或指定的数据卷里干净利落。易于管理启动、停止、重启、升级都是一条命令的事。特别是升级只需要拉取新镜像并重新运行容器即可旧数据通过挂载的数据卷得以保留。资源控制可以方便地限制容器使用的CPU、内存等资源。考虑到我们教程的通用性和生产环境的实用性我将以Docker部署作为主线进行详细讲解因为它代表了更现代、更稳健的部署实践。同时我也会在关键节点说明直接安装的对应步骤确保不同需求的读者都能跟上。2.2 环境检查与工具准备无论选择哪种方式一些前置检查是必要的。对于Linux服务器包括个人电脑上的Linux发行版系统更新首先确保你的系统包管理器是最新的。对于Ubuntu/Debian运行sudo apt update sudo apt upgrade -y。对于CentOS/RHEL运行sudo yum update -y或sudo dnf update -y。Docker安装如果选择容器化如果你的系统还没有Docker安装它。以Ubuntu为例官方提供了一键安装脚本但更推荐使用包管理器安装稳定版本# 卸载旧版本如有 sudo apt-get remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release -y # 添加Docker官方GPG密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 设置稳定版仓库 echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker引擎 sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io -y # 将当前用户加入docker组避免每次使用sudo sudo usermod -aG docker $USER # 退出当前终端并重新登录使组权限生效注意将用户加入docker组是一个便利操作但意味着该用户拥有了相当于root的权限。在生产环境或多人使用的服务器上请谨慎评估风险。对于Windows个人电脑Docker Desktop安装如果你选择Docker方式需要安装Docker Desktop。前往Docker官网下载安装包。安装过程中最关键的一步是确保开启Hyper-V和Windows容器支持。如果安装后启动失败提示“Virtualization support wasnt detected”你需要进入BIOS/UEFI设置确保CPU的虚拟化技术Intel VT-x / AMD-V已启用。在Windows“启用或关闭Windows功能”中确认“Hyper-V”和“Windows虚拟机监控程序平台”已被勾选并安装。对于Windows 10 Home版它不支持Hyper-V你需要安装WSL 2Windows Subsystem for Linux 2然后Docker Desktop会使用WSL 2作为后端。直接安装准备如果选择直接安装则只需要确保你的Windows版本不是太古老如Win7可能需要额外运行库并准备好一个你喜欢的目录来存放AList程序文件。获取AList管理员密码仅首次运行需要无论哪种安装方式AList首次启动时都会生成一个随机的管理员密码。对于Docker我们需要在启动命令中指定一个数据目录密码会生成在该目录下的日志文件中。我们会在后续步骤中具体说明如何查看。3. 使用Docker部署AListLinux/Windows通用这是我最推荐也是目前最主流的部署方式。一旦Docker环境就绪部署AList就是几条命令的事。3.1 创建数据持久化目录容器本身是无状态的重启后容器内的数据会丢失。因此我们必须将AList的配置和数据目录“映射”到宿主机的物理磁盘上。这通过Docker的“卷挂载”volume mount或“绑定挂载”bind mount实现。这里我们使用更直观的绑定挂载。在宿主机上选择一个合适的路径例如/opt/alistLinux或D:\DockerData\alistWindows。然后创建必要的子目录。Linux/macOS/WSL2终端sudo mkdir -p /opt/alist sudo chown -R $USER:$USER /opt/alist # 将目录所有权改为当前用户避免权限问题Windows PowerShell以管理员身份运行New-Item -ItemType Directory -Force -Path D:\DockerData\alist实操心得我习惯将所有的Docker应用数据集中放在一个像D:\DockerData这样的目录下每个应用一个子文件夹这样备份和管理起来一目了然。权限问题在Linux上很常见如果启动后AList无法写入配置首先检查这个目录的权限。3.2 拉取并运行AList容器使用官方镜像xhofe/alist:latest。这里提供一个最基础的运行命令它包含了核心的配置Linux/macOS/WSL2docker run -d \ --restartalways \ -v /opt/alist:/opt/alist/data \ -p 5244:5244 \ --namealist \ xhofe/alist:latestWindows PowerShelldocker run -d --restartalways -v D:\DockerData\alist:/opt/alist/data -p 5244:5244 --namealist xhofe/alist:latest命令参数详解-d后台运行detached mode。--restartalways设置容器随Docker服务自动重启。这样即使宿主机重启AList服务也会自动恢复。这是保证服务可用的关键设置。-v /宿主机器目录:/容器内目录将宿主机的目录挂载到容器内。这里我们把宿主机的/opt/alist映射到容器内AList默认的数据目录/opt/alist/data。所有配置、缓存都会保存在宿主机上。-p 5244:5244端口映射。将容器内的5244端口映射到宿主机的5244端口。AList的Web服务默认运行在5244端口。--namealist给容器起个名字方便后续管理。xhofe/alist:latest使用的镜像名和标签。latest标签代表最新稳定版。你也可以指定具体版本如xhofe/alist:v3.19.0以获得更稳定的环境。执行命令后使用docker ps查看容器状态确认其处于“Up”状态。3.3 获取初始管理员密码容器首次启动时会在数据目录中生成一个随机密码。我们需要查看日志来获取它。# 查看容器日志寻找password关键字 docker logs alist | grep -i password或者直接去挂载的数据目录里找日志文件# Linux cat /opt/alist/log/log.log | grep -i password # Windows (在PowerShell中查看文件内容) Get-Content D:\DockerData\alist\log\log.log | Select-String -Pattern password你会在输出中看到类似这样的一行INFO[2023-10-27 11:22:33] admin password: xxxxxxxx这个xxxxxxxx就是你的初始管理员密码。请立即复制保存。3.4 访问Web界面并初始化打开浏览器访问http://你的服务器IP地址:5244或http://localhost:5244如果在本地部署。点击右下角的登录按钮。用户名输入admin密码输入上一步获取的随机密码。登录成功后强烈建议你第一时间进入“管理”-“个人资料”页面修改这个随机密码为一个强密码。至此AList的核心服务已经部署完成。你现在可以看到一个空空如也的界面接下来就是最精彩的部分——挂载你的第一个网盘。4. 挂载存储驱动以夸克网盘和本地存储为例AList支持数十种存储类型挂载流程大同小异。这里我以近期讨论度很高的“夸克网盘”和最基本的“本地存储”为例详细讲解挂载过程。理解了这个其他网盘如阿里云盘、百度网盘、OneDrive等的挂载也只是参数不同而已。4.1 挂载夸克网盘获取Token是关键夸克网盘没有官方开放的APIAList通过模拟登录的方式实现挂载。其核心在于获取你的登录令牌Token。步骤一获取夸克网盘Token在Chrome或Edge浏览器中登录网页版夸克网盘 (cloud.quark.cn)。按F12打开开发者工具切换到网络(Network) 选项卡。刷新页面在网络请求列表中寻找一个名为list或类似携带sort参数的请求。点击这个请求在右侧的请求头(Headers) 部分找到Cookie字段。复制整个Cookie字段的值。这个长字符串就是你的Token。它通常以QC005...; QC006...;开头。重要警告这个Cookie包含了你的登录会话信息等同于你的账号密码。切勿泄露给他人切勿上传到任何公开的代码仓库、论坛或截图里。只在你自己信任的AList配置页面中使用。步骤二在AList中添加存储登录AList管理后台进入“管理”-“存储”。点击页面左下角的“添加存储”。在“驱动”下拉列表中选择“夸克网盘 (Quark Cloud Drive)”。填写配置信息挂载路径这是你在AList中访问这个网盘的路径。例如填写/quark那么你之后就可以通过http://你的AList地址:5244/quark来访问夸克网盘内容。排序文件列表的排序方式按需选择。Cookie将上一步复制的整个Cookie字符串粘贴到这里。根文件夹ID默认为root表示挂载网盘的根目录。如果你想只挂载某个子文件夹需要先获取该文件夹的ID在夸克网盘URL中folder/后面的那串字符。点击“添加”。如果Cookie有效页面顶部会提示“成功”稍等几秒刷新主页你就能看到“quark”这个目录了点进去就是你的夸克网盘文件。4.2 挂载本地存储扩展服务器本身的空间如果你在VPS或NAS上部署了AList除了挂载云端网盘还可以把服务器本身的硬盘空间也挂载上去作为一个简单的私有云盘。在“添加存储”页面“驱动”选择“本地存储 (Local Storage)”。填写配置挂载路径例如/local。根文件夹路径填写服务器上的一个绝对路径。例如你想把/home/user/myfiles这个文件夹共享出去就填这个路径。这里有个大坑如果你用的是Docker部署这里的路径指的是容器内部的路径而不是宿主机的路径。我们之前启动容器时已经把宿主机的/opt/alist挂载到了容器的/opt/alist/data。所以如果你想挂载宿主机的/home/user/myfiles你需要 a.不推荐启动容器时额外挂载一个卷-v /home/user/myfiles:/some/mount/path然后这里填/some/mount/path。 b.推荐在已挂载的/opt/alist/data目录下创建软链接或直接存放文件。例如在宿主机上ln -s /home/user/myfiles /opt/alist/data/mylocal然后在AList里挂载本地存储根路径填/opt/alist/data/mylocal。这样管理起来更集中。点击“添加”。现在你就可以通过AList上传、管理服务器本地的文件了。4.3 其他常见网盘挂载要点阿里云盘需要刷新令牌Refresh Token。获取方式是通过浏览器插件或脚本抓取AList文档有详细指引。这是目前最稳定的挂载方式之一。百度网盘需要Cookie和BDUSS。获取方式类似夸克但百度网盘的验证机制更复杂非会员体验可能不佳。OneDrive/Google Drive需要创建应用获取客户端ID和密钥走标准的OAuth 2.0授权流程。这需要你有一个对应平台的开发者账号个人微软/谷歌账号即可过程稍繁琐但一劳永逸。实操心得建议从一个简单的网盘如本地存储或阿里云盘开始挂载成功后再尝试其他。每添加一个存储都立即点击存储列表右侧的“启用/禁用”开关旁边的“文件夹”图标测试是否能正常列出文件。这能帮你快速定位是配置错误还是网络问题。5. 通过WebDAV将AList挂载到本地文件系统这是将体验提升到“下一个级别”的功能。通过WebDAV协议我们可以把AList中聚合的所有存储映射为Windows的一个网络驱动器或Linux的一个挂载点。5.1 在Windows上挂载为网络驱动器确保AList开启WebDAV在AList管理后台“管理”-“设置”-“WebDAV”中确认WebDAV服务是启用的默认端口5245。打开“此电脑”点击顶部菜单的“计算机”-“映射网络驱动器”。选择一个未使用的驱动器号如Z:。在文件夹栏输入你的WebDAV地址http://你的AList服务器IP:5245/dav。如果你在本地电脑运行AList地址就是http://localhost:5245/dav。如果你挂载到服务器地址就是http://服务器公网IP:5245/dav。注意如果AList配置了域名或HTTPS则需要相应改为https://你的域名:5245/dav。Windows原生客户端对HTTPS的WebDAV支持可能需要额外配置。勾选“使用其他凭据连接”点击“完成”。在弹出的登录窗口中用户名输入admin密码输入你的AList管理员密码。如果连接成功你就能在“此电脑”里看到一个新的网络位置Z:盘打开它里面就是你在AList中挂载的所有目录如/quark,/local等。常见问题Windows可能会提示“无法访问此文件夹…权限不足”。首先确认用户名密码正确。其次尝试在地址栏中直接输入\\你的AList服务器IP5245\dav格式进行连接。如果还不行可能需要修改Windows注册表或启用“WebClient”服务运行services.msc找到WebClient并启动它设置启动类型为“自动”。5.2 在Linux上挂载WebDAV在Linux上我们可以使用davfs2工具将WebDAV挂载到本地目录。安装davfs2# Ubuntu/Debian sudo apt install davfs2 -y # CentOS/RHEL sudo yum install davfs2 -y创建一个本地挂载点sudo mkdir /mnt/alist将你的AList凭据添加到davfs2的秘密文件避免每次挂载输入密码echo http://你的AList服务器IP:5245/dav admin 你的密码 | sudo tee -a /etc/davfs2/secrets sudo chmod 600 /etc/davfs2/secrets # 设置文件权限保护密码执行挂载sudo mount -t davfs http://你的AList服务器IP:5245/dav /mnt/alist如果一切正常现在ls /mnt/alist就能看到AList下的所有文件夹了。可选设置开机自动挂载 编辑/etc/fstab文件在末尾添加一行http://你的AList服务器IP:5245/dav /mnt/alist davfs _netdev,noauto,user 0 0其中noauto表示开机不自动挂载需要时用mount /mnt/alist手动挂user允许普通用户挂载。如果你需要开机自动挂去掉noauto但请注意这可能会因网络未就绪而导致挂载失败。挂载后的体验完成这一步后你就可以在任何支持文件路径的地方使用这个映射的驱动器了。比如在PotPlayer等播放器里直接打开Z:\quark\电影\xxx.mp4进行播放在VS Code里直接编辑Z:\local\code\project.py用cp或rsync命令在Linux上直接备份云端文件到本地。这种无缝集成的体验才是AList真正的威力所在。6. 进阶配置与优化基础功能部署完成后为了让AList更安全、更稳定、更好用我们还需要进行一些进阶配置。6.1 配置反向代理与HTTPS面向公网访问如果你想让AList在互联网上被安全地访问直接暴露5244端口是不专业且不安全的。我们应该使用Nginx或Caddy这样的反向代理服务器并配置HTTPS证书。使用Nginx的配置示例假设你的域名是alist.yourdomain.com并且已经申请了SSL证书文件为cert.pem和key.pem。在Nginx的配置目录如/etc/nginx/conf.d/下创建一个新配置文件例如alist.conf。写入以下配置server { listen 80; server_name alist.yourdomain.com; # 将HTTP请求重定向到HTTPS return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name alist.yourdomain.com; ssl_certificate /path/to/your/cert.pem; ssl_certificate_key /path/to/your/key.pem; # 可在此处添加其他SSL优化配置 location / { proxy_pass http://localhost:5244; # 指向AList实际运行的服务和端口 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; # 以下两行对WebDAV很重要 proxy_set_header X-Forwarded-Host $host:$server_port; proxy_set_header X-Forwarded-Port $server_port; proxy_redirect off; # 上传大文件超时设置 client_max_body_size 20000m; proxy_connect_timeout 600s; proxy_send_timeout 600s; proxy_read_timeout 600s; } }检查Nginx配置并重载sudo nginx -t sudo nginx -s reload。现在你就可以通过https://alist.yourdomain.com安全地访问AList了。同时WebDAV的地址也需要相应改为https://alist.yourdomain.com:5245如果反向代理也代理了5245端口则需在Nginx中为5245端口单独配置一个server块。6.2 权限管理与多用户默认情况下AList只有一个管理员账户。你可以通过“管理”-“用户”来创建新用户。普通用户可以登录Web界面查看和操作被授权的存储。在“存储”页面编辑每个存储可以在“权限”选项卡中指定哪些用户或用户组可以访问该存储。只读用户创建用户时可以设置角色为“只读”这样该用户只能查看和下载文件不能上传、删除或修改。用户组可以创建用户组将存储权限分配给组再将用户加入组方便批量管理。注意事项AList的权限管理是基础级别的适用于小型团队或个人分享。它不具备像专业网盘那样精细的文件夹级权限控制或审计日志。如果用于严格的商业环境请评估其是否满足合规要求。6.3 性能优化与缓存缩略图缓存AList可以为图片和视频生成缩略图但这会消耗CPU和磁盘IO。在“管理”-“设置”-“预览”中你可以调整缩略图生成策略如仅对图片生成、设置缓存过期时间。对于大量媒体文件启用并合理设置缓存能显著提升浏览体验。元信息缓存对于某些存储如阿里云盘AList会缓存文件列表信息以减少API调用。你可以在“存储”的编辑页面调整“缓存过期时间”。在文件不常变动的场景下适当延长缓存时间可以提升响应速度。数据库优化AList使用SQLite作为默认数据库。当文件数量极大数十万以上时SQLite性能可能下降。可以考虑迁移到MySQL或PostgreSQL。这需要在启动AList时通过环境变量配置数据库连接具体可参考官方文档。对于绝大多数个人用户SQLite完全足够。7. 常见问题排查与维护技巧即使按照教程一步步来也可能会遇到各种问题。这里我总结了一些高频问题和解决方法。7.1 部署与启动问题问题1Docker容器启动后立刻退出。排查使用docker logs alist查看容器日志。最常见的原因是数据目录权限问题。容器内的进程通常以非root用户运行无法写入你挂载的宿主机目录。解决确保宿主机目录对容器用户可写。一个粗暴但有效的方法是sudo chmod -R 777 /opt/alist仅限测试环境。生产环境建议查清容器内运行的用户UID通常是1000或1001然后用chown更改目录所有者。问题2Web界面能打开但挂载网盘时一直显示“加载中”或报错。排查检查存储配置尤其是Token、Cookie、Refresh Token等是否过期或填写错误。这些凭证通常都有有效期需要定期更新。检查网络连通性你的AList服务器是否能正常访问目标网盘的API可以在服务器上尝试curl一下网盘的域名。查看AList日志在管理后台的“管理”-“日志”中查看是否有具体的错误信息。这是最直接的排错手段。问题3WebDAV挂载失败Windows提示“找不到网络路径”或“权限不足”Linux提示“Mount failed”排查确认WebDAV服务已开启AList设置中确认端口是5245。检查防火墙确保服务器防火墙如ufwfirewalld和云服务商的安全组规则放行了5244Web和5245WebDAV端口。Windows特定问题尝试以管理员身份运行命令提示符执行net stop webclient net start webclient重启WebClient服务。对于较新的Windows 10/11可能需要启用“SMB 1.0/CIFS文件共享支持”功能不推荐有安全风险或使用第三方WebDAV客户端如RaiDrive。7.2 日常维护与升级如何更新AList版本对于Docker部署升级非常简单# 1. 停止并删除旧容器 docker stop alist docker rm alist # 2. 拉取最新的镜像如果之前用的是latest标签 docker pull xhofe/alist:latest # 3. 用同样的参数重新运行容器注意你的数据目录路径 docker run -d --restartalways -v /opt/alist:/opt/alist/data -p 5244:5244 --namealist xhofe/alist:latest关键点-v参数映射的宿主机数据目录没变所以你的所有配置和元数据都会保留。如何备份AList的所有核心数据配置、元数据、缓存都保存在你挂载的数据目录里如/opt/alist。定期备份这个目录即可。数据库文件data.db和配置文件config.json是这个目录下最重要的文件。如何迁移在新服务器上安装好Docker将旧服务器的整个数据目录如/opt/alist打包复制过去然后使用完全相同的docker run命令启动容器即可。7.3 安全建议一定要改密码首次登录后立即修改默认的随机密码。使用强密码管理员密码和重要存储的访问凭证务必使用高强度密码。启用HTTPS如果公网访问必须配置反向代理和SSL证书避免密码和传输数据被窃听。限制访问IP如果仅自己或小范围使用可以在Nginx或服务器防火墙层面设置IP白名单。定期更新关注AList的GitHub Releases及时更新到新版本修复潜在的安全漏洞。凭证保管网盘的Token、Cookie等敏感信息只保存在AList的配置中不要记录在别处。 1. 项目概述与核心价值如果你和我一样手头管理着好几个不同平台的网盘——比如百度网盘存着工作资料阿里云盘放着个人收藏的电影OneDrive同步着日常文档夸克网盘里还有些朋友分享的资源——那你肯定也烦透了来回切换客户端、重复登录下载的麻烦。更别提有些网盘对非会员的下载速度限制简直让人抓狂。几年前为了解决这个痛点我开始寻找一种能把所有网盘“聚合”起来像访问本地文件夹一样浏览和管理它们的方案直到我遇到了AList。AList本质上是一个开源的、支持多种存储后端的文件列表程序。你可以把它理解为一个“万能文件管理器代理”。它自己不存文件但它能帮你把分散在各个角落的网盘、对象存储、本地目录甚至FTP服务器统统“挂载”到一个统一的Web界面上。通过这个界面你可以直接在线预览视频、文档、图片生成直链分享给他人甚至通过WebDAV协议将这些虚拟的目录映射到你电脑的本地磁盘上。这意味着在Windows的资源管理器或Linux的文件管理器里你能看到一个名为“我的所有网盘”的驱动器点进去就是所有网盘内容的聚合视图复制粘贴文件就像操作本地文件一样直观。这个项目的核心价值远不止是“方便”二字。对于轻度用户它解决了多平台管理的碎片化问题对于影音爱好者它相当于搭建了一个私人的在线媒体库配合播放器直接串流观看对于团队协作它可以作为统一的文件分发和预览入口而对于开发者或运维人员将网盘挂载为本地磁盘后可以直接用命令行工具或脚本对云端文件进行批量操作自动化程度大大提升。无论是Linux服务器还是Windows个人电脑部署AList的过程已经非常成熟接下来我就结合自己多次部署的经验带你从零开始搞定它。2. 部署方案选型与前期准备在真正动手之前我们需要根据使用场景选择最合适的部署方式。AList的部署非常灵活主要分为直接安装和容器化部署两种路径。我的建议是如果你是在个人电脑Windows/macOS/Linux桌面版上使用追求简单快捷首选直接安装如果你是在服务器通常是Linux上部署希望环境隔离、管理方便、易于迁移和升级那么Docker是不二之选。2.1 直接安装 vs. Docker容器化部署直接安装指的是从AList的GitHub Releases页面下载对应操作系统和CPU架构的预编译二进制文件直接运行。它的优点是“开箱即用”依赖极少通常只需要一个可执行文件。在Windows上你下载一个alist-windows-amd64.zip解压后双击alist.exe就能跑起来在Linux上下载对应版本赋予执行权限后运行./alist server即可。这种方式非常轻量适合快速体验和单机使用。Docker部署则是将AList及其运行环境打包在一个独立的容器中。你需要先安装Docker引擎。它的优势非常明显环境一致性无论你的宿主机系统是什么版本、装了哪些库容器内的AList运行环境都是一模一样的彻底杜绝了“在我机器上好好的”这类问题。隔离性AList的运行不会影响宿主机的其他服务所有配置和数据都封装在容器或指定的数据卷里干净利落。易于管理启动、停止、重启、升级都是一条命令的事。特别是升级只需要拉取新镜像并重新运行容器即可旧数据通过挂载的数据卷得以保留。资源控制可以方便地限制容器使用的CPU、内存等资源。考虑到我们教程的通用性和生产环境的实用性我将以Docker部署作为主线进行详细讲解因为它代表了更现代、更稳健的部署实践。同时我也会在关键节点说明直接安装的对应步骤确保不同需求的读者都能跟上。2.2 环境检查与工具准备无论选择哪种方式一些前置检查是必要的。对于Linux服务器包括个人电脑上的Linux发行版系统更新首先确保你的系统包管理器是最新的。对于Ubuntu/Debian运行sudo apt update sudo apt upgrade -y。对于CentOS/RHEL运行sudo yum update -y或sudo dnf update -y。Docker安装如果选择容器化如果你的系统还没有Docker安装它。以Ubuntu为例官方提供了一键安装脚本但更推荐使用包管理器安装稳定版本# 卸载旧版本如有 sudo apt-get remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release -y # 添加Docker官方GPG密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 设置稳定版仓库 echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装Docker引擎 sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io -y # 将当前用户加入docker组避免每次使用sudo sudo usermod -aG docker $USER # 退出当前终端并重新登录使组权限生效注意将用户加入docker组是一个便利操作但意味着该用户拥有了相当于root的权限。在生产环境或多人使用的服务器上请谨慎评估风险。对于Windows个人电脑Docker Desktop安装如果你选择Docker方式需要安装Docker Desktop。前往Docker官网下载安装包。安装过程中最关键的一步是确保开启Hyper-V和Windows容器支持。如果安装后启动失败提示“Virtualization support wasnt detected”你需要进入BIOS/UEFI设置确保CPU的虚拟化技术Intel VT-x / AMD-V已启用。在Windows“启用或关闭Windows功能”中确认“Hyper-V”和“Windows虚拟机监控程序平台”已被勾选并安装。对于Windows 10 Home版它不支持Hyper-V你需要安装WSL 2Windows Subsystem for Linux 2然后Docker Desktop会使用WSL 2作为后端。直接安装准备如果选择直接安装则只需要确保你的Windows版本不是太古老如Win7可能需要额外运行库并准备好一个你喜欢的目录来存放AList程序文件。获取AList管理员密码仅首次运行需要无论哪种安装方式AList首次启动时都会生成一个随机的管理员密码。对于Docker我们需要在启动命令中指定一个数据目录密码会生成在该目录下的日志文件中。我们会在后续步骤中具体说明如何查看。3. 使用Docker部署AListLinux/Windows通用这是我最推荐也是目前最主流的部署方式。一旦Docker环境就绪部署AList就是几条命令的事。3.1 创建数据持久化目录容器本身是无状态的重启后容器内的数据会丢失。因此我们必须将AList的配置和数据目录“映射”到宿主机的物理磁盘上。这通过Docker的“卷挂载”volume mount或“绑定挂载”bind mount实现。这里我们使用更直观的绑定挂载。在宿主机上选择一个合适的路径例如/opt/alistLinux或D:\DockerData\alistWindows。然后创建必要的子目录。Linux/macOS/WSL2终端sudo mkdir -p /opt/alist sudo chown -R $USER:$USER /opt/alist # 将目录所有权改为当前用户避免权限问题Windows PowerShell以管理员身份运行New-Item -ItemType Directory -Force -Path D:\DockerData\alist实操心得我习惯将所有的Docker应用数据集中放在一个像D:\DockerData这样的目录下每个应用一个子文件夹这样备份和管理起来一目了然。权限问题在Linux上很常见如果启动后AList无法写入配置首先检查这个目录的权限。3.2 拉取并运行AList容器使用官方镜像xhofe/alist:latest。这里提供一个最基础的运行命令它包含了核心的配置Linux/macOS/WSL2docker run -d \ --restartalways \ -v /opt/alist:/opt/alist/data \ -p 5244:5244 \ --namealist \ xhofe/alist:latestWindows PowerShelldocker run -d --restartalways -v D:\DockerData\alist:/opt/alist/data -p 5244:5244 --namealist xhofe/alist:latest命令参数详解-d后台运行detached mode。--restartalways设置容器随Docker服务自动重启。这样即使宿主机重启AList服务也会自动恢复。这是保证服务可用的关键设置。-v /宿主机器目录:/容器内目录将宿主机的目录挂载到容器内。这里我们把宿主机的/opt/alist映射到容器内AList默认的数据目录/opt/alist/data。所有配置、缓存都会保存在宿主机上。-p 5244:5244端口映射。将容器内的5244端口映射到宿主机的5244端口。AList的Web服务默认运行在5244端口。--namealist给容器起个名字方便后续管理。xhofe/alist:latest使用的镜像名和标签。latest标签代表最新稳定版。你也可以指定具体版本如xhofe/alist:v3.19.0以获得更稳定的环境。执行命令后使用docker ps查看容器状态确认其处于“Up”状态。3.3 获取初始管理员密码容器首次启动时会在数据目录中生成一个随机密码。我们需要查看日志来获取它。# 查看容器日志寻找password关键字 docker logs alist | grep -i password或者直接去挂载的数据目录里找日志文件# Linux cat /opt/alist/log/log.log | grep -i password # Windows (在PowerShell中查看文件内容) Get-Content D:\DockerData\alist\log\log.log | Select-String -Pattern password你会在输出中看到类似这样的一行INFO[2023-10-27 11:22:33] admin password: xxxxxxxx这个xxxxxxxx就是你的初始管理员密码。请立即复制保存。3.4 访问Web界面并初始化打开浏览器访问http://你的服务器IP地址:5244或http://localhost:5244如果在本地部署。点击右下角的登录按钮。用户名输入admin密码输入上一步获取的随机密码。登录成功后强烈建议你第一时间进入“管理”-“个人资料”页面修改这个随机密码为一个强密码。至此AList的核心服务已经部署完成。你现在可以看到一个空空如也的界面接下来就是最精彩的部分——挂载你的第一个网盘。4. 挂载存储驱动以夸克网盘和本地存储为例AList支持数十种存储类型挂载流程大同小异。这里我以近期讨论度很高的“夸克网盘”和最基本的“本地存储”为例详细讲解挂载过程。理解了这个其他网盘如阿里云盘、百度网盘、OneDrive等的挂载也只是参数不同而已。4.1 挂载夸克网盘获取Token是关键夸克网盘没有官方开放的APIAList通过模拟登录的方式实现挂载。其核心在于获取你的登录令牌Token。步骤一获取夸克网盘Token在Chrome或Edge浏览器中登录网页版夸克网盘 (cloud.quark.cn)。按F12打开开发者工具切换到网络(Network) 选项卡。刷新页面在网络请求列表中寻找一个名为list或类似携带sort参数的请求。点击这个请求在右侧的请求头(Headers) 部分找到Cookie字段。复制整个Cookie字段的值。这个长字符串就是你的Token。它通常以QC005...; QC006...;开头。重要警告这个Cookie包含了你的登录会话信息等同于你的账号密码。切勿泄露给他人切勿上传到任何公开的代码仓库、论坛或截图里。只在你自己信任的AList配置页面中使用。步骤二在AList中添加存储登录AList管理后台进入“管理”-“存储”。点击页面左下角的“添加存储”。在“驱动”下拉列表中选择“夸克网盘 (Quark Cloud Drive)”。填写配置信息挂载路径这是你在AList中访问这个网盘的路径。例如填写/quark那么你之后就可以通过http://你的AList地址:5244/quark来访问夸克网盘内容。排序文件列表的排序方式按需选择。Cookie将上一步复制的整个Cookie字符串粘贴到这里。根文件夹ID默认为root表示挂载网盘的根目录。如果你想只挂载某个子文件夹需要先获取该文件夹的ID在夸克网盘URL中folder/后面的那串字符。点击“添加”。如果Cookie有效页面顶部会提示“成功”稍等几秒刷新主页你就能看到“quark”这个目录了点进去就是你的夸克网盘文件。4.2 挂载本地存储扩展服务器本身的空间如果你在VPS或NAS上部署了AList除了挂载云端网盘还可以把服务器本身的硬盘空间也挂载上去作为一个简单的私有云盘。在“添加存储”页面“驱动”选择“本地存储 (Local Storage)”。填写配置挂载路径例如/local。根文件夹路径填写服务器上的一个绝对路径。例如你想把/home/user/myfiles这个文件夹共享出去就填这个路径。这里有个大坑如果你用的是Docker部署这里的路径指的是容器内部的路径而不是宿主机的路径。我们之前启动容器时已经把宿主机的/opt/alist挂载到了容器的/opt/alist/data。所以如果你想挂载宿主机的/home/user/myfiles你需要 a.不推荐启动容器时额外挂载一个卷-v /home/user/myfiles:/some/mount/path然后这里填/some/mount/path。 b.推荐在已挂载的/opt/alist/data目录下创建软链接或直接存放文件。例如在宿主机上ln -s /home/user/myfiles /opt/alist/data/mylocal然后在AList里挂载本地存储根路径填/opt/alist/data/mylocal。这样管理起来更集中。点击“添加”。现在你就可以通过AList上传、管理服务器本地的文件了。4.3 其他常见网盘挂载要点阿里云盘需要刷新令牌Refresh Token。获取方式是通过浏览器插件或脚本抓取AList文档有详细指引。这是目前最稳定的挂载方式之一。百度网盘需要Cookie和BDUSS。获取方式类似夸克但百度网盘的验证机制更复杂非会员体验可能不佳。OneDrive/Google Drive需要创建应用获取客户端ID和密钥走标准的OAuth 2.0授权流程。这需要你有一个对应平台的开发者账号个人微软/谷歌账号即可过程稍繁琐但一劳永逸。实操心得建议从一个简单的网盘如本地存储或阿里云盘开始挂载成功后再尝试其他。每添加一个存储都立即点击存储列表右侧的“启用/禁用”开关旁边的“文件夹”图标测试是否能正常列出文件。这能帮你快速定位是配置错误还是网络问题。5. 通过WebDAV将AList挂载到本地文件系统这是将体验提升到“下一个级别”的功能。通过WebDAV协议我们可以把AList中聚合的所有存储映射为Windows的一个网络驱动器或Linux的一个挂载点。5.1 在Windows上挂载为网络驱动器确保AList开启WebDAV在AList管理后台“管理”-“设置”-“WebDAV”中确认WebDAV服务是启用的默认端口5245。打开“此电脑”点击顶部菜单的“计算机”-“映射网络驱动器”。选择一个未使用的驱动器号如Z:。在文件夹栏输入你的WebDAV地址http://你的AList服务器IP:5245/dav。如果你在本地电脑运行AList地址就是http://localhost:5245/dav。如果你挂载到服务器地址就是http://服务器公网IP:5245/dav。注意如果AList配置了域名或HTTPS则需要相应改为https://你的域名:5245/dav。Windows原生客户端对HTTPS的WebDAV支持可能需要额外配置。勾选“使用其他凭据连接”点击“完成”。在弹出的登录窗口中用户名输入admin密码输入你的AList管理员密码。如果连接成功你就能在“此电脑”里看到一个新的网络位置Z:盘打开它里面就是你在AList中挂载的所有目录如/quark,/local等。常见问题Windows可能会提示“无法访问此文件夹…权限不足”。首先确认用户名密码正确。其次尝试在地址栏中直接输入\\你的AList服务器IP5245\dav格式进行连接。如果还不行可能需要修改Windows注册表或启用“WebClient”服务运行services.msc找到WebClient并启动它设置启动类型为“自动”。5.2 在Linux上挂载WebDAV在Linux上我们可以使用davfs2工具将WebDAV挂载到本地目录。安装davfs2# Ubuntu/Debian sudo apt install davfs2 -y # CentOS/RHEL sudo yum install davfs2 -y创建一个本地挂载点sudo mkdir /mnt/alist将你的AList凭据添加到davfs2的秘密文件避免每次挂载输入密码echo http://你的AList服务器IP:5245/dav admin 你的密码 | sudo tee -a /etc/davfs2/secrets sudo chmod 600 /etc/davfs2/secrets # 设置文件权限保护密码执行挂载sudo mount -t davfs http://你的AList服务器IP:5245/dav /mnt/alist如果一切正常现在ls /mnt/alist就能看到AList下的所有文件夹了。可选设置开机自动挂载 编辑/etc/fstab文件在末尾添加一行http://你的AList服务器IP:5245/dav /mnt/alist davfs _netdev,noauto,user 0 0其中noauto表示开机不自动挂载需要时用mount /mnt/alist手动挂user允许普通用户挂载。如果你需要开机自动挂去掉noauto但请注意这可能会因网络未就绪而导致挂载失败。挂载后的体验完成这一步后你就可以在任何支持文件路径的地方使用这个映射的驱动器了。比如在PotPlayer等播放器里直接打开Z:\quark\电影\xxx.mp4进行播放在VS Code里直接编辑Z:\local\code\project.py用cp或rsync命令在Linux上直接备份云端文件到本地。这种无缝集成的体验才是AList真正的威力所在。6. 进阶配置与优化基础功能部署完成后为了让AList更安全、更稳定、更好用我们还需要进行一些进阶配置。6.1 配置反向代理与HTTPS面向公网访问如果你想让AList在互联网上被安全地访问直接暴露5244端口是不专业且不安全的。我们应该使用Nginx或Caddy这样的反向代理服务器并配置HTTPS证书。使用Nginx的配置示例假设你的域名是alist.yourdomain.com并且已经申请了SSL证书文件为cert.pem和key.pem。在Nginx的配置目录如/etc/nginx/conf.d/下创建一个新配置文件例如alist.conf。写入以下配置server { listen 80; server_name alist.yourdomain.com; # 将HTTP请求重定向到HTTPS return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name alist.yourdomain.com; ssl_certificate /path/to/your/cert.pem; ssl_certificate_key /path/to/your/key.pem; # 可在此处添加其他SSL优化配置 location / { proxy_pass http://localhost:5244; # 指向AList实际运行的服务和端口 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; # 以下两行对WebDAV很重要 proxy_set_header X-Forwarded-Host $host:$server_port; proxy_set_header X-Forwarded-Port $server_port; proxy_redirect off; # 上传大文件超时设置 client_max_body_size 20000m; proxy_connect_timeout 600s; proxy_send_timeout 600s; proxy_read_timeout 600s; } }检查Nginx配置并重载sudo nginx -t sudo nginx -s reload。现在你就可以通过https://alist.yourdomain.com安全地访问AList了。同时WebDAV的地址也需要相应改为https://alist.yourdomain.com:5245如果反向代理也代理了5245端口则需在Nginx中为5245端口单独配置一个server块。6.2 权限管理与多用户默认情况下AList只有一个管理员账户。你可以通过“管理”-“用户”来创建新用户。普通用户可以登录Web界面查看和操作被授权的存储。在“存储”页面编辑每个存储可以在“权限”选项卡中指定哪些用户或用户组可以访问该存储。只读用户创建用户时可以设置角色为“只读”这样该用户只能查看和下载文件不能上传、删除或修改。用户组可以创建用户组将存储权限分配给组再将用户加入组方便批量管理。注意事项AList的权限管理是基础级别的适用于小型团队或个人分享。它不具备像专业网盘那样精细的文件夹级权限控制或审计日志。如果用于严格的商业环境请评估其是否满足合规要求。6.3 性能优化与缓存缩略图缓存AList可以为图片和视频生成缩略图但这会消耗CPU和磁盘IO。在“管理”-“设置”-“预览”中你可以调整缩略图生成策略如仅对图片生成、设置缓存过期时间。对于大量媒体文件启用并合理设置缓存能显著提升浏览体验。元信息缓存对于某些存储如阿里云盘AList会缓存文件列表信息以减少API调用。你可以在“存储”的编辑页面调整“缓存过期时间”。在文件不常变动的场景下适当延长缓存时间可以提升响应速度。数据库优化AList使用SQLite作为默认数据库。当文件数量极大数十万以上时SQLite性能可能下降。可以考虑迁移到MySQL或PostgreSQL。这需要在启动AList时通过环境变量配置数据库连接具体可参考官方文档。对于绝大多数个人用户SQLite完全足够。7. 常见问题排查与维护技巧即使按照教程一步步来也可能会遇到各种问题。这里我总结了一些高频问题和解决方法。7.1 部署与启动问题问题1Docker容器启动后立刻退出。排查使用docker logs alist查看容器日志。最常见的原因是数据目录权限问题。容器内的进程通常以非root用户运行无法写入你挂载的宿主机目录。解决确保宿主机目录对容器用户可写。一个粗暴但有效的方法是sudo chmod -R 777 /opt/alist仅限测试环境。生产环境建议查清容器内运行的用户UID通常是1000或1001然后用chown更改目录所有者。问题2Web界面能打开但挂载网盘时一直显示“加载中”或报错。排查检查存储配置尤其是Token、Cookie、Refresh Token等是否过期或填写错误。这些凭证通常都有有效期需要定期更新。检查网络连通性你的AList服务器是否能正常访问目标网盘的API可以在服务器上尝试curl一下网盘的域名。查看AList日志在管理后台的“管理”-“日志”中查看是否有具体的错误信息。这是最直接的排错手段。问题3WebDAV挂载失败Windows提示“找不到网络路径”或“权限不足”Linux提示“Mount failed”排查确认WebDAV服务已开启AList设置中确认端口是5245。检查防火墙确保服务器防火墙如ufwfirewalld和云服务商的安全组规则放行了5244Web和5245WebDAV端口。Windows特定问题尝试以管理员身份运行命令提示符执行net stop webclient net start webclient重启WebClient服务。对于较新的Windows 10/11可能需要启用“SMB 1.0/CIFS文件共享支持”功能不推荐有安全风险或使用第三方WebDAV客户端如RaiDrive。7.2 日常维护与升级如何更新AList版本对于Docker部署升级非常简单# 1. 停止并删除旧容器 docker stop alist docker rm alist # 2. 拉取最新的镜像如果之前用的是latest标签 docker pull xhofe/alist:latest # 3. 用同样的参数重新运行容器注意你的数据目录路径 docker run -d --restartalways -v /opt/alist:/opt/alist/data -p 5244:5244 --namealist xhofe/alist:latest关键点-v参数映射的宿主机数据目录没变所以你的所有配置和元数据都会保留。如何备份AList的所有核心数据配置、元数据、缓存都保存在你挂载的数据目录里如/opt/alist。定期备份这个目录即可。数据库文件data.db和配置文件config.json是这个目录下最重要的文件。如何迁移在新服务器上安装好Docker将旧服务器的整个数据目录如/opt/alist打包复制过去然后使用完全相同的docker run命令启动容器即可。7.3 安全建议一定要改密码首次登录后立即修改默认的随机密码。使用强密码管理员密码和重要存储的访问凭证务必使用高强度密码。启用HTTPS如果公网访问必须配置反向代理和SSL证书避免密码和传输数据被窃听。限制访问IP如果仅自己或小范围使用可以在Nginx或服务器防火墙层面设置IP白名单。定期更新关注AList的GitHub Releases及时更新到新版本修复潜在的安全漏洞。凭证保管网盘的Token、Cookie等敏感信息只保存在AList的配置中不要记录在别处。 
