Unraid OS 踩坑记录

五一的时候把家中自组的 NAS 从 Windows 10 系统换到了 Unraid OS，在此记录一下配置与注意事项，以便之后重装有得参考。

Unraid OS 注意事项

原先在 Windows 下使用的 USB 有线网卡在 Unraid OS 下有点儿毛病，时间长了会使机器失联，而板载网卡在 Windows 下都有毛病，所以我装了闲置的 TP-Link 牌的 PCI-E 网卡，芯片是 RTL8111/8168/8411 三个型号之一，目前用着还正常；Unraid OS 支持的网卡参考“Hardware Compatibility” ，据说英特尔的兼容性很好。

关机或重启前手动停止阵列，停止阵列之前先手动停止所有容器更好，此外，大折腾前先备份一遍 CA 和虚拟机，这都是教训！Unraid OS 的关机和重启似乎不是那么可靠，有时候是强制的，导致缓存池文件系统报错，无法修复，只能恢复备份，妈了个逼的好几次了！（也许是我使用 Dynamix System Buttons 导致的？总之还是先手动停止阵列保险一些。）

另外，在 go 文件内写入 Docker 镜像加速地址：

# 国内 Docker 镜像加速
mkdir -p /etc/docker
tee /etc/docker/daemon.json <<-'EOF'
{
    "registry-mirrors": ["https://dockerhub.icu"]
}
EOF

有时，比如未停止阵列就重启后，会遇到类似 BTRFS warning (device sde1): csum failed root 5 ino 42260 off 57344 csum 0xdbb001ce expected csum 0x20d7987a mirror 1 的错误。需要用 sudo btrfs inspect-internal inode-resolve 42260 /mnt/cache/ （/mnt/cache 是 sde1 的挂载点。）找出 inode 为 42260 的文件并删除。当主机意外断电，我就很容易在 Uptime Kuma 的数据库文件 kuma.db 上遇到这样的错误。然而，其实在停止阵列并手动重启时我也遇到过这样的错误……我使用命令 btrfs dev stats -c /mnt/cache 来监测 BTRFS 错误，在删除了对应文件，srub 操作不报错后使用 btrfs dev stats -z /mnt/cache 清除错误技术。

我还曾遇到一种错误，不能通过删除某一个文件解决，只能重新建立文件系统。等我下次再遇到了，把错误写在这里。

设置

在 设置 > Docker 页面删除镜像前，先备份 appdata！

路由器映射总端口、WireGuard 端口 ~~，IPv6 的 DNS 设为无效地址 2000::1、2000::2，让路由器为 IPv6 使用 IPv4 DNS~~（不再使用 AdGuardHome）。
默认休眠延迟 1 小时。
虚拟机关机超时 300 秒，磁盘关机超时 420 秒。
在 可调式 (md_write_method) 开启重建写入（Turbo Write），见“Turbo write” ，缺点是写入时阵列内全部磁盘都将唤醒。
启用 SMB 多通道。
阿里云 NTP 服务器。
启用 IPv6。
~~为 Docker 启用 主机访问自定义网络：~~
- 不再启用 主机访问自定义网络，因为启用后使用 WireGuard，需要在 WireGuard 中关闭 本地服务器使用网络地址转换(NAT)，同时在路由器建立静态路由表，见此贴。
~~关闭磁盘共享，仅使用用户共享（磁盘共享与用户共享互拷文件，且位于同一磁盘时会出问题，关闭磁盘共享能减少人为犯错可能）：~~
- 总开关开着了，有时候需要使用磁盘共享，就单独给某块磁盘开启共享。
6.12 新增的独占模式保持关闭——虽然独占模式绕过了基于 FUSE 的 SHFS，能提高共享目录读写性能，但 AList 和荒野无灯的 File Browser 还不能识别符号链接形式的目录。
启用本地系统日志服务器，并且远程系统日志服务器地址填本机地址（192.168 的）。
WireGuard 设置远程隧道访问。
Docker 虚拟磁盘大小设为 30 GB。
各种更新通知设为每周检查一次，但在下方关闭插件与 Docker 更新通知。
为通知配置 ServerChan 代理，为 Warnings 和 Alerts 勾选通知代理。
自动奇偶校验每月 7 日 3 点。
Mover 设为每日 7 点。
SSD Trim 每周四 2 点。
……

阵列与池

阵列使用 XFS，自身不支持静默数据损坏检查，数据由校验盘保护，基于 FUSE 的 SHFS 以目录为单位将文件拆分到阵列内的多块硬盘上，若无校验盘保护，一块硬盘损坏，其他硬盘上的文件仍可读取。

池使用 Btrfs，支持静默数据损坏检查，数据由 RAID 保护，文件在池内的分布由 RAID 级别决定，若无 RAID 保护，一块硬盘损坏，其他硬盘上的文件无法读取（RAID 0）或修复后仅可读取部分（single，见“BTRFS single data FS still striped?” ）。

Unraid OS 6.12 新增 ZFS 支持，折腾了一番还是换回了 Btrfs。ZFS 磁盘阵列扩展无法加盘，且切换 Profile 需要整体重建。Btrfs 的 RAID5/6 还不稳定，不建议使用，但至少容易扩展。

有时候因为折腾，docker.img 被存放在阵列中，因持续占用无法触发 Mover 移动回 Cache，无法使阵列休眠。所以我干脆将各共享的副存储全部禁用了，见下文“共享”部分。

1 TB 硬盘放入阵列。
4 TB 硬盘作为校验盘。
SSD 作为 Cache。
18 TB 硬盘作为 Pool，single，Balance Schedule ~~设为每月 25 日 4 点~~关闭。
……

共享

appdata，application data，存在 Cache（系统默认是辅阵列 -> 主 Cache），私有共享，最小可用空间 200 MB。
dnml，下载与媒体库，存在 Pool，私有共享，最小可用空间 60 GB。
domains，saved VM instances，存在 Cache（系统默认是辅阵列 -> 主 Cache），私有共享，最小可用空间 80 GB。
gallery，相册，存在阵列，私有共享，最小可用空间 50 MB。
isos，ISO images，存在阵列（系统默认是主 Cache -> 辅阵列），私有共享，最小可用空间 10 GB。
large_data，不重要的大型数据，存在 Pool，私有共享，最小可用空间 10 GB。
large_temp，不重要的大型临时数据，存在 Cache，私有共享，最小可用空间 10 GB。
local_backups，CA 与 VM 备份，存在阵列，私有共享，最小可用空间 80 GB。
syslog，系统日志，存在 Cache，私有共享，最小可用空间 30 MB。
system，system data，存在 Cache（系统默认是辅阵列 -> 主 Cache），私有共享，最小可用空间 30 GB。
user_guest，宾客文件，存在阵列，公开共享，最小可用空间 10 GB。
user_hollis，Hollis 文件，存在阵列，私有共享，最小可用空间 30 GB。
……

插件

Community Applications，必装。
已卸载：Unraid Connect，用于远程管理机器，对我来说没啥用。
Fix Common Problems，问题检测。
Proxy Editor，快捷编辑代理，让容器镜像更新检查和 CA 安装走代理，需要手动安装，这是支持链接。
已卸载：Unassigned Devices 和 Unassigned Devices Plus，挂载未分配给阵列和池的磁盘，我为此插件添加了中文翻译。
CA Auto Update Applications，自动更新 CA 和容器镜像，我设置的是每周一 2 点更新 CA，5 点更新容器镜像，排除了 AList、mihomo、DDNS、filebrowser、Transmission、nginxWebUI、qBittorrent、MoviePilot、code-server、Duplicati、Krusader，均关闭更新通知。
Backup/Restore Appdata（安装名称：Appdata Backup），定时备份 CA 配置，我设置的是每周二 2 点，备份 Flash，不备份 VM 元数据，VM 由另一个插件备份：
- 为 Stash 启用外部卷备份，设置排除列表，只备份内部卷和存储媒体元数据的目录。
VM Backup，定时备份虚拟机，每周五 10 点，启用 Zstandard 压缩（恢复时可用 zstd -d 解压），仅开启错误通知：
- 目前这个插件在系统重启后会自动下载一些文件，如果下载不成功，就会变成卸载状态，临时的解决方案见此贴，他楼上那个 HeyHollis 就是我，哈哈。
User Scripts，运行自定义脚本。
Dynamix File Integrity，定期检查静默数据损坏，每周三 2 点，关闭通知，我为此插件添加了中文翻译。
Dynamix File Manager，简易文件管理器。
Dynamix System Autofan，自动控制风扇转速：
- 需要注意的是，系统缺少“ITE IT8613E Super IO Sensors”驱动程序，需要在 go 文件中添加 modprobe it87 force_id=0x8620 才能正常使用此插件，见“No fan control?” 。
- 此插件只管理系统风扇，我使用利民的风扇集线器来扩展风扇接口，CPU 风扇仍然接在 CPU 风扇接口上，系统风扇接在集线器上。
- 预先在 BIOS 中将系统风扇调到 无声 挡（正常 挡太吵了），CPU 风扇使用 正常 挡即可。
- 我为此插件添加了中文翻译。
Dynamix System Temperature，显示系统温度：
- 在解决了 Dynamix System Autofan 的问题后，可选 it8620 作为阵列温度显示。
- 还需添加 modprobe coretemp 和 /usr/bin/sensors -s。
GPU Statistics，在仪表板显示 GPU 信息。
Intel GPU TOP，上面那个插件依赖这个插件。
Intel GVT-g，允许向多个虚拟机和容器直通英特尔核显，适用于 5 到 10 代，如果使用 RDP 可能耗尽显存。
Disable Mitigation Settings，关闭安全缓解措施。
File Activity，监视文件读写，查找硬盘无法停转的原因时有帮助。
Open Files，同上。
Dynamix Active Streams，同上。
……

容器

需要 UPnP、DLNA 的容器必须将网络设为 host。

Custom: br0 的容器需启用 主机访问自定义网络 才可被其他网络类型的容器访问。

xhofe/alist：
- 挂载阿里云盘的根目录时，根目录ID 填 root。
- 垃圾：/data/log。
0netx/bw-export:latest，不支持设置 UMASK。
selenium/standalone-chrome，额外参数 --shm-size 2g，不支持设置 UID 等。
linuxserver/changedetection.io：
- 额外增加环境变量 LC_ALL：en_US.UTF-8，见 "Exception: charmap codec can t decode byte 0x81 in position 440: character maps to"。
allanpk716/chinesesubfinder：
- 将 /mnt/user/dnml/ 映射为 /media/dnml，否则 CSF 会提示在容器内可能因为权限原因无法读取 /media 之外的目录。这项配置也会影响 MP 的 CSF 字幕下载插件的配置，具体见下文。
- 垃圾：/config/Logs。
~~dreamacro/clash-premium，网络设为 host，不支持设置 UID 等：~~
- Clash 核心删库后改为 metacubex/mihomo，网络设为 host，不支持设置 UID 等。
- proxy-providers 由自建 Proxy Provider Converter 生成。
- rule-providers 采用 clash-rules （其中 Google 服务调整为使用代理），由自建 gh-proxy 加速。
linuxserver/code-server，DOCKER_MODS 设为 linuxserver/mods:code-server-nodejs，NODEJS_MOD_VERSION 设为 20，PROXY_DOMAIN 设为 ~~{{port}}.{{host}}~~ cs.nas.<域名>:<端口>，参考“Customizing our Containers” 设置自定义脚本，不应设置 UMASK 否则 npm 等会报权限不安全。运营商似乎封锁了 22 端口，导致我没办法 push 到 GitHub，所以在 .ssh 目录下新建配置文件，写入主机配置，见此文章：
- 垃圾：/config/data/logs、/config/data/User/History（历史记录，可能有用）。
library/couchdb，额外参数 --user 99，不支持设置 PID 和 UMASK。
newfuture/ddns，不支持设置 UID 等。
80x86/filebrowser:2.10.3-amd64：
- /mnt/user/ 映射为 /myfiles/user_shares（注意，/myfiles 部分是必不可少的，否则解压文件时会报“文件不存在”的错误）。
- /mnt/user/large_temp/appdata/filebrowser/thumbnail_cache/ 映射为 /thumbnail_cache。
- /mnt/user/large_temp/appdata/filebrowser/index_db/ 映射为 /index_db，添加核显设备 /dev/dri/renderD128。
- admin 的目录范围设置为 ./user_shares。
- Hollis 的目录范围设置为 ./user_shares/user_hollis。
iyuucn/iyuuplus，不支持设置 UID 等。
linuxserver/jellyfin，支持设定 UID、PID、UMASK 等：
- 除了常规的配置路径映射外，还做以下映射：
  - /mnt/user/large_temp/appdata/Jellyfin/cache/ 映射为 /jellyfin_cache，作为缓存路径。
  - /mnt/user/large_temp/appdata/Jellyfin/transcodes/ 映射为 /jellyfin_transcodes，作为转码路径。
  - /mnt/user/large_data/appdata/Jellyfin/metadata/ 映射为 /jellyfin_metadata，作为元数据路径，元数据存在 large_data 而非 large_temp。
- 在我的硬件下需关闭 AV1 硬解和低电压模式硬件编码器。
- 通过 universal-package-install 和 fonts-noto-cjk-extra 解决媒体库封面文字变成方块的问题。
- 垃圾：/config/log。
ghcr.io/feederbox826/stash-s6:hwaccel，不支持 UMASK，非兼容模式不支持设置 UID 等：
- 端口用默认的 9999，否则插件运行可能有问题。
- 刮削的片名、演员名、标签等数据建议是 ASCII 字符，否则导出元数据时可能遇到问题。
ich777/krusader。
jxxghp/moviepilot：
- 详细配置在环境变量与配置页面里，这里不赘述。
- CSF 字幕下载插件的“本地路径”指的是 MP 内的路径，“远程路径”指的是 CSF 内的路径；因此在我的案例中，前者填 /dnml，后者填 /media/dnml。
- 垃圾：/config/logs。
cym1102/nginxwebui，网络设为 host，不支持设置 UID 等，开启特权，端口通过 BOOT_OPTIONS 指定：口用默认的 9999，否则插件运行可能有问题。
- 刮削的片名、演员名、标签等数据建议是 ASCII 字符，否则导出元数据时可能遇到问题。
ich777/krusader。
jxxghp/moviepilot：
- 详细配置在环境变量与配置页面里，这里不赘述。
- CSF 字幕下载插件的“本地路径”指的是 MP 内的路径，“远程路径”指的是 CSF 内的路径；因此在我的案例中，前者填 /dnml，后者填 /media/dnml。
- 垃圾：/config/logs。
cym1102/nginxwebui，网络设为 host，不支持设置 UID 等，开启特权，端口通过 BOOT_OPTIONS 指定： 777/krusader。
jxxghp/moviepilot：
- 详细配置在环境变量与配置页面里，这里不赘述。
- CSF 字幕下载插件的“本地路径”指的是 MP 内的路径，“远程路径”指的是 CSF 内的路径；因此在我的案例中，前者填 /dnml，后者填 /media/dnml。
- 垃圾：/config/logs。
cym1102/nginxwebui，网络设为 host，不支持设置 UID 等，开启特权，端口通过 BOOT_OPTIONS 指定：
- 映射 /var/logs/nginx 为 /mnt/user/large_temp/appdata/nginxWebUI/，否则它可能会占大量的容器空间。
- 具体配置见下文。
- 垃圾：/config/log。
linuxserver/qbittorrent，网络设为 host：
- 垃圾：/config/qBittorrent/logs。
linuxserver/transmission，网络设为 host。
louislam/uptime-kuma，不支持设置 UID 等：
- 设置里的 站点主 URL 最后不要加斜杠，它拼接的时候自动加。
- Unraid webGui 的 Url 应在最后加上 /login。
- Transmission 可用 HTTP 基础身份验证，有效状态码 200-299。
- Clash 不能用 HTTP 基础身份验证，有效状态码在 200-299 的基础上还需添加 401。
~~linuxserver/fail2ban，网络设为 host，主机日志路径映射只读，额外参数 --cap-add=NET_ADMIN --cap-add=NET_RAW 允许修改防火墙：~~
- ~~自定义配置文件应该以 .local 结尾，见“Configuration README” ;~~
- ~~我装这个是因为有王八犊子 SSH 爆破，刷了好多日志，估计是映射的端口被扫出来了吧，现在我把映射关了；~~
- ~~Unraid webGui 自带多次尝试失败暂时封禁的功能，所以不用在 fail2ban 里配置：~~
  - ~~我使用 nginx 反向代理 Unraid webGui，然而 Unraid webGui 似乎不会读取 X-Real-IP 标头，如果某一 IP 远程登录多次失败，会导致所有远程 IP 暂时无法登录。~~
- ~~设置增量封禁，忽略局域网地址。~~
- 不再使用，因为关闭了端口映射。
linuxserver/duplicati，UID、PID 设为 0，不然无法备份与恢复 /boot：
- 分块大小设为 2 GB。
- 在 large_temp 上映射临时路径 /temp_dir，然后去高级选项保存，否则备份大文件时可能占满容器空间。
- ~~Flash（/boot）备份，每周二 5 点~~ 现在随 CA 一同由 CA Auto Update Applications 备份。
- CA 备份上云，每周二 5 点，此策略仅为本地与云端备份同步，云端保留一份备份即可。
- VM 备份上云，每周五 13 点，此策略仅为本地与云端备份同步，云端保留一份备份即可。
- user_hollis 备份，每周二 5 点 30。
- user_guest 备份，每周二 6 点。
- gallery 备份，每周三 5 点。
easychen/cookiecloud，不支持也不用设置 UID 等。
~~adguard/adguardhome，因 53 端口冲突，需网络设为 custom: br0，固定 IP 地址 192.168.31.2，不支持设置 UID 等：~~
- ~~IPv6 地址是不固定的，没法将 IPv6 的 DNS 设为 AdGuard Home 的地址，所以按照前文所述，将 IPv6 的 DNS 设为无效地址，让路由器为 IPv6 使用 IPv4 DNS。~~
- 我觉得如果我不需要通过 WireGuard 访问 AdGuard Home，就不需要关闭 本地服务器使用网络地址转换(NAT)，静态路由表也不是必须的，但实际上我只要开了 主机访问自定义网络，WireGuard 就报废，所以等我解决了 WireGuard 要求的静态路由表的设置再使用 AdGuard Home。
whyour/qinglong，不支持设置 UID 等。
……

虚拟机

都删了，以下是旧的配置。

Windows 10：
- 机器：Q35-7.1。
- BIOS：SeaBIOS，在我的情况中只有这个好使。
- USB 控制器：3.0 (nec XHCI)。
- 虚拟磁盘总线：VirtIO。
- Unraid 共享模式：VirtIOFS，Manual，/mnt/user/，user_shares。
- 显卡：虚拟，通过 Intel GVT-g 分配核显，但在这里选虚拟。
  - 需要注意的是，若开启 Intel GVT-g，使用 RDP 可能耗尽显存使虚拟机和 Unraid webGui 失去响应，但我使用 ToDesk 遇到了同样的情况。
- 虚拟控制台视频驱动：QXL (best)。
- 网络资源：br0。
- 网络模式：virtio-net。
- XML 视图下在 </devices> 前插入 <sound model='ich6'/> 以启用声卡，每次编辑虚拟机后都需要重新插入，在 ToDesk 中记得开启被控电脑声音。
- 安装操作系统时需安装 VirtIO 驱动程序，暂时只装 Balloon、NetKVM、vioserial、viostor，guest 工具也不装，装多了可能出问题，比如鼠标指针丢失。
- 关闭一些功能，见 VM Support 。
- 挂载 Unraid 共享，这样大部分软件可以直接写入 Unraid 共享，并且管理文件也更加方便，但使用 Link Shell Extension 制作硬链接还需通过 SMB：
  - 运行 VirtIO 驱动镜像里的 virtio-win-gt-x64.msi，这次可以全部安装，然后将 VirtIO-FS Service 服务设为自动启动，安装 WinFsp 。
Fedora，配置基本同上，Unraid 共享模式改为 9p；BIOS 用 SeaBIOS 就可以了，这样的虚拟机恢复备份比较容易，不需要手动恢复选 OVMF 后多出来的文件。
- 向 /etc/fstab 写入 user_shares /user_shares 9p trans=virtio,version=9p2000.L,_netdev,rw 0 0 自动挂载 Unraid 共享。

反向代理（通过 nginxWebUI 设置）

代理目标末尾通常不加 /，如 http://192.168.xx.xx:pppp，加 / 会导致 Jellyfin 的 WebSocket 出现问题。

模板参数

重定向到 Uptime Kuma 状态页：return：302 https://status.<域名>:<端口>/。
设置超时：
- proxy_read_timeout：24h。
- proxy_send_timeout：24h。
- proxy_connect_timeout：24h。
关闭缓冲区：proxy_buffering：off。
设置最大请求体大小：client_max_body_size：30g。
返回 404：return：404。

设置

证书：
- *.cs.nas.<域名>，用于 code-server 端口代理。
- nas.<域名>。
- *.nas.<域名>。
监听 IPv6，开启 HTTP/2（新版写法），TLS 1.2、1.3，设置 Host 参数为 $host，额外参数一律在 location 处设置。
cdb.nas.<域名>，CouchDB，无特殊设置。
cdio.nas.<域名>，ChangeDetection，无特殊设置。
nginx.nas.<域名>，nginxWebUI，无特殊设置。
dupl.nas.<域名>，Duplicati，无特殊设置。
cc.nas.<域名>，CookieCloud，无特殊设置。
ma.nas.<域名>，MYZXKSAssistant，无特殊设置，已禁用。
iyuu.nas.<域名>，IYUU，启用 WebSocket。
*.cs.nas.<域名>，code-server 端口代理，启用 WebSocket。
clash.nas.<域名>，Clash（mihomo），启用 WebSocket。
status.nas.<域名>，Uptime Kuma，启用 WebSocket。
csf.nas.<域名>，ChineseSubFinder，启用 WebSocket。
ql.nas.<域名>，青龙面板，启用 WebSocket，已禁用。
fb.nas.<域名>，filebrowser，启用 WebSocket，Host 参数：$host:$server_port，设置最大请求体大小，设置超时。
cs.nas.<域名>，code-server，启用 WebSocket，proxy_set_header：Accept-Encoding gzip。
tr.nas.<域名>，Transmission，设置最大请求体大小。
qb.nas.<域名>，qBittorrent，设置最大请求体大小。
alist.nas.<域名>，AList，设置最大请求体大小，设置超时，Host 参数：$http_host 。
jlf.nas.<域名>，Jellyfin：
- / 设置最大请求体大小，关闭缓冲区。
- /socket 启用 WebSocket。
stash.nas.<域名>，Stash，设置最大请求体大小，关闭缓冲区，Host 参数：$host:$server_port，启用 WebSocket。
nas.<域名>，自定义 location，重定向到 Uptime Kuma 状态页。
*.nas.<域名>，未匹配的子域名，自定义 location，重定向到 Uptime Kuma 状态页。
kr.nas.<域名>，Krusader：
- = / 无特殊设置。
- / 启用 WebSocket。
- /websockify 启用 WebSocket，设置超时，关闭缓冲区。
unraid.nas.<域名>，Unraid webGui，启用 WebSocket，Host 参数：$host:$server_port，设置最大请求体大小，设置超时。
mp.nas.<域名>，MediaPilot，Host 参数：$host:$server_port。
……

未完待续……？