树莓派 / Debian 安装 OpenMediaVault 后的基础配置记录

这篇记录一下在 Debian / 树莓派环境中安装 OpenMediaVault，也就是 OMV 的过程。

这不是一篇从零讲概念的教程，更像是一份实际安装时整理出来的操作笔记。里面包括系统源、网络、SSH、DNS、OMV 安装、Docker Compose，以及几个常用服务的配置：Jellyfin、qBittorrent、Immich 和 Bazarr。

文里的 IP、磁盘 UUID、密码都建议替换成你自己的环境配置，不要直接照抄。

一、系统环境准备

我这次的基础系统是 Debian trixie。安装 OMV 前，先把软件源、系统更新、SSH 和 DNS 这些基础项处理好。

1. 配置 Debian 软件源

先备份原来的源配置：

1
2
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
sudo cp -r /etc/apt/sources.list.d /etc/apt/sources.list.d.bak

编辑传统的 sources.list：

1
sudo nano /etc/apt/sources.list

可以使用清华源：

1
2
3
4
5
6
7
8
9
10
11
deb https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie main contrib non-free non-free-firmware
# deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie main contrib non-free non-free-firmware

deb https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-updates main contrib non-free non-free-firmware
# deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-updates main contrib non-free non-free-firmware

deb https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-backports main contrib non-free non-free-firmware
# deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-backports main contrib non-free non-free-firmware

deb https://security.debian.org/debian-security trixie-security main contrib non-free non-free-firmware
# deb-src https://security.debian.org/debian-security trixie-security main contrib non-free non-free-firmware

如果系统使用的是 deb822 格式，也可以编辑：

1
sudo nano /etc/apt/sources.list.d/debian.sources

内容参考：

1
2
3
4
5
6
7
8
9
10
11
Types: deb
URIs: https://mirrors.tuna.tsinghua.edu.cn/debian
Suites: trixie trixie-updates trixie-backports
Components: main contrib non-free non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

Types: deb
URIs: https://security.debian.org/debian-security
Suites: trixie-security
Components: main contrib non-free non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

如果是树莓派系统，还可以配置 Raspberry Pi 软件源：

1
sudo nano /etc/apt/sources.list.d/raspi.list
1
deb https://mirrors.tuna.tsinghua.edu.cn/raspberrypi/ trixie main

2. 更新系统

配置好源之后，更新系统：

1
2
3
sudo apt update
sudo apt full-upgrade -y
sudo reboot

这一步建议重启一次，确保内核和系统包都处在最新状态。

二、网络与 SSH 基础配置

1. 修改默认网关

如果设备接入了多个网络，或者默认网关不符合预期，可以手动替换默认路由。

示例：

1
2
sudo ip route replace default via 192.168.9.1 dev eth0
sudo ip route del default via 192.168.9.254 dev eth0

这里的网关地址需要按自己的网络环境修改。

2. 解决 SSH locale 警告

如果 SSH 登录时出现 locale 相关警告，可以在 Debian / 树莓派上重新配置 locale：

1
sudo dpkg-reconfigure locales

进入界面后勾选：

1
en_US.UTF-8 UTF-8

默认 locale 选择：

1
en_US.UTF-8

然后执行：

1
2
sudo locale-gen
sudo update-locale LANG=en_US.UTF-8 LC_CTYPE=en_US.UTF-8

退出 SSH 后重新登录：

1
2
exit
ssh your-user@your-nas-ip

如果仍然有提示，可以在本机连接时临时加上：

1
LC_ALL=en_US.UTF-8 ssh your-user@your-nas-ip

3. 修复 SSH 密码一直错误的问题

如果本地登录正常，但 SSH 登录一直提示密码错误，可以检查 SSH 配置：

1
sudo nano /etc/ssh/sshd_config

如果里面有类似这一行：

1
AllowGroups root _ssh

它的意思是：只有 root 和 _ssh 组里的用户允许 SSH 登录。普通用户不在这些组里时，即使密码正确，也会被拒绝。

最简单的修复方式是删除这一行。

在 nano 里把光标移动到这一行，然后：

1
2
3
4
Ctrl + K
Ctrl + O
回车
Ctrl + X

保存后重启 SSH：

1
sudo systemctl restart ssh

然后重新连接：

1
ssh your-user@your-nas-ip

OMV 有时会自动生成 SSH 配置，文件里可能会看到：

1
This file is auto-generated by openmediavault

所以如果后续 OMV 界面里改过 SSH 设置，也要留意这类限制是否又被写回来了。

不太建议为了保留 AllowGroups 而把普通用户加入 root 组。对家用 NAS 来说，直接移除这一行通常更简单。

4. 配置 DNS

如果 DNS 解析异常，可以临时改成公共 DNS：

1
2
3
4
5
6
7
sudo rm -f /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf

sudo systemctl disable systemd-resolved
sudo systemctl stop systemd-resolved
cat /etc/resolv.conf

最终内容类似：

1
2
nameserver 1.1.1.1
nameserver 8.8.8.8

三、安装 OpenMediaVault

基础环境处理完之后，安装 OMV：

1
wget -O - https://get.openmediavault.io | sudo sh -

安装 OMV 插件源：

1
wget -O - https://github.com/OpenMediaVault-Plugin-Developers/packages/raw/master/install | sudo bash

安装完成后，可以进入 OMV Web 管理界面继续配置磁盘、共享文件夹、用户、服务等。

重置 OMV 管理员密码

如果忘记 OMV 管理员密码，可以使用：

1
sudo omv-firstaid

选择：

1
Change administrator password

也可以直接修改 admin 用户密码：

1
sudo passwd admin

四、准备 Docker 目录

OMV 上常用的应用一般会通过 Docker Compose 部署。建议把应用配置和 compose 文件放到数据盘上。

示例目录：

1
2
sudo mkdir -p /srv/dev-disk-by-uuid-xxxx/appdata/docker
sudo mkdir -p /srv/dev-disk-by-uuid-xxxx/composefile

这里的 xxxx 替换成你自己磁盘的 UUID。

五、安装 Jellyfin

先准备媒体目录和配置目录：

1
2
3
sudo mkdir -p /srv/dev-disk-by-uuid-xxxx/media/movies
sudo mkdir -p /srv/dev-disk-by-uuid-xxxx/media/tv
sudo mkdir -p /srv/dev-disk-by-uuid-xxxx/appdata/jellyfin

进入 OMV：

1
Services -> Compose -> Files

新增一个 compose 文件，例如命名为：

1
jellyfin

内容示例：

1
2
3
4
5
6
7
8
9
10
11
services:
  jellyfin:
    image: jellyfin/jellyfin
    container_name: jellyfin
    network_mode: bridge
    ports:
      - "8096:8096"
    volumes:
      - /srv/dev-disk-by-uuid-xxxx/appdata/jellyfin:/config
      - /srv/dev-disk-by-uuid-xxxx/media:/media
    restart: unless-stopped

启动后访问：

1
http://your-nas-ip:8096

六、安装 qBittorrent

qBittorrent 可以用 linuxserver 镜像部署。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
version: "3.8"

services:
  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1000
      - PGID=100
      - TZ=Asia/Shanghai
      - WEBUI_PORT=8080
    volumes:
      - /srv/dev-disk-by-uuid-xxxx/appdata/qbittorrent:/config
      - /srv/dev-disk-by-uuid-xxxx/media:/downloads
    ports:
      - 8080:8080
      - 6881:6881
      - 6881:6881/udp
    restart: unless-stopped

启动后访问：

1
http://your-nas-ip:8080

初次登录后，一定要立刻修改默认密码。

七、安装 Immich

Immich 用来做照片和视频备份。它依赖 server、machine-learning、redis 和 postgres。

compose 示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-v2}
    volumes:
      - /srv/dev-disk-by-uuid-xxxx/immich:/data
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - immich.env
    ports:
      - '2283:2283'
    depends_on:
      - redis
      - database
    restart: always
    healthcheck:
      disable: false

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-v2}
    volumes:
      - model-cache:/cache
    env_file:
      - immich.env
    restart: always
    healthcheck:
      disable: false

  redis:
    container_name: immich_redis
    image: docker.io/valkey/valkey:9
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

  database:
    container_name: immich_postgres
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
      # 如果数据库放在机械硬盘，可以取消下一行注释
      # DB_STORAGE_TYPE: 'HDD'
    volumes:
      - /srv/dev-disk-by-uuid-xxxx/appdata/immich/postgres:/var/lib/postgresql/data
    shm_size: 128mb
    restart: always
    healthcheck:
      disable: false

volumes:
  model-cache:

同目录下新建 immich.env：

1
2
3
4
5
TZ=Asia/Shanghai
IMMICH_VERSION=v2
DB_PASSWORD=请换成强密码
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

启动后访问：

1
http://your-nas-ip:2283

注意：DB_PASSWORD 不要使用简单密码，更不要把真实密码写到公开文章里。

八、安装 Bazarr 自动下载字幕

Bazarr 用来给 Jellyfin / Sonarr / Radarr 管理的媒体自动下载字幕。这里按“只想自动下载中文字幕给 Jellyfin 用”的目标来配置。

1. Docker Compose

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
services:
  bazarr:
    image: lscr.io/linuxserver/bazarr:latest
    container_name: bazarr
    environment:
      - PUID=1000
      - PGID=100
      - TZ=Asia/Shanghai
      # 如果需要代理，可以按自己的网络环境打开
      # - HTTP_PROXY=http://your-proxy-ip:7890
      # - HTTPS_PROXY=http://your-proxy-ip:7890
      # - NO_PROXY=localhost,127.0.0.1,::1,sonarr,radarr,jellyfin,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12
    volumes:
      - /srv/dev-disk-by-uuid-xxxx/appdata/bazarr:/config
      - /srv/dev-disk-by-uuid-xxxx/media/movies:/movies
      - /srv/dev-disk-by-uuid-xxxx/media/tv:/tv
    ports:
      - 6767:6767
    restart: unless-stopped

启动后访问：

1
http://your-nas-ip:6767

2. 启用字幕语言

进入：

1
Settings -> Languages

在 Subtitles Language 里启用：

1
Chinese Simplified

如果希望繁体字幕也能作为备选，可以再启用：

1
Chinese Traditional

如果想同时保留英文字幕，也可以启用：

1
English

建议不要开启 Single Language。开启后字幕文件名可能不带 zh、en 这类语言标识，有些播放器识别起来反而不方便。

3. 新建语言配置文件

继续进入：

1
Settings -> Languages -> Languages Profiles

点击：

1
Add New Profile

推荐配置一：只下载简体中文。

1
2
3
4
5
6
Profile Name: 中文简体
Language: Chinese Simplified
Forced: 关闭
HI / Hearing Impaired: 关闭
Exclude Audio: 关闭
Cutoff: Chinese Simplified 或留空

推荐配置二：简体优先，繁体备用。

1
2
3
4
5
6
7
8
Profile Name: 中文简繁
Languages:
- Chinese Simplified
- Chinese Traditional
Cutoff: Chinese Simplified
Forced: 关闭
HI / Hearing Impaired: 关闭
Exclude Audio: 关闭

Cutoff = Chinese Simplified 的意思是：找到简体中文字幕后就停止继续搜索其它语言。找不到简体时，再尝试繁体。

如果你想同时下载中文和英文字幕，可以把 Chinese Simplified 和 English 都加进 Profile，但 Cutoff 建议留空。因为 Cutoff 不是优先级排序，而是“找到某个语言后停止搜索”。

4. 设置默认语言配置

在同一个页面下面找到：

1
Default Settings

分别设置：

1
2
Series Default Setting
Movies Default Setting

建议都选择刚才创建的：

1
中文简繁

这个设置通常只会自动应用到之后新增的剧集和电影。已有媒体需要手动批量设置。

5. 给已有媒体批量套用语言配置

电视剧：

1
Series -> Mass Edit -> 全选 -> Language Profile: 中文简繁 -> Save

电影：

1
Movies -> Mass Edit -> 全选 -> Language Profile: 中文简繁 -> Save

6. 字幕保存位置

进入：

1
Settings -> Subtitles

推荐：

1
Subtitle Folder = Alongside Media File

也就是字幕文件和视频文件放在同一个目录。

例如：

1
2
/movies/电影名/电影名.mkv
/movies/电影名/电影名.zh.srt

或者：

1
2
/tv/剧名/Season 01/剧名 - S01E01.mkv
/tv/剧名/Season 01/剧名 - S01E01.zh.srt

Jellyfin 对这种目录结构识别比较稳。

7. 字幕编码

进入：

1
Settings -> Subtitles -> Post-Processing

建议开启：

1
Encode Subtitles To UTF8

中文环境里这个很重要，可以减少 Jellyfin 播放中文字幕时出现乱码的概率。

8. Provider 字幕源

进入：

1
Settings -> Providers

添加字幕源。中文环境可以优先试：

1
2
3
Assrt
Zimuku
OpenSubtitles.com

具体能不能用，要看 Bazarr 当前版本、网络环境、账号要求和验证码情况。多个字幕源一起开，成功率会更高。

9. 手动测试

进入：

1
Wanted -> Series

或者：

1
Wanted -> Movies

找一个缺字幕的视频，点进去后选择：

1
Manual Search

看是否能搜到：

1
Chinese Simplified

下载成功后，去视频目录确认是否生成：

1
xxx.zh.srt

然后打开 Jellyfin 播放，手动选择中文字幕测试。

九、推荐配置汇总

如果只想让 Bazarr 稳定给 Jellyfin 下载中文字幕，可以先照这个配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Settings -> Languages
Enabled Languages:
- Chinese Simplified
- Chinese Traditional

Language Profile:
Name: 中文简繁
Languages:
- Chinese Simplified
- Chinese Traditional
Cutoff: Chinese Simplified
Forced: 关闭
HI: 关闭
Exclude Audio: 关闭
Single Language: 关闭

字幕配置：

1
2
3
Subtitle Folder: Alongside Media File
Encode Subtitles To UTF8: 开启
Use Embedded Subtitles: 可开启

已有媒体：

1
2
Series -> Mass Edit -> 全选 -> Language Profile: 中文简繁 -> Save
Movies -> Mass Edit -> 全选 -> Language Profile: 中文简繁 -> Save

十、容易踩坑的地方

这次安装里比较容易踩坑的地方主要有几个。

第一，SSH 如果一直提示密码错误，不一定是密码真的错了，要检查 sshd_config 里有没有 AllowGroups 限制。

第二，DNS 异常会导致 apt update、Docker 拉镜像、OMV 插件安装都失败。装 OMV 前最好先确认 DNS 正常。

第三，Docker Compose 里的路径不要混用。/srv/dev-disk-by-uuid-xxxx 一定要换成真实的数据盘路径，而且 Jellyfin、Bazarr、qBittorrent 看到的媒体路径最好保持一致。

第四，Bazarr 能不能正常下载字幕，关键不只是语言配置，还要看它能不能访问 Sonarr / Radarr / Jellyfin 对应的真实媒体路径。如果手动搜索时报 file not found 或路径错误，就要继续检查 Path Mapping。

第五，公开文章里不要写真实密码、真实内网地址和完整磁盘 UUID。自己留笔记可以写全，发博客最好用占位符。

总结

OMV 本身安装不复杂，真正花时间的地方通常在安装前后的基础环境配置：软件源、网络、SSH、DNS、磁盘路径和 Docker 数据目录。

我的建议是先把系统层面的东西处理稳定，再装 OMV 和插件，最后再通过 Compose 一个个加应用。这样出问题时比较好定位，不会把系统问题、网络问题和容器问题混在一起。

这套配置跑起来之后，基本就能覆盖一个家用 NAS 的核心需求：文件管理、媒体库、下载、照片备份和中文字幕自动化。