TrueNAS部署自定义Docker镜像

TrueNAS 从 24.10 版本开始将以前的部署应用的底层支持组件从 K3S 更换为了 Docker。除了 TrueNAS 本身提供的镜像源外，也能用上Docker 官方镜像仓库（Docker Hub）中海量应用，极大的丰富了 NAS 的玩法。

之前一直没整理过相关的笔记和内容。这篇文章里会避开一些太过技术性的内容，记录一下TrueNAS Web 页面部署的自定义 Docker 镜像的操作和要点。

假设只是简单的听说了一些基础的 Docker 概念，或者忘了相关知识点之类的情况下，想在自己的TrueNAS上快速部署一些第三方应用，直接跟着这篇文章操作即可。当然其他的 NAS 系统（群晖、威联通等）也可以做一些参考，毕竟 Docker 基础的知识点是相通的。

找到Docker镜像

当我们想要部署某个特定应用时，大概率都是通过一些博客、文章、视频等已经了解了某款应用程序或服务（以下统称为应用），

在部署前需要找到应用镜像的完整名称，最简单的方法是直接进入 Docker Hub 去通过关键词去搜索镜像的页面，查看这个应用是否提供了 Docker 的部署方式。

在搜索结果中点开可以打开查看应用的镜像说明页面。注意有时候可能搜出来多个同名镜像，可以借助发布者、说明等方式来判断是否是想要的应用。

这里以测速工具“Open Speed Test”为例，找到并打开应用的镜像详情页。

最顶部的就是此应用镜像的完整镜像名（一般是 xxx 或 xxx/yyy 的样式，复制下来后面会用到）。

另外大部分文章、视频等推荐应用时会直接给出部署说明或者 Github 页面。docker run / docker pull 命令最后的部分就是应用的镜像名，也可以从这里复制。例如：

如果应用给的部署方式不是直接用 Docker 命令，而是用 docker-compose 部署，也可以在 docker-compose.yml 文件 services 层级下的 image 标签找到应用名称。

下图红框是一个具体的例子：

顺带补充一个 Docker 的知识点。镜像本身有一个 Tag （标签）属性，正常情况下发布者在打包应用的时候为了区分不同版本（比如新旧版本）就会带上 Tag 做区分。而且所有的镜像都一定会有个 Tag 为 latest 的版本，表示最新发布的一个镜像。

docker run / docker pull 命令都支持在镜像名后加上 : 指定 Tag。如果省略 : 和Tag，则默认使用 latest 版本的镜像。

例如：

docker run openspeedtest/latest:latest  # Docker启动最新版的 openspeedtest/latest 镜像
docker run openspeedtest/latest:v2.0.6  # Docker启动最新版的 openspeedtest/latest 镜像
docker pull nginx:1.29    # 拉取 1.29 版本（Tag），名称为 nginx 的镜像
docker pull nginx:latest  # 拉取最新的 nginx 的镜像
docker pull nginx         # 同上

多数应用通过 Docker部署时，默认用 latest 即可。不适合随意升级的服务类应用（例如：MySQL、NextCloud）再去手动指定 Tag。

如果想浏览或搜索镜像的 Tag，可以去到镜像详情页的 Tags 选项卡里操作。

准备工作

由于国内访问Docker镜像仓库有时会失败，如果没有修改过的话，最好给 TrueNAS 上的 Docker 更换源或者配置代理。否则镜像可能拉取失败。

修改 Docker 代理，先以管理员用户进入命令行，执行：

cd /etc/systemd/system/docker.service.d/
nano http-proxy.conf

然后修改配置文件内容为（ip 和 port 按实际情况替换）：

[Service]
Environment="HTTP_PROXY=http://ip:port"
Environment="HTTPS_PROXY=http://ip:port"

然后 Ctrl+X、回车保存。

然后执行以下内容重启 Docker 相关服务：

systemctl daemon-reload
systemctl restart docker

通过 Web 部署镜像

进入 TrueNAS 管理后台，点击 应用 → 探索应用程序。

在页面右上方会有两个按钮：“自定义应用程序”（下图中1处）、在折叠菜单中的“通过YAML进行安装”（下图中2处）。选择前者等效于直接通过 docker run 命令部署应用。后者则等效于 docker-compose 方式部署。

后一种方式比较简单，选择后直接复制粘贴写好的 docker-compose.yml 配置文件内容到页面中，再部署即可。由于 docker-compose 比较复杂而且涉及很多技术性内容，这里不展开说了。主要介绍前一种方式。

点击“自定义应用程序”按钮后，会跳到一个新的页面填写一些部署内容。

大部分内容和原版 Docker 是一模一样的。如果不知道是什么，参考应用给的部署说明中的 docker run 转化过来即可，并不复杂。下方把重要的部分按分块单独列出来了。

Application name

“应用名称”：TrueNAS 应用列表中显示的名字。起到标识作用，对运行和其他配置没有任何影响（比如可以把同一个应用部署两份，然后以“应用名称”作为区分）。按照要求取名即可（不能重复）。

Image Configuration - 镜像配置

Repository（源）：填写的就是前面找到的镜像完整名称，例如“openspeedtest/latest”。注意Tag不要写在这里。

标签：镜像标签 Tag，也就是 docker run / docker pull 命令末尾冒号之后的部分（如果有冒号的话）。

Pull Policy：镜像拉取策略。这涉及到一点点 Docker 的知识，简单的说，如果选“Always pull an image…” 相当于每次启动前都更新一次应用。一般用默认项（“Pull the image if it is not already present…”）即可，需要升级应用时再Web节目手动升级。

Container Configuration - 容器配置

时区：设成当地所在的时区。国内就选上海 “Asia/Shanghai”

Restart Policy（容器重启策略）：一般都选“Unless Stopped”，应用进程被外部杀死后 Docker 会自动重启，但应用自身启动失败不会重启；选“Always”则无论启动失败还是进程被杀死都重启。此项等同于 docker run 中的 --restart= 参数指定的内容。

Environment Variables（环境变量）：一般忽略，要对应用加一些特殊配置才需要填。此项等同于 docker run 中的 -e 参数，格式为：-e 变量名称=值。

网络配置

Host Network（启用宿主网络模式）：勾选后应用容器内部直接共享宿主机的网络环境；不勾选更加安全。如果不确定怎么选择，就看应用部署文档里 docker run 中有没有出现 --network host ，有才勾选。

端口：用于配置 container 向外暴露的端口映射（对应docker run 中的 -p 参数）。有多少组映射关系，就点“添加”按钮添加多少组。

此处涉及一点 Docker 原理，简单的说如果未勾选“Host Network”就需要配置，否则没法从宿主机访问容器内的应用。端口的映射关系可以在应用部署文档中找到，或者直接看 docker run 中的 -p 参数，格式如下： -p 宿主端口:容器内端口/协议 。

具体的对照说明如下图所示

Storage Configuration - 存储配置

存储：配置容器内应用文件（数据）存储方式。此项也涉及到一点 Docker 原理。

“Tmpfs”相当于不保存，每次容器停止（重启）后文件都会被清空。不需要存储文件的应用才用得到。

“ixVolume”同 Docker 自行管理的容器卷，不会删除文件，但宿主机无法直接读取。注意选此模式时 TrueNAS 要求手动起一个名字。

“Host Path”是 Docker 物理机路径挂载模式，所有的文件读写操作会直接影响到宿主机（这里特指NAS的数据集）上的真实文件操作。需要与宿主机共享文件时可以选择此项。

例如下图，对于Aria2、Transmission这类下载器下载的文件需要在外部访问，就可以把NAS存放下载文件的目录 /mnt/ssd/dl 挂载到 /downloads 路径下（位于容器内）。

备注：这一部分配置的作用和含义与旧版（K3S）的 TrueNAS 是基本一致。ACL是用于配置文件访问权限的，一般不勾选。

Resources Configuration - 硬件资源配置

限制应用运行使用的物理机CPU/内存资源，看个人需要进行配置即可。

另外，如果类似 Jellyfin、PLEX 这类多媒体应用需要直通核显做硬件转码，需要勾选最后的 Passthrough 选项。

配置完成后，点击页面最下方的“安装”按钮开始部署。最后观察等待系统拉取镜像、启动容器是否成功。

在地址栏输入应用的IP+端口能正常访问，则说明部署成功了。如果访问不了，检查一下容器启动是否报错，以及前几步配置的端口映射是否正确。

关于 docker-compose

最后提一个小小的注意事项。在 TrueNAS 中建议尽量避免用 docker-compose 方式部署。

目前的系统版本不能直接通过 Web 管理界面去升级应用。具体来说，首次部署应用后，再点击升级，系统只会拉取新镜像但不会更新应用容器。在 Web 节目上也会有提示。

另外，由于 TrueNAS 管理 docker-compose.yml 文件的方式和 Docker Desktop/命令行的方式不同，目前暂时也没有找到通过命令行直接升级（更新容器）的方法。