CasaOS 小主机 Docker 部署 Alist+Aria2 网盘聚合与离线下载

家里那台常年吃灰的小主机装上 CasaOS 之后，我一直想把它变成能干活的设备：白天在单位想取家里的资料，晚上想把散落在几个网盘里的内容统一到一个入口看，顺手还能挂个后台下载，把别人分享的种子和大文件直接落到网盘目录里。折腾了几轮，最后落地的是一套比较稳的组合——CasaOS 管系统和容器，Docker 跑服务，Alist 把各处存储聚合成一个 Web 入口，Aria2 挂在后面做离线下载，Alist 再反过来调用 Aria2，把任务直接写进指定目录。这套 Alist+Aria2 的玩法在 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 模式则可以省掉一层端口映射的心智负担，反代的配置也更直接。代价是端口不能冲突，规划的时候要提前避开。

端口不是随便挑的，选之前先用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 id

2.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 与 Aria2

3.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: - PUID=1000 - PGID=1000 - UMASK=022 - TZ=Asia/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: - PUID=1000 - PGID=1000 - UMASK_SET=022 - RPC_SECRET=换成一串足够长的随机字符 - RPC_PORT=6800 - LISTEN_PORT=6888 - DISK_CACHE=64M - IPV6_MODE=false - UPDATE_TRACKERS=true - TZ=Asia/Shanghai

几个关键决策说明一下。restart: unless-stopped保证主机重启或者容器异常退出后自动拉起，家庭设备经常断电，这个必须加。PUID/PGID决定容器内进程以哪个用户身份写文件，设成 1000 就和你 SSH 登录的普通用户对上了。UMASK=022意味着新建文件权限是 644、目录是 755，同一台机器上的其他服务也能读，不会出现"下载完了但播放器读不了"的情况。

DISK_CACHE=64M是磁盘缓存，适当设置能减少小文件写入时的碎片，但别设太大，内存紧张的小主机会被拖垮。UPDATE_TRACKERS=true让容器启动时自动更新 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-downloads=5 file-allocation=none continue=true seed-time=0 disk-cache=64M rpc-save-upload-metadata=true

3.3 启动、验证与首次登录

文件写好后执行docker compose up -d，或者用 CasaOS 界面点启动。然后看日志确认两个服务都正常起来了。

docker compose ps docker logs --tail 50 alist docker logs --tail 50 aria2

Alist 的日志里会打印一行初始管理员密码，这个密码只显示一次，复制下来。新版 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 里配置 Aria2

Alist 本身不带下载能力，它调用 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 上传到网盘。这个中转目录必须两个容器都能访问，配置的时候要额外注意。

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 访问安全加固清单

这部分比功能配置更重要。我整理了一份自己每次部署都会过一遍的清单，按重要性排序。

两步验证这个功能很多人忽略，但在公网环境下它几乎是必须的。开启方式是在个人设置里绑定一个验证器应用，扫码之后每次登录要额外输六位数字。麻烦是麻烦了一点，但换来的是密码泄露也不会立刻失守。

还有一点，别用同一个密码。Alist 的密码、Aria2 的 RPC 密钥、反向代理的后台密码，各用各的，尤其是 RPC 密钥，它本质上是"谁拿到谁就能让你的机器下载任意文件"的凭证，泄露了会被当成下载跳板，后果比想象中严重。

6. 常见问题与排查实录

6.1 故障速查表

下面这些是我在实际部署和帮别人看配置时反复遇到的，按现象归类，方便对症下药。

6.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 的"别名"或者直接收藏，放在首页。这样家里人打开就能用，不需要理解目录结构，也不需要记路径。技术方案再漂亮，如果只有你自己会用，那它的价值就打了一半折扣。