家里那台常年开着的小主机装上 CasaOS 之后就变成了一个只管存、不管取的文件仓库——硬盘里塞满了东西可真想从外面调一份出来看或者临时下一部片子扔进去还是得折腾一阵子。这套Alist Aria2的组合说到底就是把看和下这两件事补上Alist 负责把散落在各个网盘和本地磁盘里的文件统一成一套清爽的目录树用浏览器就能翻Aria2 负责把重活接过来多线程下载、离线任务、BT 也不在话下。再配合 CasaOS 的 Docker 底座两个服务各跑一个容器配置和数据全部落在宿主机目录里重装、迁移、备份都不至于抓瞎。这篇内容面向三类人刚把 CasaOS 装上、正愁装点什么的新手已经会用 Alist 但一直卡在 Aria2 联动上的半熟手以及想把管理入口安全地放到公网访问、又不想把面板裸奔出去的老玩家。我会从组件分工讲起把目录规划、compose 编写、网盘挂载、离线任务下发、远程访问方案和踩坑排查一条线走完参数怎么算、路径为什么这么映射、权限为什么老出问题全都会说清楚。文中的路径、端口、镜像名都可以直接抄抄完改成你自己的环境即可。1. 先搞清楚这套组合到底解决了什么问题很多人一上手就急着复制粘贴 compose 文件跑起来发现打不开页面、下载任务永远卡在 0%、挂载的网盘目录点进去是空的然后开始怀疑人生。这些问题九成不是镜像的问题而是没想明白三个组件各自的边界在哪。先把角色分工理清楚后面所有的路径映射和端口配置都会变得顺理成章。1.1 三个组件各自的角色分工CasaOS 在这套方案里的定位是底座它本身不做网盘聚合也不做下载它干的事情是把 Docker 的安装、容器生命周期管理、应用目录规范和 Web 管理界面包装好了。换句话说CasaOS 给你的是一套约定俗成的目录习惯/DATA/AppData放配置、/DATA/Media放数据和一个能点鼠标的入口真正的服务还是跑在容器里。理解了这一点你就不会指望在 CasaOS 的界面里找到一个设置 Aria2 线程数的开关——那属于容器内部配置。Alist 是门面。它把不同来源的存储抽象成统一的目录树对上层暴露 HTTP 服务。它的核心能力有三个一是存储挂载把网盘、本地磁盘、对象存储、WebDAV 都接进来二是统一鉴权你可以给不同目录分配不同账号三是离线下载调度注意这里的关键词是调度——Alist 自己不做下载它只是把链接转发给你配置好的下载器然后展示进度。所以 Aria2 挂了Alist 的离线下载按钮就会一直转圈。Aria2 是苦力。它是纯粹的命令行下载器没有图形界面通过 RPC 接口接收任务。它支持 HTTP/FTP、BT/磁力、Metalink多连接分片能把带宽吃满。它在容器里跑的时候只认容器内的路径这一点是后面所有路径映射问题的根源。1.2 为什么用 Docker 而不是裸装裸装直接 apt 装或者下载二进制也能跑但 Alist 的更新频率相当高一两个月一个新版本是常态裸装每次升级都要手动停服务、替换二进制、处理可能变化的配置字段。Aria2 更麻烦它依赖一堆配置文件项的格式和默认值换机器迁移动辄漏项。Docker 把这两个问题一起解决了镜像里固化了运行环境配置文件挂载在宿主机上升级就是拉新镜像、重建容器配置还在原地。更实际的一点是隔离。Aria2 的 BT 端口、DHT 网络、会话文件都容易和其他服务产生冲突丢进容器里网络和文件系统都是独立的出问题直接删容器重建不会污染宿主机。而且 CasaOS 本身就是围绕 Docker 构建的你把 compose 交给它管理Web UI 里能看到容器状态、日志、资源占用排查起来省事。提示不要为了省事在 CasaOS 自带的应用商店里点安装。商店里的版本和路径映射往往是固定的一旦你想改下载目录、加一个挂载点就得去翻它自动生成的 compose 文件反而更绕。直接走自定义应用或者命令行 compose路径完全由你掌控。1.3 什么样的硬件和网络环境适合上手这套方案对硬件要求真的很低。一台四核、2G 内存起步的小主机完全够用Alist 是 Go 写的常驻内存大概几十 MBAria2 空载也就几十 MB真正吃资源的是下载时的磁盘 IO 和网络。存储方面建议至少留出两块盘的余量一块放配置和数据库小几十 GB 都用不完一块放下载数据越大越好。如果你打算长期挂 BT机械盘比 SSD 更划算SSD 频繁写入对寿命不友好。网络上有两个概念要先分清内网访问和远程访问。内网访问就是手机、电脑和主机连着同一个路由器用192.168.x.x:5244就能打开这种情况零配置也最安全。远程访问则要求你的网络环境支持从外部回到内网常见做法是端口映射加动态域名或者用反向代理把服务暴露出去。两者在部署阶段没有区别差别只在最后的访问链路所以完全可以先在内网把功能跑通再考虑外部访问的事。2. CasaOS环境准备与部署前的地基工作部署之前花二十分钟做检查能省掉后面两个小时的排查。这一节讲的三件事——硬件与系统状态确认、存储目录规划、端口占用预检——看起来琐碎但每一条都直接决定后面容器能不能顺滑地跑起来。尤其是目录规划很多人图省事把下载目录随手设在系统盘根目录结果系统盘被塞满、CasaOS 界面卡死这种事我见过不止一次。2.1 硬件与系统现状确认先用 SSH 登录到主机CasaOS 默认开了 SSH端口 22跑几条命令把家底摸清楚。uname -a看内核架构free -h看内存余量df -h看各分区剩余空间docker version确认 Docker 服务正常。如果你看到df -h里根分区只剩几个 G那要么先清理要么把/DATA挂在另一块盘上。CasaOS 的目录约定值得单独说一下。/DATA/AppData是它给所有应用放配置的地方/DATA/Media是给媒体文件准备的。这两个目录在正常安装时应该是独立挂载点或者至少在大容量分区上。执行lsblk和df -h /DATA交叉验证一下如果/DATA和根分区是同一个设备说明 CasaOS 的数据目录没做独立挂载这时候你得自己决定要么加一块盘重新挂载要么接受风险把下载目录设在其他位置。还有一个容易忽略的点文件系统类型。如果是 ext4权限控制按 Unix 的 uid/gid 走配置起来直观如果是 NTFS 或 exFAT很多外接硬盘默认是这个挂载后权限会被统一成某个值容器里的进程可能因为没有写权限而报错。可以mount | grep -i data看一下挂载参数NTFS 建议加上uid1000,gid1000,umask022这类选项让容器里的非 root 用户也能读写。2.2 存储目录规划与权限预埋目录规划的核心原则只有一条配置和数据分离并且数据目录不要在系统盘。我习惯这样组织/DATA/AppData/alist/ # Alist 的配置和数据库 /DATA/AppData/aria2/ # Aria2 的配置、会话文件、日志 /DATA/Media/downloads/ # 下载完成的文件 /DATA/Media/incomplete/ # 未完成的临时文件 /DATA/Media/library/ # 已有的本地媒体库给 Alist 挂载用把incomplete单独分出来是有讲究的。Aria2 下载时会先在临时目录里写分片完成后才移动到目标目录。如果临时目录和目标目录在同一个磁盘的不同分区上移动就变成了跨设备复制大文件会卡很久如果是同一分区移动几乎是瞬间的重命名操作。所以这两个目录必须落在同一块盘上。权限预埋这一步很多人跳过然后在容器日志里看到一堆Permission denied。做法是先id看一下你的普通用户 uid/gidCasaOS 装机时创建的第一个用户通常是 1000:1000然后把这几个目录的属主改成这个 uid/gid权限设成 775。Alist 和 Aria2 的容器都会用PUID和PGID环境变量接收这个值容器内进程就会以这个身份读写文件宿主机和容器里的权限就对齐了。mkdir -p /DATA/AppData/{alist,aria2} /DATA/Media/{downloads,incomplete,library} chown -R 1000:1000 /DATA/AppData/alist /DATA/AppData/aria2 /DATA/Media chmod -R 775 /DATA/AppData/alist /DATA/AppData/aria2 /DATA/Media注意如果你后面打算用 Aria2 的种子功能incomplete目录所在分区的可用空间要留足BT 做种时临时文件和已完成文件会同时存在空间占用大约是文件大小的两倍。2.3 端口占用与防火墙预检端口冲突是容器起不来最常见的原因之一而且报错信息往往很隐晦——容器状态显示running但页面打不开实际上是被宿主机上另一个服务抢先占了端口。部署前先查一遍ss -lntp | grep -E 5244|5245|6800|6881Alist 用 5244 作为 Web 端口5245 是它的另一个备用端口某些版本用于内部通信Aria2 的 RPC 端口是 6800BT 监听端口建议用 6881-6999 这个区间。如果上面这几条命令有输出说明端口被占了要么改端口要么停掉占用它的服务。防火墙这块如果你的主机在局域网内其实可以不开放任何端口容器映射到宿主机的端口在局域网内默认可访问。但如果系统开了 ufw 或 firewalld就需要显式放行。我个人建议只放行真正需要的端口而且只对局域网网段放行。比如ufw allow from 192.168.1.0/24 to any port 5244这样外部即使知道你的 IP 也连不进来。下面是这套方案的端口规划参考服务容器内端口宿主机映射用途是否建议对公网开放Alist52445244Web 管理面板与文件浏览否走反向代理Aria268006800RPC 接口接收下载任务否仅容器间通信Aria26881-69996881-6999BT 监听端口是需路由器映射Aria25141351413备用 BT 端口视情况这张表里最值得琢磨的是是否建议对公网开放这一列。Alist 面板里有你的全部网盘凭据Aria2 的 RPC 接口如果不设密钥任何人都能往你硬盘里塞文件。所以这两个管理入口一律不对公网直开需要外网访问时用反向代理套一层加上 HTTPS 和访问控制。BT 端口是例外它本身就是给外部节点连的映射出去反而能提高下载速度。3. 用Docker Compose把Alist和Aria2跑起来到了动手环节。我选 Compose 而不是docker run原因是这套服务涉及多个目录挂载、多个端口映射、两个容器之间还要通信用命令行写会变成一坨几百字符的长串改一次参数就够你受的。Compose 文件是声明式的所有配置肉眼可见改完docker compose up -d就生效而且 CasaOS 的自定义应用本质上也是接收一段 compose 内容两者可以无缝切换。3.1 编写compose文件的完整思路先把完整文件贴出来然后逐段拆解。这个文件放在/DATA/AppData/alist-stack/docker-compose.yml目录名你自己定但建议统一放在/DATA/AppData下面方便 CasaOS 识别和备份。services: alist: image: xhofe/alist:latest container_name: alist restart: unless-stopped ports: - 5244:5244 volumes: - /DATA/AppData/alist:/opt/alist/data - /DATA/Media:/mnt/media environment: - PUID1000 - PGID1000 - UMASK022 - TZAsia/Shanghai networks: - alist-net aria2: image: p3terx/aria2-pro:latest container_name: aria2 restart: unless-stopped ports: - 6800:6800 - 6881-6999:6881-6999 - 6881-6999:6881-6999/udp volumes: - /DATA/AppData/aria2:/config - /DATA/Media/downloads:/downloads - /DATA/Media/incomplete:/incomplete environment: - PUID1000 - PGID1000 - UMASK022 - TZAsia/Shanghai - RPC_SECRET换成你自己的长随机串 - RPC_PORT6800 - LISTEN_PORT6881 - DISK_CACHE64M - IPV6_MODEfalse - UPDATE_TRACKERStrue networks: - alist-net networks: alist-net: driver: bridge这个文件的核心设计思路有三点。第一两个容器放在同一个自定义 bridge 网络里这样它们可以通过容器名互相访问Alist 配置 Aria2 地址时直接写http://aria2:6800/jsonrpc就行不用管宿主机的 IP 变化。第二配置目录和数据目录分开挂载/DATA/AppData下只放小文件配置/DATA/Media下放大文件备份的时候可以只备前者。第三所有可变参数走环境变量不写死在镜像里将来想改限速、改密钥改一行重启容器就行。3.2 逐段拆解参数配置的关键考量先看PUID和PGID。这两个值必须和你宿主机上目录的属主一致否则容器里的进程写文件会被拒绝。前面我们用chown 1000:1000把目录给了 uid 1000这里就填 1000。如果你的 CasaOS 第一个用户不是 1000用id 用户名查一下改成实际值。UMASK022的意思是新建文件权限为 644、新建目录为 755这个值兼顾了安全和可读性不建议改成 000。TZAsia/Shanghai影响的是容器内日志时间戳和定时任务。不设的话日志全是 UTC排查问题时对时间会疯掉。Aria2 的RPC_SECRET是整套方案里最重要的一个安全参数。它是 RPC 接口的访问令牌不设或者设成弱口令等于把你硬盘的写权限敞开给整个局域网。生成一个长随机串比如openssl rand -hex 16的输出然后记下来后面 Alist 配置的时候要原样填进去。这个值不要用生日、不要用123456也不要在截图里露出来。DISK_CACHE64M是磁盘缓存。Aria2 默认的缓存比较小高速下载时频繁写盘会造成 IO 瓶颈尤其是机械盘。给到 64M 到 128M 之间比较合适具体看你的内存余量——内存紧张就 32M内存充裕可以 128M。这个参数调大之后下载速度的稳定性会有肉眼可见的提升。LISTEN_PORT6881配合端口映射区间6881-6999意思是 Aria2 从 6881 开始监听如果被占用就往上找。映射一个区间而不是单个端口是为了让它在多任务并发时能同时开多个监听。UDP 那行是给 DHT 用的BT 网络靠它发现节点漏了这行下载速度会明显下降。UPDATE_TRACKERStrue是个很实用的小功能容器启动时会自动拉取一份公共 tracker 列表合并到配置里。BT 下载慢的一大原因就是 tracker 失效有了这个开关至少不用手动去维护列表。3.3 启动验证与首次登录文件写好后进入目录执行cd /DATA/AppData/alist-stack docker compose up -d docker compose ps docker compose logs -f alistdocker compose ps应该看到两个容器都是Up状态。如果 alist 显示Restarting多半是配置目录权限不对或者端口被占去看logs的输出。Aria2 的日志里如果出现errorCode1之类的字样通常是下载目录不可写回到上一节检查权限。Alist 首次启动时会生成一个随机管理员密码有两种方式拿到。一是在日志里找docker compose logs alist | grep -i password二是直接重置docker exec -it alist ./alist admin set 你的新密码这个命令会直接把 admin 账号的密码改成你指定的值比翻日志快。改完之后浏览器打开http://主机IP:5244用admin加新密码登录。登录进去先别急着挂网盘做两件事一是到设置 - 站点里把站点标题改成自己认得出的名字二是到用户里确认 admin 的权限范围。默认 admin 是全权限如果你只给自己用这样就行如果打算分享给家里人建议新建一个普通用户只给特定目录的读权限别把管理员账号发出去。提示Alist 的数据库文件在/DATA/AppData/alist/data.db这个文件包含了所有存储配置和账号信息定期备份它等于备份了整个 Alist。恢复的时候停容器、覆盖文件、启容器配置全回来。4. Alist挂载网盘与Aria2下载链路的打通容器跑起来只是搭好了台子真正让这套方案产生价值的是挂载和下载两条链路。挂载让 Alist 能看见内容下载让内容进得来两者还得能互相看见——Aria2 下完的文件Alist 得能立刻在目录里列出来。这一节把三条链路拆开讲每一环都有几个容易踩的点。4.1 本地存储与网盘挂载的三种典型方式Alist 的挂载入口在管理 - 存储 - 添加。驱动列表很长实际用下来可以归成三类。第一类是本地存储。驱动选本机存储挂载路径填容器内的路径比如/mnt/media/library这是我们在 compose 里把/DATA/Media映射进容器的结果。挂载完之后Alist 的目录树里就会出现你硬盘上的文件。这一类的坑最少唯一的注意点是路径必须写容器内路径不是宿主机路径。我见过有人填/DATA/Media/library结果目录永远是空的因为容器里根本没这个路径。第二类是网盘挂载。主流网盘基本都有对应的驱动配置的核心是拿到凭据。通用套路是在浏览器里登录网盘网页版按 F12 打开开发者工具在 Network 面板里找任意一个 API 请求从请求头里复制 Cookie 或者从响应里找 refresh_token粘贴到 Alist 的对应字段。不同网盘的字段名不一样有的要 Cookie有的要刷新令牌有的还要额外的参数。挂载成功后建议先在网盘根目录建一个测试文件夹确认能列出、能下载、能上传再往里放重要数据。第三类是协议挂载比如 WebDAV、SMB、FTP。这类适合挂另一台 NAS 或者路由器上的硬盘。配置相对简单填地址、账号、密码就行注意 WebDAV 的地址通常要带完整路径有些服务端还要求 HTTPS。挂载类型典型驱动关键参数常见问题本地存储本机存储容器内路径路径写成宿主机路径目录为空网盘各家网盘驱动Cookie / 令牌凭据过期需要定期更新协议WebDAV / SMB地址、账号、密码端口不通、路径少了前缀对象存储S3 兼容AK / SK / Endpoint区域填错导致签名失败挂载完别忘了在存储列表里点一下重新加载有时候配置保存了但缓存没刷新目录看起来还是空的。4.2 Aria2下载目录如何被Alist看见这条链路的关键在于两个容器看到的是同一份宿主机目录但路径名不一样。宿主机上的/DATA/Media/downloads在 Aria2 容器里叫/downloads在 Alist 容器里叫/mnt/media/downloads。三个路径指向同一份数据但你在哪个容器里操作就得用哪个路径。具体做法Alist 里添加一个本机存储挂载路径填/mnt/media/downloads挂载名可以叫下载目录。这样 Aria2 下完的文件几秒钟内就会出现在 Alist 的这个目录里。如果想让下载目录只读展示防止误删可以在存储配置里把只读打开。这里有个容易忽略的细节Aria2 下载完成的文件属主是PUID:PGID指定的那个用户权限是UMASK决定的。如果 Alist 容器用的 PUID 和 Aria2 不一样就会出现文件存在但打不开的情况。所以两个容器的PUID、PGID、UMASK三个值必须完全一致这一点在写 compose 的时候就要对齐。还有一个性能上的考量不要让 Alist 的缓存目录和 Aria2 的临时目录落在同一块慢盘上。Alist 在生成缩略图、做视频转码预览时会产生临时文件和 Aria2 的分片写入抢 IO两边都会变慢。如果条件允许把 Alist 的临时目录指到另一块盘或者 tmpfs 上。4.3 Alist离线下载对接Aria2的任务下发这是整套方案里体验最好的一环。配置好之后你在 Alist 里浏览任何一个文件或目录右键就能离线下载到指定位置任务直接交给 Aria2 执行进度在 Alist 里能看到。配置入口在管理 - 设置 - 其他 - Aria2。需要填三个字段RPC 地址、RPC 密钥、下载目录。RPC 地址填http://aria2:6800/jsonrpc注意这里用的是容器名而不是 IP因为两个容器在同一个自定义网络里Docker 内置的 DNS 会把容器名解析成容器 IP宿主机 IP 变了也不影响。密钥就是 compose 里那个RPC_SECRET的值一个字符都不能错。下载目录这个字段最容易出问题。它填的是Aria2 容器内的路径也就是/downloads不是宿主机路径也不是 Alist 的路径。填错的表现是任务能提交成功、进度也在走但下完之后文件不知道去哪了——其实是被 Aria2 写到了容器内的默认目录相当于写进了容器层容器一重建文件就没了。配置保存后回到文件列表找一个大文件点离线下载选 Aria2看任务是否出现在 Aria2 的任务列表里。可以用docker exec -it aria2 aria2c --version确认容器正常用docker logs aria2 --tail 50看有没有 RPC 相关的报错。注意Alist 的离线下载功能只是把 URL 转发给 Aria2能不能下取决于 Aria2 那边能不能访问到这个 URL。如果是网盘里的文件Alist 会先生成一个直链再交给 Aria2直链通常有有效期任务排队太久会失效表现为下载到一半报 403。4.4 权限与路径映射的三个隐蔽坑第一个坑是符号链接跨容器失效。有人在宿主机上给下载目录做了个软链接指向另一块盘然后挂载进容器。结果是宿主机上能访问容器里是断链。原因是软链接的目标路径在容器里不存在。解决办法是用 bind mount 直接挂真实路径别用软链接。第二个坑是大小写敏感。Linux 文件系统区分大小写/Downloads和/downloads是两个目录。Aria2 配置里如果写成了大写文件会写到一个新建的空目录里你在 Alist 里怎么也找不到。写完路径之后用docker exec aria2 ls -la /确认一下目录名。第三个坑是SELinux 或 AppArmor 的拦截。部分发行版默认开启强制访问控制容器即使有权限也写不进去日志里会出现Permission denied但权限明明是对的。临时验证可以把 SELinux 设成 permissive如果问题消失就说明是它拦的这时候要么给挂载加:z标签要么调整策略。5. 远程访问的几种落地方案内网跑通之后接下来就是人在外面也能用的需求。这里要说清楚一个前提远程访问的方案选择取决于你的网络环境有没有公网地址。有公网地址的和没有的走的路子完全不同硬套方案只会白折腾。5.1 先判断自己的网络环境最直接的方法是登录路由器管理页看 WAN 口拿到的 IP。如果这个 IP 是10.x.x.x、100.64.x.x、172.16-31.x.x这类私有地址说明你在运营商的大内网里没有独立的公网地址端口映射做了也没用。如果 WAN 口 IP 和你在网上查到的出口 IP 一致说明你有公网地址可以做端口映射。另一个要确认的是公网地址是不是固定的。家宽的公网 IP 通常是动态的重启光猫就变。这就需要动态域名解析DDNS——用一个域名指向你的 IP再跑一个脚本定时把域名更新成当前 IP。很多路由器自带这个功能在动态 DNS里填上服务商给的域名和凭据就行。CasaOS 主机上也可以跑一个轻量的 DDNS 容器效果一样。如果确认没有公网地址方案就得换。可选的路子有两条一是用带中转的服务把内网服务通过一条长连接暴露出去这类服务通常有免费额度但速度受限二是不做全量暴露只把需要的内容同步到某个云存储出门时从云上取。第二条路子牺牲了实时性但稳定性和安全性都更好。5.2 公网直连加端口映射的配置要点假设你有公网地址配置链路是这样的路由器上把外部某个高端口比如 15244映射到内网的主机IP:5244同时配好 DDNS然后用http://你的域名:15244访问。这套配置十分钟能搞定但有三个地方必须注意。第一不要用默认端口。5244 是 Alist 的默认端口扫描器一抓一大把改成五位数的高端口能挡掉绝大部分无差别扫描。第二映射的端口和实际端口要区分外部 15244 映射到内部 5244这样即使外部端口泄露攻击者也不知道内部服务的真实端口。第三路由器上只映射必要的端口Aria2 的 RPC 端口 6800 绝对不要映射出去它没有 HTTPS密钥是明文传输的。访问链路变成公网 → 路由器 → 主机:5244中间没有任何加密密码在公网上是明文跑的。所以这个方案只适合临时用、或者你对链路上的风险有充分认知。长期用的话还是得套一层 HTTPS。5.3 反向代理加域名的稳妥做法反向代理的作用是在你的服务和外部访问之间加一层由它来终结 HTTPS、做访问控制、隐藏后端真实端口。常见的做法是跑一个 Nginx Proxy Manager 容器在它的界面里添加一条代理规则域名填pan.你的域名.com转发地址填alist:5244同样用容器名开启 SSL申请一张 Lets Encrypt 证书。这样外部访问https://pan.你的域名.com流量在代理这一层就被解密再以明文转发给 Alist但因为代理和 Alist 在同一台机器、同一个 Docker 网络里这段明文不出主机风险可控。证书自动续期不用操心。路由器上只需要映射 80 和 443 两个端口其余的都不开。反向代理配置里有几个参数值得调。client_max_body_size要调大默认 1M 会导致上传大文件失败设成0表示不限制。proxy_read_timeout也要调大Alist 在做大目录列表或者视频流播放时响应可能超过默认的 60 秒。如果要在浏览器里直接播放视频还得确保代理不缓冲响应体否则拖动进度条会卡。提示反向代理之后再套一层访问控制会更稳。Nginx Proxy Manager 支持添加 Access List可以限制只允许特定 IP 段访问或者加一道基础的账号密码验证。管理面板这种入口多一层验证不亏。5.4 远程访问的安全加固清单把管理面板暴露到公网等于把家门钥匙挂在门口。下面这几条是我每次部署完都会过一遍的清单。加固项具体做法为什么重要强制 HTTPS反向代理申请证书HTTP 自动跳转防止密码和 Cookie 明文传输改默认路径Alist 设置里改管理路径扫描器找不到登录入口强密码16 位以上随机串不用重复密码防撞库关闭匿名访问访客权限设为仅特定目录防止目录被遍历限制来源代理层加 IP 白名单缩小攻击面关闭 RPC 外网6800 端口不映射Aria2 RPC 无加密定期更新镜像跟随最新稳定版修复已知漏洞日志审计定期看登录日志发现异常尝试其中改管理路径这一条成本最低、收益很高。Alist 默认的管理入口是/manage扫描器都知道改成/mysecretpanel这种随机串被扫到的概率直线下降。设置位置在管理 - 设置 - 站点 - 管理路径。6. 常见问题排查实录下面这些问题是这几年反复遇到、也被问得最多的按现象归类整理。排查的基本原则是先看容器状态再看日志最后才怀疑配置。九成的故障在前两步就能定位。6.1 容器起来了但页面打不开先执行docker compose ps确认状态是Up而不是Restarting或Exited。如果是Restarting看docker compose logs alist的最后几十行常见原因有三个配置目录权限不对导致程序无法写数据库端口被占用镜像架构不匹配比如在 ARM 设备上拉了 amd64 的镜像。如果状态正常但浏览器打不开分三步排查。第一步在主机上curl -I http://127.0.0.1:5244如果有响应说明服务本身正常问题在网络层如果没响应说明服务没监听在预期端口上去日志里找监听地址。第二步从局域网另一台设备访问http://主机IP:5244如果这台能开而那台不能检查防火墙规则。第三步如果局域网能开、远程不能开回到端口映射和 DDNS 那两节。还有一种情况是页面能打开但一直转圈最后超时。这通常是反向代理的proxy_read_timeout太短或者代理和后端之间的网络不通。在代理容器里curl http://alist:5244测一下能通就是超时配置问题。6.2 Aria2 RPC连接失败Alist 里点离线下载提示提交失败或者无法连接 Aria2按这个顺序查。先确认 Aria2 容器活着docker ps | grep aria2。再确认 RPC 端口在监听docker exec aria2 netstat -lntp | grep 6800。然后从 Alist 容器内部测试连通性docker exec -it alist sh -c wget -qO- http://aria2:6800/jsonrpc如果返回 404 或者一段 JSON说明网络通如果卡住或者报解析失败说明两个容器不在同一个网络里。密钥错误的表现是返回{error:{code:1,message:Unauthorized}}。这时候核对 compose 里的RPC_SECRET和 Alist 里填的是否一致注意前后空格和大小写。改完 compose 要docker compose up -d重建容器才生效只重启不重建不会更新环境变量。还有一个小概率情况Aria2 的 RPC 监听地址默认是0.0.0.0但某些镜像配置成了127.0.0.1这时候容器内部能访问跨容器就访问不到。看docker exec aria2 cat /config/aria2.conf | grep rpc-listen-all确认是true。6.3 网盘挂载后目录为空或加载慢挂载显示正常但目录里什么都没有先点一次重新加载。如果还是空去存储里点开那个挂载项看状态是不是有报错信息。最常见的错误是凭据失效——网盘的 Cookie 有有效期短则几天长则几个月过期后挂载状态会变成错误需要重新抓取。加载慢是另一类问题。网盘的文件列表接口本身有延迟尤其是目录里文件很多的时候一次请求可能拉取几十页。Alist 有缓存机制第一次加载慢后续会快。可以在存储配置里调大缓存过期时间代价是网盘那边新增的文件不会立刻显示。如果用的是本地存储还慢那多半是磁盘 IO 打满了检查是不是 Aria2 正在满速下载。还有一种诡异情况目录能列出来但点开文件下载报错。这通常是网盘对直链做了防盗链或者限速Alist 生成的直链需要特定的请求头。可以换一个代理模式试试——Alist 的存储配置里有个Web 代理开关打开后下载流量会经过 Alist 中转绕过防盗链代价是占用主机的带宽。6.4 重启后配置丢失或任务清空配置丢失一般是挂载路径写错了容器把数据写在了容器内部而不是挂载卷上。验证方法docker inspect alist | grep -A 10 Mounts看/opt/alist/data是否指向了宿主机的实际目录。如果显示的是匿名卷说明 compose 里的路径写错了。Aria2 重启后任务列表清空是因为会话文件没有持久化。Aria2 需要一个aria2.session文件来保存任务状态配置项是save-session和input-file分别指向保存路径和加载路径。这两个路径必须落在挂载出来的/config目录里否则容器一重建就没了。检查docker exec aria2 cat /config/aria2.conf | grep session确认两个路径都是/config/aria2.session。下面这张表可以贴在便签上出问题的时候按现象对照现象最可能原因快速验证解决页面 502代理连不上后端代理容器内 curl 后端检查容器名和网络页面超时读超时太短看代理日志调大 timeout上传失败请求体大小限制看代理报错调大 body size下载 0 速度BT 端口未映射检查端口映射映射 6881-6999离线任务不出现RPC 地址填错容器内 wget 测试改用容器名文件找不到路径写成宿主机路径容器内 ls改成容器内路径权限拒绝PUID 不一致对比两容器环境变量统一 PUID/PGID重启丢配置未挂载配置目录docker inspect修正 volumes6.5 我踩过的两个非典型坑第一个是磁盘满了但df显示还有空间。原因是 Aria2 删除任务时如果文件正被 Alist 读取比如正在播放文件句柄没释放空间不会立刻回收。用lsof | grep deleted能看到这些已删除但仍被占用的文件重启相关容器就能释放。预防办法是删除任务前先确认没有正在播放的会话。第二个是容器时间跳变导致证书续期失败。有段时间我发现 HTTPS 证书总是续不上查了半天发现是主机的 NTP 同步出了问题容器时间比实际慢了十几分钟Lets Encrypt 的校验直接失败。修好时间同步之后一切正常。这个坑很隐蔽因为服务本身跑得好好的只有依赖时间的功能会出问题。7. 长期维护与几个实用配置部署只是开始这套东西要长期稳定跑还得管住三件事更新、备份、限速。这三件事都不复杂但拖延的代价很大——尤其是备份等到数据出问题再想起来就晚了。7.1 更新策略与回滚准备Alist 的更新节奏快不建议无脑追最新版。我的做法是每季度看一次更新日志如果只是小版本修复就等一两个版本再升涉及安全修复的立刻升。升级前先备份/DATA/AppData/alist整个目录然后改 compose 里的镜像 tag建议用具体版本号而不是latest方便回滚执行docker compose pull docker compose up -d。用具体版本号而不是latest的好处是可控。latest每次 pull 都可能是新版本出问题时你连回退到哪个版本都不知道。写成xhofe/alist:v3.x.x这种形式出问题改回上一个版本号重新拉就行。Aria2 的镜像相对稳定半年更新一次足够。但要注意Aria2 的配置文件格式在不同镜像之间可能有差异换镜像之前把/DATA/AppData/aria2备份一份出问题直接覆盖回去。7.2 限速与资源占用的平衡家里带宽有限的话Aria2 满速下载会把整个网络拖垮看视频都卡。限速在 Aria2 的配置文件里设两个关键项max-overall-download-limit和max-overall-upload-limit单位是字节每秒。比如想限制到 10MB/s就填10M。这两个值可以在运行时通过 RPC 动态调整不用重启容器。限速的时机也有讲究。白天家里有人用网限到 5M凌晨自动放开到满速。这个可以用 Aria2 的 RPC 接口加一个定时任务实现也可以简单点在 Alist 里手动切。我自己的做法是给 Aria2 设一个全局上限然后在路由器上对这台主机做 QoS 限速双保险。CPU 占用方面Aria2 在下载大文件时会做分片校验单核可能跑满。如果主机核心少把--max-concurrent-downloads调到 3 到 5别贪多。Alist 本身很轻但如果开了缩略图生成浏览图片目录时 CPU 会飙一下这个可以把缩略图功能关掉换响应速度。提示incomplete目录记得定期清理。任务失败或者被取消后临时分片文件有时候会残留时间长了能占几十 GB。写个定时任务每周清理一次超过七天的残留文件能省不少空间。最后分享一个我自己一直在用的小习惯给每个容器的 compose 文件都加一行labels写上部署日期和用途备注。半年后回头看一眼就能知道这个容器是干嘛的、什么时候装的、当时为什么这么配。这台机器上的服务越堆越多没有备注的话半年后自己都认不出来哪个是哪个。
家里那台常年开着的小主机装上 CasaOS 之后就变成了一个只管存、不管取的文件仓库——硬盘里塞满了东西可真想从外面调一份出来看或者临时下一部片子扔进去还是得折腾一阵子。这套Alist Aria2的组合说到底就是把看和下这两件事补上Alist 负责把散落在各个网盘和本地磁盘里的文件统一成一套清爽的目录树用浏览器就能翻Aria2 负责把重活接过来多线程下载、离线任务、BT 也不在话下。再配合 CasaOS 的 Docker 底座两个服务各跑一个容器配置和数据全部落在宿主机目录里重装、迁移、备份都不至于抓瞎。这篇内容面向三类人刚把 CasaOS 装上、正愁装点什么的新手已经会用 Alist 但一直卡在 Aria2 联动上的半熟手以及想把管理入口安全地放到公网访问、又不想把面板裸奔出去的老玩家。我会从组件分工讲起把目录规划、compose 编写、网盘挂载、离线任务下发、远程访问方案和踩坑排查一条线走完参数怎么算、路径为什么这么映射、权限为什么老出问题全都会说清楚。文中的路径、端口、镜像名都可以直接抄抄完改成你自己的环境即可。1. 先搞清楚这套组合到底解决了什么问题很多人一上手就急着复制粘贴 compose 文件跑起来发现打不开页面、下载任务永远卡在 0%、挂载的网盘目录点进去是空的然后开始怀疑人生。这些问题九成不是镜像的问题而是没想明白三个组件各自的边界在哪。先把角色分工理清楚后面所有的路径映射和端口配置都会变得顺理成章。1.1 三个组件各自的角色分工CasaOS 在这套方案里的定位是底座它本身不做网盘聚合也不做下载它干的事情是把 Docker 的安装、容器生命周期管理、应用目录规范和 Web 管理界面包装好了。换句话说CasaOS 给你的是一套约定俗成的目录习惯/DATA/AppData放配置、/DATA/Media放数据和一个能点鼠标的入口真正的服务还是跑在容器里。理解了这一点你就不会指望在 CasaOS 的界面里找到一个设置 Aria2 线程数的开关——那属于容器内部配置。Alist 是门面。它把不同来源的存储抽象成统一的目录树对上层暴露 HTTP 服务。它的核心能力有三个一是存储挂载把网盘、本地磁盘、对象存储、WebDAV 都接进来二是统一鉴权你可以给不同目录分配不同账号三是离线下载调度注意这里的关键词是调度——Alist 自己不做下载它只是把链接转发给你配置好的下载器然后展示进度。所以 Aria2 挂了Alist 的离线下载按钮就会一直转圈。Aria2 是苦力。它是纯粹的命令行下载器没有图形界面通过 RPC 接口接收任务。它支持 HTTP/FTP、BT/磁力、Metalink多连接分片能把带宽吃满。它在容器里跑的时候只认容器内的路径这一点是后面所有路径映射问题的根源。1.2 为什么用 Docker 而不是裸装裸装直接 apt 装或者下载二进制也能跑但 Alist 的更新频率相当高一两个月一个新版本是常态裸装每次升级都要手动停服务、替换二进制、处理可能变化的配置字段。Aria2 更麻烦它依赖一堆配置文件项的格式和默认值换机器迁移动辄漏项。Docker 把这两个问题一起解决了镜像里固化了运行环境配置文件挂载在宿主机上升级就是拉新镜像、重建容器配置还在原地。更实际的一点是隔离。Aria2 的 BT 端口、DHT 网络、会话文件都容易和其他服务产生冲突丢进容器里网络和文件系统都是独立的出问题直接删容器重建不会污染宿主机。而且 CasaOS 本身就是围绕 Docker 构建的你把 compose 交给它管理Web UI 里能看到容器状态、日志、资源占用排查起来省事。提示不要为了省事在 CasaOS 自带的应用商店里点安装。商店里的版本和路径映射往往是固定的一旦你想改下载目录、加一个挂载点就得去翻它自动生成的 compose 文件反而更绕。直接走自定义应用或者命令行 compose路径完全由你掌控。1.3 什么样的硬件和网络环境适合上手这套方案对硬件要求真的很低。一台四核、2G 内存起步的小主机完全够用Alist 是 Go 写的常驻内存大概几十 MBAria2 空载也就几十 MB真正吃资源的是下载时的磁盘 IO 和网络。存储方面建议至少留出两块盘的余量一块放配置和数据库小几十 GB 都用不完一块放下载数据越大越好。如果你打算长期挂 BT机械盘比 SSD 更划算SSD 频繁写入对寿命不友好。网络上有两个概念要先分清内网访问和远程访问。内网访问就是手机、电脑和主机连着同一个路由器用192.168.x.x:5244就能打开这种情况零配置也最安全。远程访问则要求你的网络环境支持从外部回到内网常见做法是端口映射加动态域名或者用反向代理把服务暴露出去。两者在部署阶段没有区别差别只在最后的访问链路所以完全可以先在内网把功能跑通再考虑外部访问的事。2. CasaOS环境准备与部署前的地基工作部署之前花二十分钟做检查能省掉后面两个小时的排查。这一节讲的三件事——硬件与系统状态确认、存储目录规划、端口占用预检——看起来琐碎但每一条都直接决定后面容器能不能顺滑地跑起来。尤其是目录规划很多人图省事把下载目录随手设在系统盘根目录结果系统盘被塞满、CasaOS 界面卡死这种事我见过不止一次。2.1 硬件与系统现状确认先用 SSH 登录到主机CasaOS 默认开了 SSH端口 22跑几条命令把家底摸清楚。uname -a看内核架构free -h看内存余量df -h看各分区剩余空间docker version确认 Docker 服务正常。如果你看到df -h里根分区只剩几个 G那要么先清理要么把/DATA挂在另一块盘上。CasaOS 的目录约定值得单独说一下。/DATA/AppData是它给所有应用放配置的地方/DATA/Media是给媒体文件准备的。这两个目录在正常安装时应该是独立挂载点或者至少在大容量分区上。执行lsblk和df -h /DATA交叉验证一下如果/DATA和根分区是同一个设备说明 CasaOS 的数据目录没做独立挂载这时候你得自己决定要么加一块盘重新挂载要么接受风险把下载目录设在其他位置。还有一个容易忽略的点文件系统类型。如果是 ext4权限控制按 Unix 的 uid/gid 走配置起来直观如果是 NTFS 或 exFAT很多外接硬盘默认是这个挂载后权限会被统一成某个值容器里的进程可能因为没有写权限而报错。可以mount | grep -i data看一下挂载参数NTFS 建议加上uid1000,gid1000,umask022这类选项让容器里的非 root 用户也能读写。2.2 存储目录规划与权限预埋目录规划的核心原则只有一条配置和数据分离并且数据目录不要在系统盘。我习惯这样组织/DATA/AppData/alist/ # Alist 的配置和数据库 /DATA/AppData/aria2/ # Aria2 的配置、会话文件、日志 /DATA/Media/downloads/ # 下载完成的文件 /DATA/Media/incomplete/ # 未完成的临时文件 /DATA/Media/library/ # 已有的本地媒体库给 Alist 挂载用把incomplete单独分出来是有讲究的。Aria2 下载时会先在临时目录里写分片完成后才移动到目标目录。如果临时目录和目标目录在同一个磁盘的不同分区上移动就变成了跨设备复制大文件会卡很久如果是同一分区移动几乎是瞬间的重命名操作。所以这两个目录必须落在同一块盘上。权限预埋这一步很多人跳过然后在容器日志里看到一堆Permission denied。做法是先id看一下你的普通用户 uid/gidCasaOS 装机时创建的第一个用户通常是 1000:1000然后把这几个目录的属主改成这个 uid/gid权限设成 775。Alist 和 Aria2 的容器都会用PUID和PGID环境变量接收这个值容器内进程就会以这个身份读写文件宿主机和容器里的权限就对齐了。mkdir -p /DATA/AppData/{alist,aria2} /DATA/Media/{downloads,incomplete,library} chown -R 1000:1000 /DATA/AppData/alist /DATA/AppData/aria2 /DATA/Media chmod -R 775 /DATA/AppData/alist /DATA/AppData/aria2 /DATA/Media注意如果你后面打算用 Aria2 的种子功能incomplete目录所在分区的可用空间要留足BT 做种时临时文件和已完成文件会同时存在空间占用大约是文件大小的两倍。2.3 端口占用与防火墙预检端口冲突是容器起不来最常见的原因之一而且报错信息往往很隐晦——容器状态显示running但页面打不开实际上是被宿主机上另一个服务抢先占了端口。部署前先查一遍ss -lntp | grep -E 5244|5245|6800|6881Alist 用 5244 作为 Web 端口5245 是它的另一个备用端口某些版本用于内部通信Aria2 的 RPC 端口是 6800BT 监听端口建议用 6881-6999 这个区间。如果上面这几条命令有输出说明端口被占了要么改端口要么停掉占用它的服务。防火墙这块如果你的主机在局域网内其实可以不开放任何端口容器映射到宿主机的端口在局域网内默认可访问。但如果系统开了 ufw 或 firewalld就需要显式放行。我个人建议只放行真正需要的端口而且只对局域网网段放行。比如ufw allow from 192.168.1.0/24 to any port 5244这样外部即使知道你的 IP 也连不进来。下面是这套方案的端口规划参考服务容器内端口宿主机映射用途是否建议对公网开放Alist52445244Web 管理面板与文件浏览否走反向代理Aria268006800RPC 接口接收下载任务否仅容器间通信Aria26881-69996881-6999BT 监听端口是需路由器映射Aria25141351413备用 BT 端口视情况这张表里最值得琢磨的是是否建议对公网开放这一列。Alist 面板里有你的全部网盘凭据Aria2 的 RPC 接口如果不设密钥任何人都能往你硬盘里塞文件。所以这两个管理入口一律不对公网直开需要外网访问时用反向代理套一层加上 HTTPS 和访问控制。BT 端口是例外它本身就是给外部节点连的映射出去反而能提高下载速度。3. 用Docker Compose把Alist和Aria2跑起来到了动手环节。我选 Compose 而不是docker run原因是这套服务涉及多个目录挂载、多个端口映射、两个容器之间还要通信用命令行写会变成一坨几百字符的长串改一次参数就够你受的。Compose 文件是声明式的所有配置肉眼可见改完docker compose up -d就生效而且 CasaOS 的自定义应用本质上也是接收一段 compose 内容两者可以无缝切换。3.1 编写compose文件的完整思路先把完整文件贴出来然后逐段拆解。这个文件放在/DATA/AppData/alist-stack/docker-compose.yml目录名你自己定但建议统一放在/DATA/AppData下面方便 CasaOS 识别和备份。services: alist: image: xhofe/alist:latest container_name: alist restart: unless-stopped ports: - 5244:5244 volumes: - /DATA/AppData/alist:/opt/alist/data - /DATA/Media:/mnt/media environment: - PUID1000 - PGID1000 - UMASK022 - TZAsia/Shanghai networks: - alist-net aria2: image: p3terx/aria2-pro:latest container_name: aria2 restart: unless-stopped ports: - 6800:6800 - 6881-6999:6881-6999 - 6881-6999:6881-6999/udp volumes: - /DATA/AppData/aria2:/config - /DATA/Media/downloads:/downloads - /DATA/Media/incomplete:/incomplete environment: - PUID1000 - PGID1000 - UMASK022 - TZAsia/Shanghai - RPC_SECRET换成你自己的长随机串 - RPC_PORT6800 - LISTEN_PORT6881 - DISK_CACHE64M - IPV6_MODEfalse - UPDATE_TRACKERStrue networks: - alist-net networks: alist-net: driver: bridge这个文件的核心设计思路有三点。第一两个容器放在同一个自定义 bridge 网络里这样它们可以通过容器名互相访问Alist 配置 Aria2 地址时直接写http://aria2:6800/jsonrpc就行不用管宿主机的 IP 变化。第二配置目录和数据目录分开挂载/DATA/AppData下只放小文件配置/DATA/Media下放大文件备份的时候可以只备前者。第三所有可变参数走环境变量不写死在镜像里将来想改限速、改密钥改一行重启容器就行。3.2 逐段拆解参数配置的关键考量先看PUID和PGID。这两个值必须和你宿主机上目录的属主一致否则容器里的进程写文件会被拒绝。前面我们用chown 1000:1000把目录给了 uid 1000这里就填 1000。如果你的 CasaOS 第一个用户不是 1000用id 用户名查一下改成实际值。UMASK022的意思是新建文件权限为 644、新建目录为 755这个值兼顾了安全和可读性不建议改成 000。TZAsia/Shanghai影响的是容器内日志时间戳和定时任务。不设的话日志全是 UTC排查问题时对时间会疯掉。Aria2 的RPC_SECRET是整套方案里最重要的一个安全参数。它是 RPC 接口的访问令牌不设或者设成弱口令等于把你硬盘的写权限敞开给整个局域网。生成一个长随机串比如openssl rand -hex 16的输出然后记下来后面 Alist 配置的时候要原样填进去。这个值不要用生日、不要用123456也不要在截图里露出来。DISK_CACHE64M是磁盘缓存。Aria2 默认的缓存比较小高速下载时频繁写盘会造成 IO 瓶颈尤其是机械盘。给到 64M 到 128M 之间比较合适具体看你的内存余量——内存紧张就 32M内存充裕可以 128M。这个参数调大之后下载速度的稳定性会有肉眼可见的提升。LISTEN_PORT6881配合端口映射区间6881-6999意思是 Aria2 从 6881 开始监听如果被占用就往上找。映射一个区间而不是单个端口是为了让它在多任务并发时能同时开多个监听。UDP 那行是给 DHT 用的BT 网络靠它发现节点漏了这行下载速度会明显下降。UPDATE_TRACKERStrue是个很实用的小功能容器启动时会自动拉取一份公共 tracker 列表合并到配置里。BT 下载慢的一大原因就是 tracker 失效有了这个开关至少不用手动去维护列表。3.3 启动验证与首次登录文件写好后进入目录执行cd /DATA/AppData/alist-stack docker compose up -d docker compose ps docker compose logs -f alistdocker compose ps应该看到两个容器都是Up状态。如果 alist 显示Restarting多半是配置目录权限不对或者端口被占去看logs的输出。Aria2 的日志里如果出现errorCode1之类的字样通常是下载目录不可写回到上一节检查权限。Alist 首次启动时会生成一个随机管理员密码有两种方式拿到。一是在日志里找docker compose logs alist | grep -i password二是直接重置docker exec -it alist ./alist admin set 你的新密码这个命令会直接把 admin 账号的密码改成你指定的值比翻日志快。改完之后浏览器打开http://主机IP:5244用admin加新密码登录。登录进去先别急着挂网盘做两件事一是到设置 - 站点里把站点标题改成自己认得出的名字二是到用户里确认 admin 的权限范围。默认 admin 是全权限如果你只给自己用这样就行如果打算分享给家里人建议新建一个普通用户只给特定目录的读权限别把管理员账号发出去。提示Alist 的数据库文件在/DATA/AppData/alist/data.db这个文件包含了所有存储配置和账号信息定期备份它等于备份了整个 Alist。恢复的时候停容器、覆盖文件、启容器配置全回来。4. Alist挂载网盘与Aria2下载链路的打通容器跑起来只是搭好了台子真正让这套方案产生价值的是挂载和下载两条链路。挂载让 Alist 能看见内容下载让内容进得来两者还得能互相看见——Aria2 下完的文件Alist 得能立刻在目录里列出来。这一节把三条链路拆开讲每一环都有几个容易踩的点。4.1 本地存储与网盘挂载的三种典型方式Alist 的挂载入口在管理 - 存储 - 添加。驱动列表很长实际用下来可以归成三类。第一类是本地存储。驱动选本机存储挂载路径填容器内的路径比如/mnt/media/library这是我们在 compose 里把/DATA/Media映射进容器的结果。挂载完之后Alist 的目录树里就会出现你硬盘上的文件。这一类的坑最少唯一的注意点是路径必须写容器内路径不是宿主机路径。我见过有人填/DATA/Media/library结果目录永远是空的因为容器里根本没这个路径。第二类是网盘挂载。主流网盘基本都有对应的驱动配置的核心是拿到凭据。通用套路是在浏览器里登录网盘网页版按 F12 打开开发者工具在 Network 面板里找任意一个 API 请求从请求头里复制 Cookie 或者从响应里找 refresh_token粘贴到 Alist 的对应字段。不同网盘的字段名不一样有的要 Cookie有的要刷新令牌有的还要额外的参数。挂载成功后建议先在网盘根目录建一个测试文件夹确认能列出、能下载、能上传再往里放重要数据。第三类是协议挂载比如 WebDAV、SMB、FTP。这类适合挂另一台 NAS 或者路由器上的硬盘。配置相对简单填地址、账号、密码就行注意 WebDAV 的地址通常要带完整路径有些服务端还要求 HTTPS。挂载类型典型驱动关键参数常见问题本地存储本机存储容器内路径路径写成宿主机路径目录为空网盘各家网盘驱动Cookie / 令牌凭据过期需要定期更新协议WebDAV / SMB地址、账号、密码端口不通、路径少了前缀对象存储S3 兼容AK / SK / Endpoint区域填错导致签名失败挂载完别忘了在存储列表里点一下重新加载有时候配置保存了但缓存没刷新目录看起来还是空的。4.2 Aria2下载目录如何被Alist看见这条链路的关键在于两个容器看到的是同一份宿主机目录但路径名不一样。宿主机上的/DATA/Media/downloads在 Aria2 容器里叫/downloads在 Alist 容器里叫/mnt/media/downloads。三个路径指向同一份数据但你在哪个容器里操作就得用哪个路径。具体做法Alist 里添加一个本机存储挂载路径填/mnt/media/downloads挂载名可以叫下载目录。这样 Aria2 下完的文件几秒钟内就会出现在 Alist 的这个目录里。如果想让下载目录只读展示防止误删可以在存储配置里把只读打开。这里有个容易忽略的细节Aria2 下载完成的文件属主是PUID:PGID指定的那个用户权限是UMASK决定的。如果 Alist 容器用的 PUID 和 Aria2 不一样就会出现文件存在但打不开的情况。所以两个容器的PUID、PGID、UMASK三个值必须完全一致这一点在写 compose 的时候就要对齐。还有一个性能上的考量不要让 Alist 的缓存目录和 Aria2 的临时目录落在同一块慢盘上。Alist 在生成缩略图、做视频转码预览时会产生临时文件和 Aria2 的分片写入抢 IO两边都会变慢。如果条件允许把 Alist 的临时目录指到另一块盘或者 tmpfs 上。4.3 Alist离线下载对接Aria2的任务下发这是整套方案里体验最好的一环。配置好之后你在 Alist 里浏览任何一个文件或目录右键就能离线下载到指定位置任务直接交给 Aria2 执行进度在 Alist 里能看到。配置入口在管理 - 设置 - 其他 - Aria2。需要填三个字段RPC 地址、RPC 密钥、下载目录。RPC 地址填http://aria2:6800/jsonrpc注意这里用的是容器名而不是 IP因为两个容器在同一个自定义网络里Docker 内置的 DNS 会把容器名解析成容器 IP宿主机 IP 变了也不影响。密钥就是 compose 里那个RPC_SECRET的值一个字符都不能错。下载目录这个字段最容易出问题。它填的是Aria2 容器内的路径也就是/downloads不是宿主机路径也不是 Alist 的路径。填错的表现是任务能提交成功、进度也在走但下完之后文件不知道去哪了——其实是被 Aria2 写到了容器内的默认目录相当于写进了容器层容器一重建文件就没了。配置保存后回到文件列表找一个大文件点离线下载选 Aria2看任务是否出现在 Aria2 的任务列表里。可以用docker exec -it aria2 aria2c --version确认容器正常用docker logs aria2 --tail 50看有没有 RPC 相关的报错。注意Alist 的离线下载功能只是把 URL 转发给 Aria2能不能下取决于 Aria2 那边能不能访问到这个 URL。如果是网盘里的文件Alist 会先生成一个直链再交给 Aria2直链通常有有效期任务排队太久会失效表现为下载到一半报 403。4.4 权限与路径映射的三个隐蔽坑第一个坑是符号链接跨容器失效。有人在宿主机上给下载目录做了个软链接指向另一块盘然后挂载进容器。结果是宿主机上能访问容器里是断链。原因是软链接的目标路径在容器里不存在。解决办法是用 bind mount 直接挂真实路径别用软链接。第二个坑是大小写敏感。Linux 文件系统区分大小写/Downloads和/downloads是两个目录。Aria2 配置里如果写成了大写文件会写到一个新建的空目录里你在 Alist 里怎么也找不到。写完路径之后用docker exec aria2 ls -la /确认一下目录名。第三个坑是SELinux 或 AppArmor 的拦截。部分发行版默认开启强制访问控制容器即使有权限也写不进去日志里会出现Permission denied但权限明明是对的。临时验证可以把 SELinux 设成 permissive如果问题消失就说明是它拦的这时候要么给挂载加:z标签要么调整策略。5. 远程访问的几种落地方案内网跑通之后接下来就是人在外面也能用的需求。这里要说清楚一个前提远程访问的方案选择取决于你的网络环境有没有公网地址。有公网地址的和没有的走的路子完全不同硬套方案只会白折腾。5.1 先判断自己的网络环境最直接的方法是登录路由器管理页看 WAN 口拿到的 IP。如果这个 IP 是10.x.x.x、100.64.x.x、172.16-31.x.x这类私有地址说明你在运营商的大内网里没有独立的公网地址端口映射做了也没用。如果 WAN 口 IP 和你在网上查到的出口 IP 一致说明你有公网地址可以做端口映射。另一个要确认的是公网地址是不是固定的。家宽的公网 IP 通常是动态的重启光猫就变。这就需要动态域名解析DDNS——用一个域名指向你的 IP再跑一个脚本定时把域名更新成当前 IP。很多路由器自带这个功能在动态 DNS里填上服务商给的域名和凭据就行。CasaOS 主机上也可以跑一个轻量的 DDNS 容器效果一样。如果确认没有公网地址方案就得换。可选的路子有两条一是用带中转的服务把内网服务通过一条长连接暴露出去这类服务通常有免费额度但速度受限二是不做全量暴露只把需要的内容同步到某个云存储出门时从云上取。第二条路子牺牲了实时性但稳定性和安全性都更好。5.2 公网直连加端口映射的配置要点假设你有公网地址配置链路是这样的路由器上把外部某个高端口比如 15244映射到内网的主机IP:5244同时配好 DDNS然后用http://你的域名:15244访问。这套配置十分钟能搞定但有三个地方必须注意。第一不要用默认端口。5244 是 Alist 的默认端口扫描器一抓一大把改成五位数的高端口能挡掉绝大部分无差别扫描。第二映射的端口和实际端口要区分外部 15244 映射到内部 5244这样即使外部端口泄露攻击者也不知道内部服务的真实端口。第三路由器上只映射必要的端口Aria2 的 RPC 端口 6800 绝对不要映射出去它没有 HTTPS密钥是明文传输的。访问链路变成公网 → 路由器 → 主机:5244中间没有任何加密密码在公网上是明文跑的。所以这个方案只适合临时用、或者你对链路上的风险有充分认知。长期用的话还是得套一层 HTTPS。5.3 反向代理加域名的稳妥做法反向代理的作用是在你的服务和外部访问之间加一层由它来终结 HTTPS、做访问控制、隐藏后端真实端口。常见的做法是跑一个 Nginx Proxy Manager 容器在它的界面里添加一条代理规则域名填pan.你的域名.com转发地址填alist:5244同样用容器名开启 SSL申请一张 Lets Encrypt 证书。这样外部访问https://pan.你的域名.com流量在代理这一层就被解密再以明文转发给 Alist但因为代理和 Alist 在同一台机器、同一个 Docker 网络里这段明文不出主机风险可控。证书自动续期不用操心。路由器上只需要映射 80 和 443 两个端口其余的都不开。反向代理配置里有几个参数值得调。client_max_body_size要调大默认 1M 会导致上传大文件失败设成0表示不限制。proxy_read_timeout也要调大Alist 在做大目录列表或者视频流播放时响应可能超过默认的 60 秒。如果要在浏览器里直接播放视频还得确保代理不缓冲响应体否则拖动进度条会卡。提示反向代理之后再套一层访问控制会更稳。Nginx Proxy Manager 支持添加 Access List可以限制只允许特定 IP 段访问或者加一道基础的账号密码验证。管理面板这种入口多一层验证不亏。5.4 远程访问的安全加固清单把管理面板暴露到公网等于把家门钥匙挂在门口。下面这几条是我每次部署完都会过一遍的清单。加固项具体做法为什么重要强制 HTTPS反向代理申请证书HTTP 自动跳转防止密码和 Cookie 明文传输改默认路径Alist 设置里改管理路径扫描器找不到登录入口强密码16 位以上随机串不用重复密码防撞库关闭匿名访问访客权限设为仅特定目录防止目录被遍历限制来源代理层加 IP 白名单缩小攻击面关闭 RPC 外网6800 端口不映射Aria2 RPC 无加密定期更新镜像跟随最新稳定版修复已知漏洞日志审计定期看登录日志发现异常尝试其中改管理路径这一条成本最低、收益很高。Alist 默认的管理入口是/manage扫描器都知道改成/mysecretpanel这种随机串被扫到的概率直线下降。设置位置在管理 - 设置 - 站点 - 管理路径。6. 常见问题排查实录下面这些问题是这几年反复遇到、也被问得最多的按现象归类整理。排查的基本原则是先看容器状态再看日志最后才怀疑配置。九成的故障在前两步就能定位。6.1 容器起来了但页面打不开先执行docker compose ps确认状态是Up而不是Restarting或Exited。如果是Restarting看docker compose logs alist的最后几十行常见原因有三个配置目录权限不对导致程序无法写数据库端口被占用镜像架构不匹配比如在 ARM 设备上拉了 amd64 的镜像。如果状态正常但浏览器打不开分三步排查。第一步在主机上curl -I http://127.0.0.1:5244如果有响应说明服务本身正常问题在网络层如果没响应说明服务没监听在预期端口上去日志里找监听地址。第二步从局域网另一台设备访问http://主机IP:5244如果这台能开而那台不能检查防火墙规则。第三步如果局域网能开、远程不能开回到端口映射和 DDNS 那两节。还有一种情况是页面能打开但一直转圈最后超时。这通常是反向代理的proxy_read_timeout太短或者代理和后端之间的网络不通。在代理容器里curl http://alist:5244测一下能通就是超时配置问题。6.2 Aria2 RPC连接失败Alist 里点离线下载提示提交失败或者无法连接 Aria2按这个顺序查。先确认 Aria2 容器活着docker ps | grep aria2。再确认 RPC 端口在监听docker exec aria2 netstat -lntp | grep 6800。然后从 Alist 容器内部测试连通性docker exec -it alist sh -c wget -qO- http://aria2:6800/jsonrpc如果返回 404 或者一段 JSON说明网络通如果卡住或者报解析失败说明两个容器不在同一个网络里。密钥错误的表现是返回{error:{code:1,message:Unauthorized}}。这时候核对 compose 里的RPC_SECRET和 Alist 里填的是否一致注意前后空格和大小写。改完 compose 要docker compose up -d重建容器才生效只重启不重建不会更新环境变量。还有一个小概率情况Aria2 的 RPC 监听地址默认是0.0.0.0但某些镜像配置成了127.0.0.1这时候容器内部能访问跨容器就访问不到。看docker exec aria2 cat /config/aria2.conf | grep rpc-listen-all确认是true。6.3 网盘挂载后目录为空或加载慢挂载显示正常但目录里什么都没有先点一次重新加载。如果还是空去存储里点开那个挂载项看状态是不是有报错信息。最常见的错误是凭据失效——网盘的 Cookie 有有效期短则几天长则几个月过期后挂载状态会变成错误需要重新抓取。加载慢是另一类问题。网盘的文件列表接口本身有延迟尤其是目录里文件很多的时候一次请求可能拉取几十页。Alist 有缓存机制第一次加载慢后续会快。可以在存储配置里调大缓存过期时间代价是网盘那边新增的文件不会立刻显示。如果用的是本地存储还慢那多半是磁盘 IO 打满了检查是不是 Aria2 正在满速下载。还有一种诡异情况目录能列出来但点开文件下载报错。这通常是网盘对直链做了防盗链或者限速Alist 生成的直链需要特定的请求头。可以换一个代理模式试试——Alist 的存储配置里有个Web 代理开关打开后下载流量会经过 Alist 中转绕过防盗链代价是占用主机的带宽。6.4 重启后配置丢失或任务清空配置丢失一般是挂载路径写错了容器把数据写在了容器内部而不是挂载卷上。验证方法docker inspect alist | grep -A 10 Mounts看/opt/alist/data是否指向了宿主机的实际目录。如果显示的是匿名卷说明 compose 里的路径写错了。Aria2 重启后任务列表清空是因为会话文件没有持久化。Aria2 需要一个aria2.session文件来保存任务状态配置项是save-session和input-file分别指向保存路径和加载路径。这两个路径必须落在挂载出来的/config目录里否则容器一重建就没了。检查docker exec aria2 cat /config/aria2.conf | grep session确认两个路径都是/config/aria2.session。下面这张表可以贴在便签上出问题的时候按现象对照现象最可能原因快速验证解决页面 502代理连不上后端代理容器内 curl 后端检查容器名和网络页面超时读超时太短看代理日志调大 timeout上传失败请求体大小限制看代理报错调大 body size下载 0 速度BT 端口未映射检查端口映射映射 6881-6999离线任务不出现RPC 地址填错容器内 wget 测试改用容器名文件找不到路径写成宿主机路径容器内 ls改成容器内路径权限拒绝PUID 不一致对比两容器环境变量统一 PUID/PGID重启丢配置未挂载配置目录docker inspect修正 volumes6.5 我踩过的两个非典型坑第一个是磁盘满了但df显示还有空间。原因是 Aria2 删除任务时如果文件正被 Alist 读取比如正在播放文件句柄没释放空间不会立刻回收。用lsof | grep deleted能看到这些已删除但仍被占用的文件重启相关容器就能释放。预防办法是删除任务前先确认没有正在播放的会话。第二个是容器时间跳变导致证书续期失败。有段时间我发现 HTTPS 证书总是续不上查了半天发现是主机的 NTP 同步出了问题容器时间比实际慢了十几分钟Lets Encrypt 的校验直接失败。修好时间同步之后一切正常。这个坑很隐蔽因为服务本身跑得好好的只有依赖时间的功能会出问题。7. 长期维护与几个实用配置部署只是开始这套东西要长期稳定跑还得管住三件事更新、备份、限速。这三件事都不复杂但拖延的代价很大——尤其是备份等到数据出问题再想起来就晚了。7.1 更新策略与回滚准备Alist 的更新节奏快不建议无脑追最新版。我的做法是每季度看一次更新日志如果只是小版本修复就等一两个版本再升涉及安全修复的立刻升。升级前先备份/DATA/AppData/alist整个目录然后改 compose 里的镜像 tag建议用具体版本号而不是latest方便回滚执行docker compose pull docker compose up -d。用具体版本号而不是latest的好处是可控。latest每次 pull 都可能是新版本出问题时你连回退到哪个版本都不知道。写成xhofe/alist:v3.x.x这种形式出问题改回上一个版本号重新拉就行。Aria2 的镜像相对稳定半年更新一次足够。但要注意Aria2 的配置文件格式在不同镜像之间可能有差异换镜像之前把/DATA/AppData/aria2备份一份出问题直接覆盖回去。7.2 限速与资源占用的平衡家里带宽有限的话Aria2 满速下载会把整个网络拖垮看视频都卡。限速在 Aria2 的配置文件里设两个关键项max-overall-download-limit和max-overall-upload-limit单位是字节每秒。比如想限制到 10MB/s就填10M。这两个值可以在运行时通过 RPC 动态调整不用重启容器。限速的时机也有讲究。白天家里有人用网限到 5M凌晨自动放开到满速。这个可以用 Aria2 的 RPC 接口加一个定时任务实现也可以简单点在 Alist 里手动切。我自己的做法是给 Aria2 设一个全局上限然后在路由器上对这台主机做 QoS 限速双保险。CPU 占用方面Aria2 在下载大文件时会做分片校验单核可能跑满。如果主机核心少把--max-concurrent-downloads调到 3 到 5别贪多。Alist 本身很轻但如果开了缩略图生成浏览图片目录时 CPU 会飙一下这个可以把缩略图功能关掉换响应速度。提示incomplete目录记得定期清理。任务失败或者被取消后临时分片文件有时候会残留时间长了能占几十 GB。写个定时任务每周清理一次超过七天的残留文件能省不少空间。最后分享一个我自己一直在用的小习惯给每个容器的 compose 文件都加一行labels写上部署日期和用途备注。半年后回头看一眼就能知道这个容器是干嘛的、什么时候装的、当时为什么这么配。这台机器上的服务越堆越多没有备注的话半年后自己都认不出来哪个是哪个。
