外观
环境变量：调整界面里没有的选项
OMV 的界面只覆盖了常用设置，但很多服务的细节参数，例如 SSH 允许哪些组登录、文件系统创建时的 mkfs 选项、告警阈值，都可以用环境变量调整。读完这一篇，你能查到有哪些变量，修改并让它生效，出问题时还原，并且知道不同变量要用不同的生效步骤。
开始之前
- 命令在 OMV 的 shell（root 身份）里执行。
- 环境变量比界面选项更靠近底层，改错会让服务起不来。动手前先在测试机验证，并保证有另一种方式能登录 NAS（例如本机控制台）。
- 本文的变量名和默认值来自 OMV 8.5.x 源码。OMV 版本变化后可能增减，先用
omv-env list确认变量在你的系统上存在。
环境变量会改变服务的配置并触发重新部署
影响范围：变量生效时，相关服务的配置文件会被重新生成并重启（例如 SSH、SMB、Web 界面），已有连接会短暂中断。有些变量只对「之后新创建」的对象有效（例如新建文件系统）。
前置条件：界面里没有待应用的更改；已经备份系统盘或至少备份了 /etc/default/openmediavault；知道要改的变量由谁读取（见下表），以便选对生效步骤。
怎么回退：omv-env unset <变量名> 删除这个变量，再重复一遍生效步骤，服务就回到内置默认值。
环境变量是什么
所有变量保存在 /etc/default/openmediavault，格式是一行一个：
sh
OMV_SSHD_ALLOWGROUPS="root _ssh"这个文件装机时就带有一批内部路径变量，例如 OMV_CONFIG_FILE、OMV_MOUNT_DIR、OMV_WEBGUI_ADMINUSER_NAME，它们告诉 OMV 各种文件放在哪里，不要修改。你要改的是另外那些「有内置默认值、文件里没写」的变量：只有你设置了，才会覆盖默认值。
四类程序会读取它，所以生效步骤不同：
| 读取方 | 例子 | 什么时候读取 |
|---|---|---|
| Salt 状态（生成配置文件） | OMV_SSHD_*、OMV_SAMBA_*、OMV_NGINX_*、OMV_MONIT_* | 部署时，通过 Salt 的 pillar 数据读取 |
PHP（omv-engined 与 Web 后台） | OMV_MKFS_OPTIONS_*、OMV_FSTAB_MNTOPS_* | omv-engined 启动时读取一次 |
脚本（cron、omv-upgrade、omv-btrfs-scrub） | OMV_BTRFS_SCRUB_*、OMV_UPGRADE_APT_ARGS | 每次脚本运行时读取 |
| udev 规则 | OMV_MD_STRIPE_CACHE_SIZE | RAID 设备出现或变化的事件发生时 |
查看与修改
命令行
sh
omv-env list # 所有可用的变量名
omv-env get # 当前文件里已设置的变量
omv-env get <变量名> # 看某个变量
omv-env set -- <变量名> <值> # 设置，值里有空格要加引号
omv-env unset <变量名> # 删除list的内容来自三处：文件里已有的变量、Salt 状态里用到的变量、几个 cron 和 shell 脚本里用到的变量。只在 PHP 里读取的变量不在其中，例如OMV_MKFS_OPTIONS_EXT4。但omv-env set接受任何以OMV_开头的名字。set后面的--不能省，因为值常常以-开头，例如-b 4096。- 变量名只能是大写字母、数字和下划线；值里不能有双引号。含
$或反引号的值会被 shell 脚本在读取这个文件时展开，尽量避免。 set、unset会重写整个文件，只保留OMV_开头的行并按名称排序，你手写的注释会丢失。
envvars 插件
官方插件 openmediavault-envvars 提供了图形界面，入口是 系统 → 环境变量（System → Environment Variables）。它是一个表格，列是名称和值，工具栏有创建、编辑、删除，最右边有一个播放形状的应用（Apply）按钮。插件的概况见 小工具合集。
- 创建时，名称是从下拉列表里选的，列表内容来自
omv-env list。不在这个列表里的变量（例如只在 PHP 里读取的OMV_MKFS_OPTIONS_EXT4），界面里可能选不到，改用命令行。 - 点应用会依次执行
omv-salt stage run prepare、omv-salt stage run deploy和monit restart omv-engined，也就是重新生成所有服务的配置，耗时较长，期间服务会重启。只想影响一个服务时，用命令行更精细。
让改动生效
按变量由谁读取，选下面的步骤：
Salt 读取的变量（大多数）：先重新生成 pillar，再部署受影响的模块。
sh
omv-salt stage run prepare
omv-salt deploy run <模块>prepare 会根据 /etc/default/openmediavault 重新写出 Salt 使用的 pillar 数据，不运行它，deploy run 读到的还是旧值。模块名见 Salt 部署与自定义配置。也可以用 omv-salt stage run deploy 部署所有模块，影响范围大得多。
PHP 读取的变量：重启 RPC 守护进程。
sh
monit restart omv-engined重启后 Web 界面会短暂报错，几秒后刷新即可。
脚本读取的变量：不需要任何操作，下次脚本运行就生效。
udev 读取的变量：下次 RAID 设备触发 add 或 change 事件时生效，重启后一定生效。
官方文档给出的完整顺序是 monit restart omv-engined、omv-salt stage run prepare、omv-salt stage run deploy，三步都做总是安全的。
示例：让另一个组也能 SSH 登录
OMV 默认只允许 root 和 _ssh 组的成员通过 SSH 登录，写在变量 OMV_SSHD_ALLOWGROUPS 里。想让名为 ops 的组也能登录：
sh
omv-env get OMV_SSHD_ALLOWGROUPS # 没设置过时没有输出，默认值是 root _ssh
omv-env set -- OMV_SSHD_ALLOWGROUPS "root _ssh ops"
omv-salt stage run prepare
omv-salt deploy run ssh注意保持当前这个 SSH 会话不要关，另开一个终端测试新的登录，确认没问题后再退出旧会话。要还原：
sh
omv-env unset OMV_SSHD_ALLOWGROUPS
omv-salt stage run prepare
omv-salt deploy run ssh先看有没有扩展选项
SSH 的页面（服务 → SSH，Services → SSH）里有扩展选项（Extra options），能直接追加 sshd_config 的指令。能用扩展选项解决的，不必设环境变量。
常用变量表
下表的默认值是内置默认值，也就是变量没设置时的取值。「来源」是读取它的文件，Salt 状态相对于 /srv/salt/omv/deploy/。
文件系统：创建与挂载
来源：默认值定义在 /usr/share/php/openmediavault/globals.inc，由 .../system/filesystem/backend/ 下的 PHP 文件读取。只影响之后新建、新挂载的文件系统，已经挂载的不受影响。读取方是 PHP，生效步骤是 monit restart omv-engined。
| 变量 | 默认值 | 作用 |
|---|---|---|
OMV_MKFS_OPTIONS_EXT4 | -b 4096 -m 0 -E lazy_itable_init=0,lazy_journal_init=0 -O quota | 创建 EXT4 时传给 mkfs 的参数 |
OMV_MKFS_OPTIONS_XFS | -f | 创建 XFS 时的参数 |
OMV_MKFS_OPTIONS_BTRFS | -O skinny-metadata,^mixed-bg | 创建 Btrfs 时的参数 |
OMV_FSTAB_MNTOPS_EXT4 | defaults,nofail,user_xattr,usrquota,grpquota | EXT4 的挂载选项 |
OMV_FSTAB_MNTOPS_XFS | defaults,nofail,usrquota,grpquota | XFS 的挂载选项 |
OMV_FSTAB_MNTOPS_BTRFS | defaults,nofail | Btrfs 的挂载选项 |
OMV_FSTAB_MNTOPS_NTFS | defaults,nofail,big_writes | NTFS 的挂载选项 |
OMV_FSTAB_MNTOPS_EXFAT | defaults,nofail | exFAT 的挂载选项 |
OMV_FSTAB_MNTOPS_VFAT | defaults,nofail | FAT32 等 VFAT 的挂载选项 |
官方文档里的旧默认值
官方文档的 fs_env_vars 页面里，EXT4 的默认挂载选项还是旧写法 usrjquota=aquota.user,grpjquota=aquota.group,jqfmt=vfsv0。OMV 7.4.6 起，新建的 EXT4 文件系统改用内部配额，源码里的默认值已经是 usrquota,grpquota。官方文档里 NTFS 是 defaults,nofail，源码里还带着 big_writes，exFAT 则在官方文档里没有列出。上表以源码（globals.inc）为准。
已经挂载的文件系统，挂载选项保存在配置数据库里，改变量不会影响它们。要改已有文件系统的选项，见 文件系统挂载选项与 fstab。
另有 OMV_FSTAB_MNTOPS_NONROTATIONAL，默认 noatime,nodiratime：系统盘是固态盘时，初始化阶段会把它加到根分区的挂载选项里，只运行一次（来源 setup/fstab/default.sls）。
Web 管理界面（nginx）
来源：deploy/nginx/files/ 下的 site-webgui.j2、headers.conf.j2、security.conf.j2。生效：prepare，再 omv-salt deploy run nginx。
| 变量 | 默认值 | 作用 |
|---|---|---|
OMV_NGINX_SITE_WEBGUI_CLIENT_MAX_BODY_SIZE | 25M | 通过界面上传文件的大小上限 |
OMV_NGINX_SITE_WEBGUI_FASTCGI_READ_TIMEOUT | 60s | 后端响应的超时时间 |
OMV_NGINX_SITE_WEBGUI_LISTEN_IPV4_ADDRESS | * | 监听的 IPv4 地址 |
OMV_NGINX_SITE_WEBGUI_LISTEN_IPV6_ADDRESS | :: | 监听的 IPv6 地址 |
OMV_NGINX_SITE_WEBGUI_SSL_PROTOCOLS | TLSv1.2 TLSv1.3 | 允许的 TLS 版本 |
OMV_NGINX_SITE_WEBGUI_SECURITY_XFRAMEOPTIONS_ENABLE | yes | 是否发送 X-Frame-Options 头 |
OMV_NGINX_SITE_WEBGUI_SECURITY_XFRAMEOPTIONS | SAMEORIGIN | 该头的取值 |
OMV_NGINX_SITE_WEBGUI_SECURITY_CSP_ENABLE | yes | 是否发送内容安全策略头 |
OMV_NGINX_SITE_WEBGUI_SECURITY_HSTS | max-age=15768000; includeSubDomains | HSTS 头的取值 |
OMV_NGINX_SITE_WEBGUI_INCLUDE_DIR | /etc/nginx/openmediavault-webgui.d | nginx 额外包含的配置目录，放进去的 *.conf 会被加载 |
想把 OMV 界面嵌进导航页的 iframe，需要放宽 X-Frame-Options，这会削弱防点击劫持的保护，只在内网、可信的页面里这样做。
SSH、SMB 与 NFS
SSH 来源 deploy/ssh/files/sshd_config.j2，SMB 来源 deploy/samba/files/global.j2 与 shares.j2，NFS 来源 deploy/nfs/files/etc-exports.j2。生效：prepare，再部署 ssh、samba 或 nfs。
| 变量 | 默认值 | 作用 |
|---|---|---|
OMV_SSHD_ALLOWGROUPS | root _ssh | 允许 SSH 登录的组 |
OMV_SSHD_LOGLEVEL | INFO | sshd 的日志级别 |
OMV_SSHD_LOGINGRACETIME | 120 | 登录宽限时间（秒） |
OMV_SSHD_X11FORWARDING | yes | 是否允许 X11 转发 |
OMV_SSHD_SUBSYSTEM_SFTP | /usr/lib/openssh/sftp-server | SFTP 子系统的程序 |
OMV_SAMBA_SOCKETOPTIONS | TCP_NODELAY IPTOS_LOWDELAY | Samba 的 socket options |
OMV_SAMBA_AIOREADSIZE、OMV_SAMBA_AIOWRITESIZE | 1 | 启用「异步 I/O」时，异步读写的大小门限 |
OMV_SAMBA_SHARE_CREATEMASK、OMV_SAMBA_SHARE_FORCECREATEMODE | 0664 | 共享里新建文件的权限掩码 |
OMV_SAMBA_SHARE_DIRECTORYMASK、OMV_SAMBA_SHARE_FORCEDIRECTORYMODE | 0775 | 共享里新建目录的权限掩码 |
OMV_SAMBA_SHARE_RECYCLE_REPOSITORY | .recycle/%U | 回收站目录，%U 是用户名 |
OMV_SAMBA_SHARE_AUDIT_SUCCESS | mkdirat renameat unlinkat pwrite | 启用「审核文件操作」后，记录哪些成功的操作 |
OMV_WSDD_ENABLED | 1 | SMB 启用时是否启动 wsdd，让 Windows 在「网络」里发现 NAS。1、yes、on、true 算真，设成 0 之后 OMV 不再启动 wsdd-server，已经在运行的实例不会被这一步停掉（按 Salt 状态推断）。来源 deploy/samba/default.sls |
OMV_WSDD_PARAMS | 空 | 追加给 wsdd 的命令行参数。OMV 把 WSDD_PARAMS="--workgroup='<工作组>' <这个变量的值>" 写进 /etc/wsdd-server/defaults，参数写法以 wsdd 项目文档为准。来源 deploy/samba/50wsdd.sls，部署模块 samba。用法见 局域网发现：为什么在网络里看不到 NAS |
OMV_NFSD_V4_PSEUDO_ROOT_OPTIONS | ro,fsid=0,root_squash,subtree_check,secure | NFSv4 伪文件系统根目录的导出选项 |
监测告警阈值（monit）
来源：deploy/monit/services/files/ 下的模板和 deploy/monit/files/etc-monit-monitrc.j2。生效：prepare，再 omv-salt deploy run monit。邮件由 配置邮件通知 里的设置发出，哪些事件会发由 系统 → 通知 → 事件（System → Notification → Events）决定。
| 变量 | 默认值 | 作用 |
|---|---|---|
OMV_MONIT_CHECK_INTERVAL | 30 | 检查周期（秒），下面的「周期数」按它计算 |
OMV_MONIT_SERVICE_FILESYSTEM_ROOT_USAGEWARNTHRESHOLD | 85 | 系统盘（/）使用率告警阈值（%） |
OMV_MONIT_SERVICE_SYSTEM_MEMORYUSAGE | 90 | 内存使用率告警阈值（%） |
OMV_MONIT_SERVICE_SYSTEM_CPUUSAGE_USER、_SYSTEM、_WAIT | 95 | CPU 用户态、内核态、I/O 等待占用的告警阈值（%） |
OMV_MONIT_SERVICE_SYSTEM_CPUUSAGE_CYCLES | 2 | CPU 超过阈值持续多少个周期才告警 |
OMV_MONIT_SERVICE_SYSTEM_LOADAVG_1MIN_MULT、_5MIN_MULT | 2、1 | 1 分钟、5 分钟平均负载的阈值是「CPU 核数乘以这个倍数」 |
OMV_MONIT_SERVICE_SYSTEM_LOADAVG_1MIN_CYCLES、_5MIN_CYCLES | 3 | 负载超过阈值持续多少个周期才告警 |
数据盘的使用率阈值不用环境变量，在 存储器 → 文件系统（Storage → File Systems）里编辑文件系统，用用量警告阈值（Usage Warning Threshold）设置，默认 85%。
系统、电源与内核参数
| 变量 | 默认值 | 作用与来源 |
|---|---|---|
OMV_CPUPOWER_FREQ、OMV_CPUPOWER_MINFREQ、OMV_CPUPOWER_MAXFREQ、OMV_CPUPOWER_PERFBIAS | 空 | 在界面设置了CPU 频率调节后，进一步限制频率范围或设置性能偏好，来源 deploy/cpupower/files/etc-cpupower-service_conf.j2 |
OMV_SYSCTL_DEV_RAID_SPEEDLIMITMIN | 10000 | 写入内核参数 dev.raid.speed_limit_min，决定 RAID 重建和同步的最低速度，单位 KiB/s，来源 deploy/sysctl/mdadm.sls |
OMV_MD_STRIPE_CACHE_SIZE | 8192 | RAID5/6 阵列的 stripe_cache_size，来源 udev 规则 /etc/udev/rules.d/99-openmediavault-md-raid.rules，8.0.4 起提供 |
OMV_SYSTEMD_JOURNALD_SYSTEMMAXUSE | 1G | systemd 日志占用磁盘的上限，来源 deploy/systemd-journald/10default.sls |
OMV_CPUPOWER_GOVERNOR 已经不再使用
OMV 8.0.9 的更新记录曾说，可以用环境变量 OMV_CPUPOWER_GOVERNOR 修改 CPU 调节策略。8.1.0-2 的更新记录要求改在 系统 → 电源管理 → 设置（System → Power Management → Settings）里配置，也就是 CPU 频率调节（CPU frequency scaling）字段。8.5.x 源码里，cpupower 的 Salt 模板读的是这个界面字段，已经没有这个变量，设了也不会有效果。上表里的四个变量才是现在还在用的。
系统盘是固态盘（非旋转设备）时，OMV 还会写入一组减少磁盘写入的内核参数，来源 deploy/sysctl/nonrot.sls，对应的变量都以 OMV_SYSCTL_VM_ 开头：DIRTYBACKGROUNDRATIO（1）、DIRTYRATIO（20）、DIRTYWRITEBACKCENTISECS（12000）、DIRTYEXPIRECENTISECS（12000）、LAPTOPMODE（5）、SWAPPINESS（1）、VFSCACHEPRESSURE（50）。这些参数是整个内核的，数据盘也受影响。
脚本读取的变量
来源：/etc/cron.*/ 下的 openmediavault-* 脚本和 /usr/sbin/ 下的命令。改完立刻生效，不需要部署。
| 变量 | 默认值 | 作用 |
|---|---|---|
OMV_BTRFS_SCRUB_ENABLED | yes | 是否自动对 Btrfs 做 scrub |
OMV_BTRFS_SCRUB_PERIOD | monthly | 自动 scrub 的周期，monthly 或 weekly |
OMV_BTRFS_SCRUB_PRIORITY | -c 2 -n 4 | scrub 的 I/O 优先级参数 |
OMV_BTRFS_SCRUB_READONLY | no | scrub 只检查不修复 |
OMV_BTRFS_ERROR_CHECK_ENABLED | yes | 是否每天检查 Btrfs 设备错误计数 |
OMV_SSL_CERTIFICATE_CHECK_EXPIRY_ENABLED | yes | 是否每天检查证书是否快到期 |
OMV_SSL_CERTIFICATE_CHECK_EXPIRY_DAYS | 7 | 到期前多少天开始告警 |
OMV_SMARTMONTOOLS_UPDATE_DRIVEDB_ENABLED | yes | 是否每周更新 smartmontools 的硬盘数据库 |
OMV_UPGRADE_APT_ARGS | --yes --allow-downgrades --allow-change-held-packages --fix-missing --fix-broken --auto-remove --allow-unauthenticated --option DPkg::Options::=--force-confold | omv-upgrade 传给 apt-get 的参数 |
不要随意改 OMV_UPGRADE_APT_ARGS
这组参数决定了系统更新时如何处理依赖和冲突，改错可能让更新卸载关键软件包。除非你清楚每个参数的含义，否则保持默认。
插件相关变量
插件也用同样的机制：变量写在插件自己的 Salt 状态（或 PHP 代码）里，装了插件才有意义，卸载插件后就没有作用了。生效方式和核心变量一样：Salt 读取的变量先 prepare，再部署表里写的模块；PHP 读取的变量重启 omv-engined。
| 变量 | 默认值 | 来自哪个插件 | 作用 |
|---|---|---|---|
OMV_PROFTPD_UMASK | 000 000 | 官方 openmediavault-ftp，部署模块 proftpd，来源 deploy/proftpd/modules/files/mod_core.j2 | 写进 proftpd.conf 里每个共享文件夹目录和匿名目录的 Umask 指令，两个数依次是新建文件和新建目录的掩码。按 ProFTPD 的规则，000 000 会让新文件是 666、新目录是 777，谁能访问由共享文件夹的权限（<Limit> 规则）决定。想收紧可以改成例如 002 002，上传之后用 ls -l 确认实际权限。见 FTP 与 FTPS（官方插件） |
OMV_RSNAPSHOT_STARTING_HOUR | 2 | omv-extras openmediavault-rsnapshot，部署模块 rsnapshot，来源 deploy/rsnapshot/default.sls | 备份任务的起始小时，写进 /etc/cron.d/openmediavault-rsnapshot：每月（1 日）和每年（1 月 1 日）的任务用它，每日和每周（周一）的任务用它加 1，每小时任务固定在每小时的第 5 分钟。默认的 2 对应每月 02:30、每年 02:00、每日 03:30、每周一 03:00。取 0 到 22，23 加 1 会得到不合法的 24 点。安装插件时，安装脚本会把它写进 /etc/default/openmediavault。见 rsnapshot：轮转快照式备份 |
OMV_RSNAPSHOT_DISABLE_CRON | 0 | 同上 | 设为 1 时，OMV 不再生成上面的 cron 文件，并删除已有的，插件就不会再按计划自动备份。除非你打算自己调度，否则不要设 |
OMV_RSNAPSHOT_LOGFILE | /var/log/rsnapshot.log | 同上 | rsnapshot 的日志文件 |
OMV_RSNAPSHOT_VERBOSE_LO、OMV_RSNAPSHOT_VERBOSE_HI、OMV_RSNAPSHOT_LOG_LEVEL | 2、3、2 | 同上 | 写进每个任务的 rsnapshot 配置：任务设为只输出错误时，verbose 取 _LO，否则取 _HI；loglevel 取 _LOG_LEVEL |
OMV_RSNAPSHOT_DIRS_MASK、OMV_RSNAPSHOT_SCRIPTS_MASK | 2775、755 | 同上 | 前者是备份时对目标目录链执行 chmod 用的权限，后者是插件生成的 rsnapshot 配置文件和脚本的权限 |
OMV_MDMGMT_ALLOW_USB_DEVICES | 未设置，相当于否 | 官方 openmediavault-md，由 PHP 读取（8.1.2 起） | 设为 yes 后，创建软 RAID 的候选磁盘列表才包含 USB 设备，官方默认不支持这样做。它只在 PHP 里读取，不在 omv-env list 里，用命令行设置，改完 monit restart omv-engined。见 软件 RAID：用 md 插件组阵列、外接 USB 硬盘的正确用法 |
rsnapshot 插件还有 OMV_RSNAPSHOT_CONFS_DIR 和 OMV_RSNAPSHOT_CRONSCRIPT，是插件内部使用的路径，不要改。
其他插件的变量写在各自的文章里：ClamAV 病毒扫描（OMV_CLAMAV_CLAMD_*）、用 Fail2ban 封禁暴力破解（OMV_FAIL2BAN_CHAIN）、内核插件（OMV_KERNEL_BOOT_ISO_SUBDIR）、FileBrowser、PhotoPrism、音乐服务：OwnTone 与 Shairport、同步 OneDrive，omv-extras 的软件源变量见 软件源、国内镜像与第一次更新。
找到你要的变量
不知道某项行为能不能用变量调整时，在 OMV 的 shell 里搜源码，这些都是只读命令：
sh
omv-env list | grep -i <关键词>
grep -rn "OMV_<关键词>" /srv/salt/omv /usr/share/php/openmediavault /usr/share/openmediavault /etc/cron.daily 2>/dev/null找到变量后，看它所在的文件是怎样读取的：pillar.get('default:OMV_...', 默认值) 表示 Salt 读取，Environment::get("OMV_...") 表示 PHP 读取，OMV_...=${OMV_...:-"默认值"} 表示脚本读取。
检查结果
用只读命令确认变量已经生效：
sh
omv-env get <变量名> # 文件里的值
grep -A1 "<变量名>" /srv/pillar/omv/default.sls # prepare 之后 Salt 看到的值
omv-salt deploy list-dirty # 没有遗留的待应用模块再检查生成的配置确实变了，例如 SSH 用 sshd -T | grep -i allowgroups。
常见问题
omv-env set 没有报错，但行为没变。 九成是没有执行生效步骤，或者执行了 deploy run 却没有先运行 prepare。按上面的步骤从头做一遍。
envvars 插件的下拉列表里找不到我要的变量。 列表只包含 omv-env list 找到的变量。改用命令行 omv-env set。
改了变量之后，界面提示有待应用的更改吗？ 不会。环境变量不经过配置数据库，所以没有黄色提示条，需要你手动执行生效步骤。
升级之后某个变量失效。 OMV 的变量名和默认值会随版本变化。升级后重新核对，并阅读 OMV 8.1–8.5 更新要点 里和你用到的功能相关的条目。