家里那台常年吃灰的小主机装上 CasaOS 之后我一直想把它变成能干活的设备白天在单位想取家里的资料晚上想把散落在几个网盘里的内容统一到一个入口看顺手还能挂个后台下载把别人分享的种子和大文件直接落到网盘目录里。折腾了几轮最后落地的是一套比较稳的组合——CasaOS 管系统和容器Docker 跑服务Alist 把各处存储聚合成一个 Web 入口Aria2 挂在后面做离线下载Alist 再反过来调用 Aria2把任务直接写进指定目录。这套 AlistAria2 的玩法在 NAS 圈子里讨论得很多但真正上手会卡在权限、路径映射、端口冲突、RPC 鉴权这几个地方网上的教程大多只给一段 compose剩下的坑得自己踩。下面这篇就是我把整套流程重新梳理一遍的结果从目录规划到容器编排从网盘挂载到下载路径对齐再到怎么在家里其他设备上稳定访问尽量把每一步为什么这么做说清楚。适合手里有 CasaOS 或者任意一台装了 Docker 的 Linux 小主机、想搭一个私人文件入口的朋友新手照着抄也能跑起来有基础的可以直接看路径映射和安全加固那几节。1. 这套组合到底在解决什么问题1.1 三个组件各自的角色定位先把分工讲清楚不然后面配置很容易乱。CasaOS 本身不是一个网盘系统它更像是一个给家庭小主机套上的外壳底层还是标准的 Linux上面加了一层 Web 管理界面、应用商店、文件浏览和容器管理。你在它界面里点安装应用本质上就是它在后台生成了一份 docker compose 文件然后执行所以完全可以把 CasaOS 理解成一个可视化的 Docker 面板只不过预设了一堆家庭场景常用的应用模板。Alist 是这套方案的核心。它是一个用 Go 写的文件列表服务最大的价值是把各种来源的存储——本机硬盘目录、WebDAV 服务、对象存储、各家网盘的开放接口——统一挂成一个个存储然后对外提供一个网页界面和一套 WebDAV 接口。也就是说你在浏览器里打开一个地址就能像翻本地文件夹一样翻好几个网盘支持 WebDAV 的播放器、文件管理器也能直接连上来把它当成一个总入口。它自己不存文件只负责列目录、转请求、发链接这个定位很关键。Aria2 是下载引擎。它轻量、支持 HTTP/FTP/BT/磁力命令行就能跑但它最有用的地方是提供了 RPC 接口——也就是说它可以只当后台服务界面交给别人做。Alist 内置了对 Aria2 RPC 的调用能力你在 Alist 里选中一个网盘目录点离线下载填个链接任务就会甩给 Aria2 去跑跑完的文件落在 Alist 挂载的那个目录里。这套联动是整篇文章的重点也是最多人配置失败的地方。1.2 为什么坚持用 Docker 而不是原生安装有人会问Alist 就一个二进制文件直接下载跑起来不就行了何必绕一圈 Docker。我试过两种方式最后还是回到容器。原因有三个。第一是依赖和版本管理Alist 迭代很快原生安装要自己写 systemd 服务、自己处理升级容器只需要改个 tag 重新拉镜像回滚也就是改回去。第二是隔离Aria2 要监听端口、要写配置文件、要处理 BT 的端口映射跑在容器里出问题不会污染宿主机环境删掉容器目录就干净了。第三是 CasaOS 的天然契合它的应用管理就是围绕 compose 设计的你手写一份 compose 放进它的应用目录界面上就能看到状态、日志、启停按钮比纯命令行舒服。注意CasaOS 应用商店里确实有 Alist 的一键安装但那份模板的路径和网络模式是写死的后期要改挂载目录、要接 Aria2还是得改 compose 文件。与其装完再改不如一开始就自己写一份放到自定义应用目录里主动权在自己手上。1.3 网络模式选型与端口规划这是第一个必须想清楚的问题。Docker 默认的 bridge 模式会给容器分配一个内网 IP外部访问要靠端口映射host 模式则直接共用宿主机网络栈容器里的端口就是宿主机的端口不需要映射也不会有 NAT 转换。对这套组合我的建议是两个容器都用 host 模式。原因很实际Aria2 做 BT 下载时需要监听一个端口供其他节点连入走 bridge 模式虽然能映射但涉及多层转换做种和连接成功率会打折扣Alist 用 host 模式则可以省掉一层端口映射的心智负担反代的配置也更直接。代价是端口不能冲突规划的时候要提前避开。组件容器内端口host 模式下的宿主机端口用途Alist52445244Web 管理界面与 WebDAVAria268006800RPC 接口供 Alist 与前端调用Aria268886888BT 监听端口TCPUDP反向代理可选80/44380/443域名访问与 HTTPS端口不是随便挑的选之前先用ss -lntp看一眼有没有被占用。5244 和 6800 都是这两个项目的默认值保持默认有个好处以后看别人的配置、查文档不用做心算换算。如果你家里还有别的服务占了这些端口改 compose 里的环境变量就行但改完记得同步改反向代理和 Alist 里的 RPC 地址。2. 部署前的准备工作2.1 CasaOS 环境自检清单动手之前先确认几件事能省掉后面一大半的排查时间。第一确认 Docker 和 compose 都正常CasaOS 装好之后一般就有了但版本太老可能会不认新版 compose 的语法docker compose version看一眼建议 2.x 以上。第二确认宿主机时间正确容器默认继承宿主机时区如果宿主机时间跑偏Alist 里显示的修改时间会全乱日志时间也对不上排查问题时会误导你。第三确认磁盘空间和挂载点。CasaOS 的默认数据目录一般在/DATA下面但如果你外挂了硬盘实际路径可能是/mnt/xxx之类这个路径要原样写进 compose写错了容器起得来但目录是空的。第四确认权限CasaOS 首次初始化会创建一个普通用户uid 通常是 1000容器里跑的服务也建议用这个 uid不然下载下来的文件属主是 root你在 CasaOS 的文件管理里想删都删不掉。# 环境自检三连 docker compose version date lsblk -f id2.2 目录结构怎么规划才不返工目录规划看着琐碎其实是最容易返工的地方。我踩过的坑是一开始把 Alist 的数据目录和下载目录混在一起后来想单独备份配置发现整个目录几十个 G备份脚本直接卡死。正确的做法是配置和数据进行物理分离。我现在的结构是这样/DATA/AppData/alist放 Alist 的数据库和配置体积小随时可以打包备份/DATA/AppData/aria2放 Aria2 的会话文件和配置也不大/DATA/Downloads是真正的下载落地区单独一个大目录。三个目录都属于同一个用户权限统一。sudo mkdir -p /DATA/AppData/alist /DATA/AppData/aria2 /DATA/Downloads sudo chown -R 1000:1000 /DATA/AppData /DATA/Downloads sudo chmod -R 755 /DATA/AppData /DATA/Downloads提示如果你打算让下载任务直接落到某个网盘目录里而不是本地磁盘那/DATA/Downloads这个位置反而没那么重要但本地目录还是建议保留用来做临时缓存和测试出问题的时候能快速判断是网盘那边的问题还是下载器的问题。2.3 自定义应用的存放位置CasaOS 的自定义应用目录在/var/lib/casaos/apps/下面每个应用一个子目录里面放一份docker-compose.yml。你把文件写进去重启一下 CasaOS 的服务或者刷新界面它就能识别出来。这个机制的好处是你写的 compose 完全由自己掌控不会被商店模板覆盖。sudo mkdir -p /var/lib/casaos/apps/alist-aria2 sudo nano /var/lib/casaos/apps/alist-aria2/docker-compose.yml写完保存然后sudo systemctl restart casaos或者直接在界面里刷新就能在应用列表里看到。当然你也可以完全绕开 CasaOS直接在任意目录docker compose up -d效果一样只是少了界面管理。我倾向于放进 CasaOS 目录因为家里人偶尔要用的时候点界面比敲命令友好得多。3. 用 Compose 拉起 Alist 与 Aria23.1 compose 文件逐段拆解下面这份是我目前在用的两个服务都用 host 网络挂载路径统一。每一段后面我会解释为什么这么写。services: alist: image: xhofe/alist:latest container_name: alist restart: unless-stopped network_mode: host volumes: - /DATA/AppData/alist:/opt/alist/data - /DATA/Downloads:/downloads environment: - PUID1000 - PGID1000 - UMASK022 - TZAsia/Shanghai aria2: image: p3terx/aria2-pro:latest container_name: aria2 restart: unless-stopped network_mode: host volumes: - /DATA/AppData/aria2:/config - /DATA/Downloads:/downloads environment: - PUID1000 - PGID1000 - UMASK_SET022 - RPC_SECRET换成一串足够长的随机字符 - RPC_PORT6800 - LISTEN_PORT6888 - DISK_CACHE64M - IPV6_MODEfalse - UPDATE_TRACKERStrue - TZAsia/Shanghai几个关键决策说明一下。restart: unless-stopped保证主机重启或者容器异常退出后自动拉起家庭设备经常断电这个必须加。PUID/PGID决定容器内进程以哪个用户身份写文件设成 1000 就和你 SSH 登录的普通用户对上了。UMASK022意味着新建文件权限是 644、目录是 755同一台机器上的其他服务也能读不会出现下载完了但播放器读不了的情况。DISK_CACHE64M是磁盘缓存适当设置能减少小文件写入时的碎片但别设太大内存紧张的小主机会被拖垮。UPDATE_TRACKERStrue让容器启动时自动更新 BT 追踪器列表这个非常关键很多人的 BT 下载没速度就是因为追踪器列表太旧连不上节点。RPC_SECRET是 Aria2 的调用密钥一定要改成长随机串后面 Alist 和前端都要填它。注意host 模式下不能再写ports:段两个同时存在 compose 会直接报错。第一次写的时候我在这卡了十几分钟报错信息还不算直观。3.2 Aria2 配置文件里几个容易忽略的参数容器第一次启动会在/DATA/AppData/aria2下生成aria2.conf有几个默认值我建议手动调一下。一个是max-concurrent-downloads默认 5 对家庭带宽够用但如果你经常一次性甩十几个任务进去可以改成 3 到 5别设太高小主机的磁盘并发写会撑不住。另一个是file-allocation默认可能是prealloc也就是下载前先把整个文件大小的空间预分配出来。这个在大文件上体验很差——一个 40G 的种子点下去磁盘立刻少 40G而且预分配过程本身要花时间机械盘上能卡好几分钟看起来像卡死。改成none之后就是边下边写空间按实际进度占用心理感受好很多。还有seed-time控制做种时长如果你不打算长期做种设成0或者一个很小的值下完就停避免长时间占着连接和带宽。bt-tracker那一行通常由容器自动维护不需要手动改但如果你关闭了自动更新就要自己定期去拉一份新的列表替换不然 BT 就是龟速。max-concurrent-downloads5 file-allocationnone continuetrue seed-time0 disk-cache64M rpc-save-upload-metadatatrue3.3 启动、验证与首次登录文件写好后执行docker compose up -d或者用 CasaOS 界面点启动。然后看日志确认两个服务都正常起来了。docker compose ps docker logs --tail 50 alist docker logs --tail 50 aria2Alist 的日志里会打印一行初始管理员密码这个密码只显示一次复制下来。新版 Alist 出于安全考虑改成了随机初始密码不再是早期的固定值所以必须看日志别去网上抄旧教程里的默认密码抄了也登不上。浏览器打开http://宿主机内网IP:5244用账号admin和你日志里拿到的密码登录。进去第一件事就是改密码改成你自己记得住的强密码顺手把用户名也改掉admin 这个默认名太显眼。Aria2 的验证稍微麻烦一点它没有网页界面得用一个支持 RPC 的前端去连。我一般用 AriaNg纯静态页面随便丢到一个能访问的目录里就行。验证方式是填 RPC 地址http://内网IP:6800/jsonrpc和刚才设置的RPC_SECRET连上之后能看到下载列表就说明通了。3.4 挂载网盘的实操流程登录 Alist 之后左侧菜单进存储点添加选对应的驱动类型。这里每个驱动的字段都不一样但逻辑是统一的给一个挂载路径也就是它在你 Alist 目录树里显示的位置然后填授权信息。以需要授权的那类网盘为例流程通常是这样的先去对方的开放平台创建一个应用拿到客户端 ID 和密钥把回调地址填成 Alist 提供的那一串然后浏览器打开授权链接登录后拿到一串授权码或者刷新令牌粘回 Alist。整个过程不复杂但有两个坑。一个是回调地址必须完全一致多一个斜杠都会失败另一个是令牌有有效期过期之后挂载会报错需要重新授权所以别把刷新令牌弄丢最好备份一份。挂载路径建议做成分层结构比如/网盘A、/网盘B、/本地/downloads一眼能看出哪个是哪个。挂载完点进去看看能不能列目录能列说明配置对了但先别急着测试下载下一步的路径映射没对齐的话下载完照样找不到文件。4. Alist 与 Aria2 的联动配置4.1 为什么要在 Alist 里配置 Aria2Alist 本身不带下载能力它调用 Aria2 的方式是发一条 RPC 请求过去告诉对方下载这个链接存到这个路径。所以配置的核心就两件事告诉 Alist 去哪里找 Aria2以及告诉 Aria2 把文件放在哪里。进 Alist 后台的设置找其他那一栏能看到 Aria2 的相关配置项。地址填http://127.0.0.1:6800/jsonrpc——因为两个容器都用 host 网络Alist 和 Aria2 在同一台机器的网络空间里直接用回环地址最省事。如果你用的是 bridge 网络这里就要填 Aria2 的容器名或者内网 IP。密钥填RPC_SECRET的值和 Aria2 那边一模一样。提示填完先点一下测试或者直接去文件列表里试一个离线下载任务。如果提示 401 或者 unauthorized九成是密钥不一致如果提示连接被拒绝那是地址或端口错了如果提示找不到路径那就是下一节要讲的路径映射问题。4.2 路径映射整套方案里最容易翻车的地方这个坑我踩过不止一次。原理其实很简单Alist 认为的路径和 Aria2 认为的路径必须是同一个物理位置在容器内的同一个字符串。举个人话的例子你跟快递员说放 3 号楼 502 的门口和收件人以为的放在小区门口的柜子里只要说法不一致,东西就找不到了。具体到配置上Aria2 容器把/DATA/Downloads挂载到了内部/downloads那就意味着 Aria2 只认得/downloads这个路径你说/DATA/Downloads它完全不认识。而 Alist 那边如果要调用它下载到本地目录也必须用/downloads。所以正确做法是让两个容器挂载同一个宿主机目录到同一个容器内路径# 两个容器里都这么写路径字符串必须完全一致 - /DATA/Downloads:/downloads然后在 Alist 里把本地存储的挂载路径也设成/downloads对应的目录。听起来很绕但只要你保证宿主机目录 → 容器内路径这个映射在两个容器里完全一样问题就消失了。如果你的目标是下载到网盘而不是本地情况会稍微复杂一点。Alist 把网盘挂载成了自己的一个目录但 Aria2 是看不到这个虚拟目录的它只能写本地文件系统。所以直接下载到网盘这件事Alist 的实现方式是先下到本地某个目录完成之后再由 Alist 上传到网盘。这个中转目录必须两个容器都能访问配置的时候要额外注意。场景Aria2 里的路径Alist 里的路径是否需要中转下载到本地盘/downloads/downloads不需要下载后转存网盘/downloads/temp网盘目录 本地 temp需要且两边挂载要一致只做 BT 缓存/downloads不挂载不需要4.3 AriaNg 前端放到 Alist 背后AriaNg 的接入方式有两种。一种是单独跑一个容器端口另开一个比如 6880然后反代出去另一种更省事——把 AriaNg 的静态文件丢进 Alist 的一个本地存储目录里通过 Alist 的路径直接访问。后者的好处是只需要维护一个入口登录 Alist 之后就能看下载进度不用再记一个端口。具体做法是下载 AriaNg 的发布包解压到一个目录比如/DATA/Downloads/ariang然后在 Alist 里把这个目录挂成本地存储路径设为/ariang。之后访问http://内网IP:5244/ariang/就能打开。第一次打开会要求填 RPC 地址填http://内网IP:6800/jsonrpc加密钥保存之后就能看到任务列表。这个方式有个小细节Alist 对静态文件的处理是走它自己的文件服务所以 AriaNg 的index.html必须能被正确识别。如果打开是一片空白多半是路径层级搞错了检查一下 Alist 里挂载的根路径是不是直接指向包含 index.html 的那一层。5. 远程访问的几种方式与安全边界5.1 先把局域网访问跑通任何远程访问方案的基础都是局域网内先跑通。这一步没验证就去做外网配置出问题你根本分不清是本地服务的问题还是网络链路的问题。验证方法很直接在同一路由器下的手机或者笔记本上浏览器打开http://宿主机内网IP:5244能登录、能列目录、能看视频就说明服务本身没问题。如果这一步打不开先排查防火墙。很多发行版默认开了防火墙规则5244 端口没放行外面就连不上。用ss -lntp | grep 5244确认服务确实在监听再用curl -I http://127.0.0.1:5244在机器本机测一下。本机能通、局域网不通那就是防火墙或者网络隔离的问题跟 Docker 无关。还有个小提醒给宿主机配一个固定的内网 IP或者在路由器上做 DHCP 静态绑定。不然路由器重启后 IP 变了你存的收藏夹全失效家里人也会抱怨昨天还能打开今天就不行了。5.2 出门在外怎么连域名、反代与 HTTPS如果在家里以外的地方也要访问通常有两类做法。一类是家里宽带有固定的公网地址那就把域名解析过去前面架一层反向代理配上证书走 HTTPS。另一类是地址不固定借助动态解析把变化的地址映射到域名上效果类似。这里我不展开具体服务商和配置细节各家方案差异太大只说通用的思路和安全要求。反向代理建议单独跑一个容器比如常见的 Nginx 管理面板或者 Caddy它们能自动申请和续期证书省掉手动折腾证书的时间。代理配置里最关键的是把 WebSocket 透传打开Alist 的部分功能依赖长连接如果反代没配好会出现页面能打开但操作没反应的情况。另外要把上传体积限制调大否则大文件上传会被拦在网关这一层。注意把管理界面直接暴露在公网上是有风险的暴力破解、爬虫扫描都是常态。如果只是自己用我更推荐先在局域网内用需要外部访问时再单独开一条通道而不是常年挂着公网入口。真要开前面说的几条加固措施一条都不能省。5.3 访问安全加固清单这部分比功能配置更重要。我整理了一份自己每次部署都会过一遍的清单按重要性排序。加固项具体做法不做的后果改默认账号登录后立刻改用户名和密码默认名被字典攻击首选强密码长度 16 位以上混合字符弱密码几小时被爆破关闭匿名访问存储设置里勾选需要登录任何人都能翻你的网盘开启两步验证Alist 支持基于时间的一次性口令密码泄露后仍有一道门限制管理入口反代层面只允许特定来源访问后台暴露给全网扫描器定期看日志留意异常登录和大量 404被扫了都不知道两步验证这个功能很多人忽略但在公网环境下它几乎是必须的。开启方式是在个人设置里绑定一个验证器应用扫码之后每次登录要额外输六位数字。麻烦是麻烦了一点但换来的是密码泄露也不会立刻失守。还有一点别用同一个密码。Alist 的密码、Aria2 的 RPC 密钥、反向代理的后台密码各用各的尤其是 RPC 密钥它本质上是谁拿到谁就能让你的机器下载任意文件的凭证泄露了会被当成下载跳板后果比想象中严重。6. 常见问题与排查实录6.1 故障速查表下面这些是我在实际部署和帮别人看配置时反复遇到的按现象归类方便对症下药。现象最可能的原因排查与解决容器起来了但网页打不开端口被占用或防火墙拦截ss -lntp查监听放行端口登录提示密码错误用了旧教程的默认密码docker logs alist找初始密码Alist 连不上 Aria2密钥不一致或地址写错核对 RPC_SECRET 与端口BT 下载一直是 0追踪器列表过旧开启自动更新或手动替换 tracker下载完成但 Alist 找不到两个容器路径映射不一致统一容器内路径字符串网盘挂载报 401/403授权令牌过期重新走一遍授权流程视频能列不能播反代没透传 Range 请求反代配置放行 Range 头下载的文件删不掉属主是 root检查 PUID/PGID 设置中文文件名乱码容器 locale 缺失设置 LANG 环境变量时间显示差 8 小时时区没设加 TZAsia/Shanghai6.2 几个我踩过的坑和独家处理技巧第一个坑是文件权限。早期我图省事没设 PUID容器以 root 跑下载下来的文件属主是 root用普通用户 SSH 登录进去rm都删不掉还得sudo。后来统一设成 1000这个问题再没出现过。如果你已经踩了补救办法是用chown -R 1000:1000批量改一次但注意别对着系统目录乱跑这条命令。第二个坑是 BT 端口。Aria2 的监听端口如果没在路由器上做端口映射虽然还能下载但只能连主动连出去的节点速度和连接数会明显偏低。这个不是必须做但做了体验差别很大。做映射的时候 TCP 和 UDP 都要开只开 TCP 会少掉一部分节点。第三个坑是反向代理下的上传。Alist 往网盘传大文件时如果前面的代理没调大client_max_body_size之类的限制传到一半会返回 413看起来像是网盘那边拒绝其实是网关拦了。这个错误很难从日志直接看出来需要去反代容器的日志里翻。第四个坑是 Alist 的数据库。它的配置都存在一个本地数据库文件里这个文件如果损坏所有挂载配置全丢。所以我在部署完、配置调通之后会立刻把/DATA/AppData/alist整个目录打包备份一份放到另一块盘上。后面每次加重要存储之前也备份一次成本很低但能救命。提示升级镜像之前一定先备份配置目录。Alist 迭代很快偶尔会有数据结构变化的版本直接pull最新版然后重启有小概率起不来。备份了最多回滚一次没备份就得从头配一遍所有挂载。6.3 性能调优的一点经验小主机资源有限几个参数值得调。Aria2 的并发数不要贪多5 个同时下载对大多数家庭带宽已经吃满了设成 16 反而会让每个任务都变慢还容易把磁盘 IO 打满导致整个系统卡顿。磁盘缓存 64M 是个比较平衡的值内存小于 2G 的机器建议降到 32M。Alist 这边主要关注的是网盘接口的请求频率。如果你挂了很多存储又在文件列表页面不停刷新会触发对方的限流表现为目录加载转圈或者报错。解决办法是在存储设置里适当调大缓存时间减少不必要的请求。另外不要在同一次操作里同时展开好几个大目录逐个来会稳很多。最后说一个我自己的使用习惯把常用的几个目录做成 Alist 的别名或者直接收藏放在首页。这样家里人打开就能用不需要理解目录结构也不需要记路径。技术方案再漂亮如果只有你自己会用那它的价值就打了一半折扣。
家里那台常年吃灰的小主机装上 CasaOS 之后我一直想把它变成能干活的设备白天在单位想取家里的资料晚上想把散落在几个网盘里的内容统一到一个入口看顺手还能挂个后台下载把别人分享的种子和大文件直接落到网盘目录里。折腾了几轮最后落地的是一套比较稳的组合——CasaOS 管系统和容器Docker 跑服务Alist 把各处存储聚合成一个 Web 入口Aria2 挂在后面做离线下载Alist 再反过来调用 Aria2把任务直接写进指定目录。这套 AlistAria2 的玩法在 NAS 圈子里讨论得很多但真正上手会卡在权限、路径映射、端口冲突、RPC 鉴权这几个地方网上的教程大多只给一段 compose剩下的坑得自己踩。下面这篇就是我把整套流程重新梳理一遍的结果从目录规划到容器编排从网盘挂载到下载路径对齐再到怎么在家里其他设备上稳定访问尽量把每一步为什么这么做说清楚。适合手里有 CasaOS 或者任意一台装了 Docker 的 Linux 小主机、想搭一个私人文件入口的朋友新手照着抄也能跑起来有基础的可以直接看路径映射和安全加固那几节。1. 这套组合到底在解决什么问题1.1 三个组件各自的角色定位先把分工讲清楚不然后面配置很容易乱。CasaOS 本身不是一个网盘系统它更像是一个给家庭小主机套上的外壳底层还是标准的 Linux上面加了一层 Web 管理界面、应用商店、文件浏览和容器管理。你在它界面里点安装应用本质上就是它在后台生成了一份 docker compose 文件然后执行所以完全可以把 CasaOS 理解成一个可视化的 Docker 面板只不过预设了一堆家庭场景常用的应用模板。Alist 是这套方案的核心。它是一个用 Go 写的文件列表服务最大的价值是把各种来源的存储——本机硬盘目录、WebDAV 服务、对象存储、各家网盘的开放接口——统一挂成一个个存储然后对外提供一个网页界面和一套 WebDAV 接口。也就是说你在浏览器里打开一个地址就能像翻本地文件夹一样翻好几个网盘支持 WebDAV 的播放器、文件管理器也能直接连上来把它当成一个总入口。它自己不存文件只负责列目录、转请求、发链接这个定位很关键。Aria2 是下载引擎。它轻量、支持 HTTP/FTP/BT/磁力命令行就能跑但它最有用的地方是提供了 RPC 接口——也就是说它可以只当后台服务界面交给别人做。Alist 内置了对 Aria2 RPC 的调用能力你在 Alist 里选中一个网盘目录点离线下载填个链接任务就会甩给 Aria2 去跑跑完的文件落在 Alist 挂载的那个目录里。这套联动是整篇文章的重点也是最多人配置失败的地方。1.2 为什么坚持用 Docker 而不是原生安装有人会问Alist 就一个二进制文件直接下载跑起来不就行了何必绕一圈 Docker。我试过两种方式最后还是回到容器。原因有三个。第一是依赖和版本管理Alist 迭代很快原生安装要自己写 systemd 服务、自己处理升级容器只需要改个 tag 重新拉镜像回滚也就是改回去。第二是隔离Aria2 要监听端口、要写配置文件、要处理 BT 的端口映射跑在容器里出问题不会污染宿主机环境删掉容器目录就干净了。第三是 CasaOS 的天然契合它的应用管理就是围绕 compose 设计的你手写一份 compose 放进它的应用目录界面上就能看到状态、日志、启停按钮比纯命令行舒服。注意CasaOS 应用商店里确实有 Alist 的一键安装但那份模板的路径和网络模式是写死的后期要改挂载目录、要接 Aria2还是得改 compose 文件。与其装完再改不如一开始就自己写一份放到自定义应用目录里主动权在自己手上。1.3 网络模式选型与端口规划这是第一个必须想清楚的问题。Docker 默认的 bridge 模式会给容器分配一个内网 IP外部访问要靠端口映射host 模式则直接共用宿主机网络栈容器里的端口就是宿主机的端口不需要映射也不会有 NAT 转换。对这套组合我的建议是两个容器都用 host 模式。原因很实际Aria2 做 BT 下载时需要监听一个端口供其他节点连入走 bridge 模式虽然能映射但涉及多层转换做种和连接成功率会打折扣Alist 用 host 模式则可以省掉一层端口映射的心智负担反代的配置也更直接。代价是端口不能冲突规划的时候要提前避开。组件容器内端口host 模式下的宿主机端口用途Alist52445244Web 管理界面与 WebDAVAria268006800RPC 接口供 Alist 与前端调用Aria268886888BT 监听端口TCPUDP反向代理可选80/44380/443域名访问与 HTTPS端口不是随便挑的选之前先用ss -lntp看一眼有没有被占用。5244 和 6800 都是这两个项目的默认值保持默认有个好处以后看别人的配置、查文档不用做心算换算。如果你家里还有别的服务占了这些端口改 compose 里的环境变量就行但改完记得同步改反向代理和 Alist 里的 RPC 地址。2. 部署前的准备工作2.1 CasaOS 环境自检清单动手之前先确认几件事能省掉后面一大半的排查时间。第一确认 Docker 和 compose 都正常CasaOS 装好之后一般就有了但版本太老可能会不认新版 compose 的语法docker compose version看一眼建议 2.x 以上。第二确认宿主机时间正确容器默认继承宿主机时区如果宿主机时间跑偏Alist 里显示的修改时间会全乱日志时间也对不上排查问题时会误导你。第三确认磁盘空间和挂载点。CasaOS 的默认数据目录一般在/DATA下面但如果你外挂了硬盘实际路径可能是/mnt/xxx之类这个路径要原样写进 compose写错了容器起得来但目录是空的。第四确认权限CasaOS 首次初始化会创建一个普通用户uid 通常是 1000容器里跑的服务也建议用这个 uid不然下载下来的文件属主是 root你在 CasaOS 的文件管理里想删都删不掉。# 环境自检三连 docker compose version date lsblk -f id2.2 目录结构怎么规划才不返工目录规划看着琐碎其实是最容易返工的地方。我踩过的坑是一开始把 Alist 的数据目录和下载目录混在一起后来想单独备份配置发现整个目录几十个 G备份脚本直接卡死。正确的做法是配置和数据进行物理分离。我现在的结构是这样/DATA/AppData/alist放 Alist 的数据库和配置体积小随时可以打包备份/DATA/AppData/aria2放 Aria2 的会话文件和配置也不大/DATA/Downloads是真正的下载落地区单独一个大目录。三个目录都属于同一个用户权限统一。sudo mkdir -p /DATA/AppData/alist /DATA/AppData/aria2 /DATA/Downloads sudo chown -R 1000:1000 /DATA/AppData /DATA/Downloads sudo chmod -R 755 /DATA/AppData /DATA/Downloads提示如果你打算让下载任务直接落到某个网盘目录里而不是本地磁盘那/DATA/Downloads这个位置反而没那么重要但本地目录还是建议保留用来做临时缓存和测试出问题的时候能快速判断是网盘那边的问题还是下载器的问题。2.3 自定义应用的存放位置CasaOS 的自定义应用目录在/var/lib/casaos/apps/下面每个应用一个子目录里面放一份docker-compose.yml。你把文件写进去重启一下 CasaOS 的服务或者刷新界面它就能识别出来。这个机制的好处是你写的 compose 完全由自己掌控不会被商店模板覆盖。sudo mkdir -p /var/lib/casaos/apps/alist-aria2 sudo nano /var/lib/casaos/apps/alist-aria2/docker-compose.yml写完保存然后sudo systemctl restart casaos或者直接在界面里刷新就能在应用列表里看到。当然你也可以完全绕开 CasaOS直接在任意目录docker compose up -d效果一样只是少了界面管理。我倾向于放进 CasaOS 目录因为家里人偶尔要用的时候点界面比敲命令友好得多。3. 用 Compose 拉起 Alist 与 Aria23.1 compose 文件逐段拆解下面这份是我目前在用的两个服务都用 host 网络挂载路径统一。每一段后面我会解释为什么这么写。services: alist: image: xhofe/alist:latest container_name: alist restart: unless-stopped network_mode: host volumes: - /DATA/AppData/alist:/opt/alist/data - /DATA/Downloads:/downloads environment: - PUID1000 - PGID1000 - UMASK022 - TZAsia/Shanghai aria2: image: p3terx/aria2-pro:latest container_name: aria2 restart: unless-stopped network_mode: host volumes: - /DATA/AppData/aria2:/config - /DATA/Downloads:/downloads environment: - PUID1000 - PGID1000 - UMASK_SET022 - RPC_SECRET换成一串足够长的随机字符 - RPC_PORT6800 - LISTEN_PORT6888 - DISK_CACHE64M - IPV6_MODEfalse - UPDATE_TRACKERStrue - TZAsia/Shanghai几个关键决策说明一下。restart: unless-stopped保证主机重启或者容器异常退出后自动拉起家庭设备经常断电这个必须加。PUID/PGID决定容器内进程以哪个用户身份写文件设成 1000 就和你 SSH 登录的普通用户对上了。UMASK022意味着新建文件权限是 644、目录是 755同一台机器上的其他服务也能读不会出现下载完了但播放器读不了的情况。DISK_CACHE64M是磁盘缓存适当设置能减少小文件写入时的碎片但别设太大内存紧张的小主机会被拖垮。UPDATE_TRACKERStrue让容器启动时自动更新 BT 追踪器列表这个非常关键很多人的 BT 下载没速度就是因为追踪器列表太旧连不上节点。RPC_SECRET是 Aria2 的调用密钥一定要改成长随机串后面 Alist 和前端都要填它。注意host 模式下不能再写ports:段两个同时存在 compose 会直接报错。第一次写的时候我在这卡了十几分钟报错信息还不算直观。3.2 Aria2 配置文件里几个容易忽略的参数容器第一次启动会在/DATA/AppData/aria2下生成aria2.conf有几个默认值我建议手动调一下。一个是max-concurrent-downloads默认 5 对家庭带宽够用但如果你经常一次性甩十几个任务进去可以改成 3 到 5别设太高小主机的磁盘并发写会撑不住。另一个是file-allocation默认可能是prealloc也就是下载前先把整个文件大小的空间预分配出来。这个在大文件上体验很差——一个 40G 的种子点下去磁盘立刻少 40G而且预分配过程本身要花时间机械盘上能卡好几分钟看起来像卡死。改成none之后就是边下边写空间按实际进度占用心理感受好很多。还有seed-time控制做种时长如果你不打算长期做种设成0或者一个很小的值下完就停避免长时间占着连接和带宽。bt-tracker那一行通常由容器自动维护不需要手动改但如果你关闭了自动更新就要自己定期去拉一份新的列表替换不然 BT 就是龟速。max-concurrent-downloads5 file-allocationnone continuetrue seed-time0 disk-cache64M rpc-save-upload-metadatatrue3.3 启动、验证与首次登录文件写好后执行docker compose up -d或者用 CasaOS 界面点启动。然后看日志确认两个服务都正常起来了。docker compose ps docker logs --tail 50 alist docker logs --tail 50 aria2Alist 的日志里会打印一行初始管理员密码这个密码只显示一次复制下来。新版 Alist 出于安全考虑改成了随机初始密码不再是早期的固定值所以必须看日志别去网上抄旧教程里的默认密码抄了也登不上。浏览器打开http://宿主机内网IP:5244用账号admin和你日志里拿到的密码登录。进去第一件事就是改密码改成你自己记得住的强密码顺手把用户名也改掉admin 这个默认名太显眼。Aria2 的验证稍微麻烦一点它没有网页界面得用一个支持 RPC 的前端去连。我一般用 AriaNg纯静态页面随便丢到一个能访问的目录里就行。验证方式是填 RPC 地址http://内网IP:6800/jsonrpc和刚才设置的RPC_SECRET连上之后能看到下载列表就说明通了。3.4 挂载网盘的实操流程登录 Alist 之后左侧菜单进存储点添加选对应的驱动类型。这里每个驱动的字段都不一样但逻辑是统一的给一个挂载路径也就是它在你 Alist 目录树里显示的位置然后填授权信息。以需要授权的那类网盘为例流程通常是这样的先去对方的开放平台创建一个应用拿到客户端 ID 和密钥把回调地址填成 Alist 提供的那一串然后浏览器打开授权链接登录后拿到一串授权码或者刷新令牌粘回 Alist。整个过程不复杂但有两个坑。一个是回调地址必须完全一致多一个斜杠都会失败另一个是令牌有有效期过期之后挂载会报错需要重新授权所以别把刷新令牌弄丢最好备份一份。挂载路径建议做成分层结构比如/网盘A、/网盘B、/本地/downloads一眼能看出哪个是哪个。挂载完点进去看看能不能列目录能列说明配置对了但先别急着测试下载下一步的路径映射没对齐的话下载完照样找不到文件。4. Alist 与 Aria2 的联动配置4.1 为什么要在 Alist 里配置 Aria2Alist 本身不带下载能力它调用 Aria2 的方式是发一条 RPC 请求过去告诉对方下载这个链接存到这个路径。所以配置的核心就两件事告诉 Alist 去哪里找 Aria2以及告诉 Aria2 把文件放在哪里。进 Alist 后台的设置找其他那一栏能看到 Aria2 的相关配置项。地址填http://127.0.0.1:6800/jsonrpc——因为两个容器都用 host 网络Alist 和 Aria2 在同一台机器的网络空间里直接用回环地址最省事。如果你用的是 bridge 网络这里就要填 Aria2 的容器名或者内网 IP。密钥填RPC_SECRET的值和 Aria2 那边一模一样。提示填完先点一下测试或者直接去文件列表里试一个离线下载任务。如果提示 401 或者 unauthorized九成是密钥不一致如果提示连接被拒绝那是地址或端口错了如果提示找不到路径那就是下一节要讲的路径映射问题。4.2 路径映射整套方案里最容易翻车的地方这个坑我踩过不止一次。原理其实很简单Alist 认为的路径和 Aria2 认为的路径必须是同一个物理位置在容器内的同一个字符串。举个人话的例子你跟快递员说放 3 号楼 502 的门口和收件人以为的放在小区门口的柜子里只要说法不一致,东西就找不到了。具体到配置上Aria2 容器把/DATA/Downloads挂载到了内部/downloads那就意味着 Aria2 只认得/downloads这个路径你说/DATA/Downloads它完全不认识。而 Alist 那边如果要调用它下载到本地目录也必须用/downloads。所以正确做法是让两个容器挂载同一个宿主机目录到同一个容器内路径# 两个容器里都这么写路径字符串必须完全一致 - /DATA/Downloads:/downloads然后在 Alist 里把本地存储的挂载路径也设成/downloads对应的目录。听起来很绕但只要你保证宿主机目录 → 容器内路径这个映射在两个容器里完全一样问题就消失了。如果你的目标是下载到网盘而不是本地情况会稍微复杂一点。Alist 把网盘挂载成了自己的一个目录但 Aria2 是看不到这个虚拟目录的它只能写本地文件系统。所以直接下载到网盘这件事Alist 的实现方式是先下到本地某个目录完成之后再由 Alist 上传到网盘。这个中转目录必须两个容器都能访问配置的时候要额外注意。场景Aria2 里的路径Alist 里的路径是否需要中转下载到本地盘/downloads/downloads不需要下载后转存网盘/downloads/temp网盘目录 本地 temp需要且两边挂载要一致只做 BT 缓存/downloads不挂载不需要4.3 AriaNg 前端放到 Alist 背后AriaNg 的接入方式有两种。一种是单独跑一个容器端口另开一个比如 6880然后反代出去另一种更省事——把 AriaNg 的静态文件丢进 Alist 的一个本地存储目录里通过 Alist 的路径直接访问。后者的好处是只需要维护一个入口登录 Alist 之后就能看下载进度不用再记一个端口。具体做法是下载 AriaNg 的发布包解压到一个目录比如/DATA/Downloads/ariang然后在 Alist 里把这个目录挂成本地存储路径设为/ariang。之后访问http://内网IP:5244/ariang/就能打开。第一次打开会要求填 RPC 地址填http://内网IP:6800/jsonrpc加密钥保存之后就能看到任务列表。这个方式有个小细节Alist 对静态文件的处理是走它自己的文件服务所以 AriaNg 的index.html必须能被正确识别。如果打开是一片空白多半是路径层级搞错了检查一下 Alist 里挂载的根路径是不是直接指向包含 index.html 的那一层。5. 远程访问的几种方式与安全边界5.1 先把局域网访问跑通任何远程访问方案的基础都是局域网内先跑通。这一步没验证就去做外网配置出问题你根本分不清是本地服务的问题还是网络链路的问题。验证方法很直接在同一路由器下的手机或者笔记本上浏览器打开http://宿主机内网IP:5244能登录、能列目录、能看视频就说明服务本身没问题。如果这一步打不开先排查防火墙。很多发行版默认开了防火墙规则5244 端口没放行外面就连不上。用ss -lntp | grep 5244确认服务确实在监听再用curl -I http://127.0.0.1:5244在机器本机测一下。本机能通、局域网不通那就是防火墙或者网络隔离的问题跟 Docker 无关。还有个小提醒给宿主机配一个固定的内网 IP或者在路由器上做 DHCP 静态绑定。不然路由器重启后 IP 变了你存的收藏夹全失效家里人也会抱怨昨天还能打开今天就不行了。5.2 出门在外怎么连域名、反代与 HTTPS如果在家里以外的地方也要访问通常有两类做法。一类是家里宽带有固定的公网地址那就把域名解析过去前面架一层反向代理配上证书走 HTTPS。另一类是地址不固定借助动态解析把变化的地址映射到域名上效果类似。这里我不展开具体服务商和配置细节各家方案差异太大只说通用的思路和安全要求。反向代理建议单独跑一个容器比如常见的 Nginx 管理面板或者 Caddy它们能自动申请和续期证书省掉手动折腾证书的时间。代理配置里最关键的是把 WebSocket 透传打开Alist 的部分功能依赖长连接如果反代没配好会出现页面能打开但操作没反应的情况。另外要把上传体积限制调大否则大文件上传会被拦在网关这一层。注意把管理界面直接暴露在公网上是有风险的暴力破解、爬虫扫描都是常态。如果只是自己用我更推荐先在局域网内用需要外部访问时再单独开一条通道而不是常年挂着公网入口。真要开前面说的几条加固措施一条都不能省。5.3 访问安全加固清单这部分比功能配置更重要。我整理了一份自己每次部署都会过一遍的清单按重要性排序。加固项具体做法不做的后果改默认账号登录后立刻改用户名和密码默认名被字典攻击首选强密码长度 16 位以上混合字符弱密码几小时被爆破关闭匿名访问存储设置里勾选需要登录任何人都能翻你的网盘开启两步验证Alist 支持基于时间的一次性口令密码泄露后仍有一道门限制管理入口反代层面只允许特定来源访问后台暴露给全网扫描器定期看日志留意异常登录和大量 404被扫了都不知道两步验证这个功能很多人忽略但在公网环境下它几乎是必须的。开启方式是在个人设置里绑定一个验证器应用扫码之后每次登录要额外输六位数字。麻烦是麻烦了一点但换来的是密码泄露也不会立刻失守。还有一点别用同一个密码。Alist 的密码、Aria2 的 RPC 密钥、反向代理的后台密码各用各的尤其是 RPC 密钥它本质上是谁拿到谁就能让你的机器下载任意文件的凭证泄露了会被当成下载跳板后果比想象中严重。6. 常见问题与排查实录6.1 故障速查表下面这些是我在实际部署和帮别人看配置时反复遇到的按现象归类方便对症下药。现象最可能的原因排查与解决容器起来了但网页打不开端口被占用或防火墙拦截ss -lntp查监听放行端口登录提示密码错误用了旧教程的默认密码docker logs alist找初始密码Alist 连不上 Aria2密钥不一致或地址写错核对 RPC_SECRET 与端口BT 下载一直是 0追踪器列表过旧开启自动更新或手动替换 tracker下载完成但 Alist 找不到两个容器路径映射不一致统一容器内路径字符串网盘挂载报 401/403授权令牌过期重新走一遍授权流程视频能列不能播反代没透传 Range 请求反代配置放行 Range 头下载的文件删不掉属主是 root检查 PUID/PGID 设置中文文件名乱码容器 locale 缺失设置 LANG 环境变量时间显示差 8 小时时区没设加 TZAsia/Shanghai6.2 几个我踩过的坑和独家处理技巧第一个坑是文件权限。早期我图省事没设 PUID容器以 root 跑下载下来的文件属主是 root用普通用户 SSH 登录进去rm都删不掉还得sudo。后来统一设成 1000这个问题再没出现过。如果你已经踩了补救办法是用chown -R 1000:1000批量改一次但注意别对着系统目录乱跑这条命令。第二个坑是 BT 端口。Aria2 的监听端口如果没在路由器上做端口映射虽然还能下载但只能连主动连出去的节点速度和连接数会明显偏低。这个不是必须做但做了体验差别很大。做映射的时候 TCP 和 UDP 都要开只开 TCP 会少掉一部分节点。第三个坑是反向代理下的上传。Alist 往网盘传大文件时如果前面的代理没调大client_max_body_size之类的限制传到一半会返回 413看起来像是网盘那边拒绝其实是网关拦了。这个错误很难从日志直接看出来需要去反代容器的日志里翻。第四个坑是 Alist 的数据库。它的配置都存在一个本地数据库文件里这个文件如果损坏所有挂载配置全丢。所以我在部署完、配置调通之后会立刻把/DATA/AppData/alist整个目录打包备份一份放到另一块盘上。后面每次加重要存储之前也备份一次成本很低但能救命。提示升级镜像之前一定先备份配置目录。Alist 迭代很快偶尔会有数据结构变化的版本直接pull最新版然后重启有小概率起不来。备份了最多回滚一次没备份就得从头配一遍所有挂载。6.3 性能调优的一点经验小主机资源有限几个参数值得调。Aria2 的并发数不要贪多5 个同时下载对大多数家庭带宽已经吃满了设成 16 反而会让每个任务都变慢还容易把磁盘 IO 打满导致整个系统卡顿。磁盘缓存 64M 是个比较平衡的值内存小于 2G 的机器建议降到 32M。Alist 这边主要关注的是网盘接口的请求频率。如果你挂了很多存储又在文件列表页面不停刷新会触发对方的限流表现为目录加载转圈或者报错。解决办法是在存储设置里适当调大缓存时间减少不必要的请求。另外不要在同一次操作里同时展开好几个大目录逐个来会稳很多。最后说一个我自己的使用习惯把常用的几个目录做成 Alist 的别名或者直接收藏放在首页。这样家里人打开就能用不需要理解目录结构也不需要记路径。技术方案再漂亮如果只有你自己会用那它的价值就打了一半折扣。
