当前位置：首页 > news >正文

构建家庭NAS之三：在TrueNAS SCALE上安装qBittorrent

news 2026/2/7 11:32:42

本系列文章索引：
构建家庭NAS之一：用途和软硬件选型
构建家庭NAS之二：TrueNAS Scale规划、安装与配置
构建家庭NAS之三：在TrueNAS SCALE上安装qBittorrent

大部分家庭NAS用户应该都会装一个下载工具。本篇以qBittorrent为例，说一下如何在TrueNAS SCALE上使用docker来安装应用。

1. 关于Docker

要顺利地使用docker，首先还是需要理解一些基本概念。

1.1 docker

什么是docker？简单地说，docker镜像（docker image）是自带运行环境的应用程序（本文会混合使用“docker镜像”和“docker应用”这两个词，表示的是同一个意思）。所以部署docker应用非常简单，把docker镜像下载下来直接运行就可以了，不需要传统应用那样复杂的安装过程。拿windows举例，安装一个应用通常需要复制文件到系统目录，安装和更新一些共享库（时不时造成软件冲突），还要修改注册表。卸载也同样麻烦。时间长了，系统里会留下很多垃圾文件和注册项，而这些问题在docker应用上都不存在。

可以把docker镜像理解成一个自带虚拟机的应用，或免安装版的应用。它运行需要的各种环境（依赖的库文件、需要创建的文件目录和配置文件、需要修改的系统文件和参数等）已经在docker镜像里设置好了，所以只需要把这个镜像像虚拟机一样运行起来就OK了。

实际上docker应用也是一个虚拟机，只不过相对于传统虚拟机，它有下面这几个特点。

它很轻量，更节省资源。
它可以和宿主机（运行TrueNAS的机器）共享文件夹，所以数据交换比起传统虚拟机方便很多。比如我们可以在docker里运行下载工具，下载的文件直接存放在nas的文件系统上。这是通过把宿主机上的文件夹映射到虚拟机里的一个文件夹来实现的。对于docker应用来说，它访问的是本虚拟机内部的一个文件夹和文件，实际上访问的是宿主机上的文件夹和文件。
由于有这样的文件共享机制，docker应用的配置信息和数据通常都放在docker镜像外面（宿主机或者云上），所以应用升级非常简便，只需要下载一个升级版本的docker镜像再跑起来就行了。

TrueNAS SCALE支持docker以后，极大提升了系统的可定制性和稳定性。用户可以安装自己喜欢的docker镜像来扩展功能；同时TrueNAS系统本身不会被修改，从而保障系统稳定。

1.2 k8s/k3s

说完docker，再简单地说一下K8S/K3S。K8S全名叫做Kubernetes，因为单词比较长，所以习惯取头尾各一个字母加上中间的字母数量简写为K8S。类似命名还有i18n，是国际化（Internationalization）的缩写。

那么这个K8S究竟是个什么东西呢？K8S就是运行和管理docker应用的操作系统。Windows操作系统是管理单机的资源和应用，而k8s是用来管理云上的资源和应用（把docker镜像看成是云上的应用）。

至于k3s，是k8s的简化版。K8S用来在云上大规模部署和管理docker应用，在我们的nas系统上不需要这么强大和复杂的k8s，所以TrueNAS SCALE采用了一个简化版的k3s来管理和运行docker应用。

在实际使用TrueNAS的过程中，我们基本不会直接操作k8s/k3s，TrueNAS的管理界面把这些功能隐藏在后台了，所以只需要了解概念就好。

介绍完基本概念，我们就可以开始干活了，看看如何安装和运行qBittorrent。

2. 设置下载目录和权限

为了安装qBittorrent应用，首先需要在NAS的数据集里创建一个下载目录，用来存放下载文件，并设置好相应的权限。

2.1 用户和用户组设置

后续的操作都假设已经创建了下列用户和用户组：

用户：lqy；用户ID：3000
用户组：luoma；用户组ID：3000

2.2 创建存放下载文件的数据集

进入TrueNAS的WEB UI，点击左边菜单栏里的“数据集”。
在右边的数据集列表里选择（点击）一个顶层数据集（我选择“test”数据集），在数据集“详细信息”页面点击右上角的“添加数据集”
输入数据集的名称（我的数据集名称是downloads），点击“保存”。这样我的数据集就创建好了。数据集的访问路径为：/mnt/test/downloads。

2.3 设置数据集的权限。

再次进入downloads数据集的“详细信息”页面。
下拉到“权限”部分，点击右上角的“编辑”。
在“编辑ACL”部分，把所有者和所有者组改成上面预先创建好的用户和用户组，并勾选“申请所有者”和“应用于组”。
拉到最下面，勾选“递归应用权限”和“将权限应用于子数据集”，并点击“保存访问控制列表”。

这样，就把downloads数据集以及其下的子目录的用户和组修改好了。

3. 安装和使用qBittorrent

3.1 安装配置

TrueNAS SCALE的应用库里有好几个下载应用，我这里使用qBitttorent。
安装部署的步骤如下：

登录到Web界面，点击左边菜单栏里的“应用”，再点击右上角的“探索应用程序”
搜索qBittorrent，点开应用，在应用的详情页面点击“安装”。
下拉到"User and Group Configuration"，把“群组ID”设置为上面提到的"luoma"组的ID：
下拉到“Network Configuration”，把“Host Network"勾上。
在“Storage Configuration”区域：

“类型”选择“Host Path(Paht that already exists on the system)”。
勾选“启用ACL”。
"Host Path"选择在“创建存放下载文件的数据集”部分创建的“/mnt/test/downloads”。

在“ACL条目”部分：

添加一条ACL，“ID Type”选择“Entry for a GROUP”，ID使用前面创建的luoma用户组的ID（3000），“访问”选择“FULL_CONTROL Access”。
把下面的“Force Flag”勾选上。（如果/mnt/test/downloads文件夹里已经有文件，不选这个会报错）

点击最下方的“安装”，等待安装完成。

3.2 管理qBittorent Web界面密码

3.2.1 查找初始密码

qBittorrent的初始用户名为admin，但初始密码是随机生成的。可以按如下方式找到初始密码：

在TrueNAS管理界面选择“应用”菜单，并在右边应用列表里点击 qBitTorrent 应用程序。
在工作负载部分，单击该部分右下角的查看日志图标。
在“选择 Pod”部分，接受默认设置并单击“选择”。
查找日志中包含password的行并复制密码。
返回应用程序界面，然后转到“应用程序信息”部分，然后单击“Web Portal”图标打开qBittorrent管理应用。
使用用户名admin和步骤4中的密码登录。

3.2.2 更改qBitTorrent登录密码

登录 qBitTorrent 管理应用。
转到工具→选项。
单击“Web UI”选项卡。
在“验证”部分，设置新的用户名和密码并记下来。
向下滚动并单击“保存”。

3.2.3 关闭身份验证

关闭身份验证之后，登录qBittorrent就不需要输入用户名和密码了。

首先需要知道你自己的IP地址和子网掩码。我自己的ip地址/子网掩码为192.168.1.XXX/255.255.255.0，因此我输入的实际IP地址是192.168.1.0/24。读者可以根据自己的网络地址进行调整。

登录 qBitTorrent 应用程序。
转到工具→选项。
单击“Web UI”选项卡。
转到“验证”部分。
勾选“对IP子网白名单中的客户端跳过身份验证”
在下面的框中输入您的网络地址。（例如192.168.1.0/24）
向下滚动并单击“保存”。

4. 小结

这样qBittorrent就安装好了。可以愉快地找下载种子玩耍了。

安装配置要点如下：

下载目录（/mnt/test/downloads）的所有者ID/用户组ID分别设置为3000/3000（详见“设置下载目录和权限”部分），权限设置为同组用户可读、写和执行。
运行qBittorrent的用户组ID也设置为3000，因此对/mnt/test/downloads目录具有读、写和执行权限。这里的用户ID不重要，保留系统默认设置。
网络要配置成“host network”（见“安装配置部分”第4步）。

如果出现问题，可以再检查一下这几项设置。