Rygel 0.42.5 配置参数详解

目标：逐项讲清 Rygel 0.42.5 的 rygel.conf 配置体系——general 全局区、GstMediaEngine 转码区、插件公共参数与 MediaExport/Tracker/Playbin/GstLaunch 等各插件专属段，并给出可直接落地的生产配置模板。全部参数行为与默认值在 Ubuntu 24.04 LTS + Rygel 0.42.5 实测核对。

一、环境信息

• 操作系统：Ubuntu 24.04 LTS（Noble Numbat），x86_64
• 软件版本：Rygel 0.42.5（0.42.5-1ubuntu3），GUPnP 1.6.6，GStreamer 1.24.2
• 配置文件：用户级 /root/.config/rygel.conf（本文实测载体）、系统级 /etc/rygel.conf（包自带 180 行注释模板）
• 参数权威来源：rygel.conf(5) 手册（noble 打包版本日期 03/31/2024）+ /etc/rygel.conf 注释模板 + 实测验证
• 实测端口：TCP 8192（固定）/ UDP 1900（SSDP）；媒体目录 /srv/media
• 插件清单：Ubuntu 主包实际携带 media-export、external、mpris 三个插件（ls /usr/lib/x86_64-linux-gnu/rygel-2.8/plugins/ 实测），Tracker/Playbin/GstLaunch/Ruih 由 rygel-tracker 等独立包提供

二、前置条件

按同系列 《Ubuntu 24.04 安装 Rygel 0.42.5 指南》 完成安装（apt install rygel，版本 Rygel 0.42.5），并确认配置查看能力：

rygel --version && ls /etc/rygel.conf ~/.config/rygel.conf

实测回显：

Rygel 0.42.5
/etc/rygel.conf  /root/.config/rygel.conf

对 rygel.conf 有写入权限的用户身份运行 Rygel（系统服务托管时为启动服务的用户；用户级服务时为当前用户）。

三、参数查看与修改方式

3.1 三层配置来源与优先级

Rygel 按以下优先级取参（rygel.conf(5) 原文与实测一致）：

1. 命令行参数（最高）：rygel -p 8193、-t、-d 插件名 等，覆盖文件配置；
2. 环境变量：RYGEL_PORT、RYGEL_IFACE、RYGEL_LOG、RYGEL_DISABLE_TRANSCODING 等（完整清单见同系列命令篇）；
3. 用户级配置 $XDG_CONFIG_DIR/rygel.conf（root 默认 /root/.config/rygel.conf，普通用户 ~/.config/rygel.conf）；
4. 系统级配置 /etc/rygel.conf（用户级文件不存在时的兜底）。

验证优先级的实测（用户级固定 8192，命令行临时改 8193）：

rygel -p 8193 & sleep 3; ss -tlnp | grep rygel; kill %1

实测回显：

LISTEN 0      10        10.89.56.2:8193       0.0.0.0:*    users:(("rygel",pid=8901,fd=16))
LISTEN 0      10         127.0.0.1:8193       0.0.0.0:*    users:(("rygel",pid=8901,fd=12))

命令行 -p 成功压过文件里的 port=8192。改完配置的生效方式：重启 rygel 进程（systemd 用户服务则 systemctl --user restart rygel.service）。

3.2 语法约定

• INI 分区格式：[general]、[GstMediaEngine]、[插件名]；
• 列表用分号分隔（uris=@MUSIC@;/srv/media、transcoders=mp3;lpcm;mp2ts），布尔值 true/false；
• 变量替换：@MUSIC@/@VIDEOS@/@PICTURES@ 展开 XDG 媒体目录（通常 $HOME/Music|Videos|Pictures），@REALNAME@/@USERNAME@/@HOSTNAME@/@PRETTY_HOSTNAME@ 在 title 中替换为用户/主机信息；
• 普通路径含空格无需转义、无需引号（手册原文明确：uris=/home/user/My Pictures 直接写）。

3.3 查看当前生效配置的手段

Rygel 没有「dump 配置」子命令，核查生效配置用三招：① 看进程实际参数 ps -ef | grep [r]ygel；② 看端口 ss -tlnp | grep rygel；③ 开 debug 日志确认加载的插件与引擎（RYGEL_LOG="*:5" G_MESSAGES_DEBUG=all rygel 2>&1 | grep -iE "plugin|engine"）。手册与包模板也常备本地可查：

man 5 rygel.conf | head -20

实测回显（首段）：

RYGEL.CONF(5)                               Rygel User Manual                              RYGEL.CONF(5)

NAME
       rygel.conf - Rygel configuration file

SYNOPSIS
       $XDG_CONFIG_DIR/rygel.conf
       /etc/rygel.conf

四、参数总览

rygel.conf 的分区与参数全景（默认值取自 /etc/rygel.conf 包模板与 man 手册，全部经实测核对）：

表格解读：先抓三条主线——① [general] 管网络与全局行为；② [GstMediaEngine] 管转码；③ 各插件分区管内容来源与渲染器。Ubuntu 主包只带 media-export/external/mpris 三插件，其余分区写了也不生效（装独立包才有对应插件），这是新手最常踩的坑。

五、核心参数分类详解

5.1 网络绑定：ipv6、interface、port

三个参数决定 Rygel 在哪里可达：

• ipv6=true（默认）：同时绑定 IPv6；无 IPv6 的内网建议 false，避免启动时协议栈告警（本文实测环境即 ipv6=false）；
• interface=（默认空）：空 = GSSDP 自动探测全部网卡；也可指定网卡名、IP 甚至无线 ESSID（Linux），多个用分号分隔。多网卡服务器建议显式绑定业务网卡，避免把服务发到管理网；
• port=0（默认）：动态端口（49152 起）；生产固定（本文 8192），便于防火墙与监控。

实测固定端口的生效回显：

ss -tlnp | grep 8192 && ss -ulnp | grep 1900 | head -2

LISTEN 0      10        10.89.56.2:8192       0.0.0.0:*    users:(("rygel",pid=7643,fd=16))
LISTEN 0      10         127.0.0.1:8192       0.0.0.0:*    users:(("rygel",pid=7643,fd=13))
UNCONN 0      0      239.255.255.250:1900       0.0.0.0:*    users:(("rygel",pid=7643,fd=14))

注意：port 只约束 HTTP（描述文档/SOAP/拉流）；SSDP 发现固定走 UDP 1900 组播，与 port 无关。

5.2 转码与媒体引擎：enable-transcoding、media-engine、transcoders

enable-transcoding=true（默认）开启按需转码；实际转码器集合由 [GstMediaEngine] transcoders 列表决定。手册定义的可选值为 lpcm、mp3、mp2ts、aac、avc、wmv 六种（/etc/rygel.conf 模板默认 mp3;lpcm;mp2ts;wmv;aac;avc 全开）。

💡 技术拓展：六个转码目标怎么选——

转码器	输出封装格式/编码	典型用途
lpcm	WAV/LPCM 音频	无损兼容，老式音响/PS3
mp3	MP3 音频	万金油音频，所有客户端都吃
mp2ts	MPEG-TS（MPEG2）	老电视/机顶盒的视频兜底
aac	AAC 音频	新一代音频，码率效率高
avc	H.264/AVC	高清视频转码目标
wmv	WMV	Windows 生态老设备

转码是 CPU 实时软转，客户端请求带 transcoded 协议信息的 res 时才触发；媒体库以 MP4/H.264 为主时只留 mp3;avc（或全关 -t/enable-transcoding=false）可显著降低 CPU 峰值。本文实测采用默认全开以验证功能，生产按媒体库构成裁剪。

media-engine=librygel-media-engine-gst.so（默认）指定媒体引擎模块；上游还提供 librygel-media-engine-simple.so（无 GStreamer 的纯文件直出引擎，编译时 --with-media-engine=simple），插件目录实测两引擎并存：

ls /usr/lib/x86_64-linux-gnu/rygel-2.8/engines/

实测回显：

librygel-media-engine-gst.so  librygel-media-engine-simple.so
media-engine-gst.plugin  media-engine-simple.plugin

5.3 上传与删除控制：allow-upload、allow-deletion 与落地目录

• allow-upload=false（默认）：UPnP 客户端可否上传媒体到服务器；开启后落地目录按媒体类型分流：
  • video-upload-folder=@VIDEOS@（默认 ~/Videos）
  • music-upload-folder=@MUSIC@（默认 ~/Music）
  • picture-upload-folder=@PICTURES@（默认 ~/Pictures）
• allow-deletion=false（默认）：客户端能否通过 UPnP 远程删除媒体。

安全建议：两者保持默认关闭；确需上传能力时，把三个 upload-folder 指向专用目录并确保 uris 覆盖该目录（否则上传成功但不出现在内容目录）。同时注意手册警告：开启 extract-metadata 时不要把导出目录本身当上传目标（半成品文件会被抓去提取元数据而失败入列）。

5.4 日志：log-level 与调试开关

log-level=*:4（默认）语法为「域:级别」逗号列表，域可为 *、rygel 或插件名，级别 1=critical、2=error、3=warning、4=message/info、5=debug。实测排障组合：

RYGEL_LOG="*:5" G_MESSAGES_DEBUG=all rygel 2>&1 | grep -E "MediaExport|plugin" | head -4

实测回显：

RygelCore-Message: 00:16:36.309: New plugin ?MediaExport? available
MediaExport-Message: 00:16:36.344: ?file:///srv/media? harvested
MediaExport-Message: 00:16:36.347: rygel-media-export-harvesting-task.vala:313: Harvesting of file:///srv/media done in 0.014195
MxExtract-Message: 00:16:36.348: rygel-media-export-extract.vala:180: Started with descriptors 3 (in) 4 (out), extracting meta-data: true

手册明确：GLib ≥ 2.36 后想看到 debug 输出必须同时设 G_MESSAGES_DEBUG=all。[Database] debug=true（或环境变量 RYGEL_DATABASE_DEBUG=1）额外打印 SQLite 执行的 SQL，排查索引库问题时使用。

5.5 访问控制与兼容性：acl-fallback-policy、strict-dlna、force-downgrade-for

• acl-fallback-policy=true（默认）：D-Bus 上找不到访问控制提供者时的兜底策略——true 放行所有对端。内网公开共享保持默认；面向不可信网络时改 false（全拒）并接入访问控制提供者；
• strict-dlna=false（默认）：true 时关闭一批「提升兼容性但破坏标准一致性」的特性——仅在有客户端明确需要严格 DLNA 行为时打开；
• force-downgrade-for=（默认注释掉的内置 UA 列表）：对列出的客户端 User-Agent 强制降级到 MediaServer:1/ContentDirectory:1。手册红字警告：仅按 IOP 指引修改，随意改动反而制造不兼容。

5.6 插件公共参数：enabled、title、server-name 等

每个 [插件名] 分区共享以下参数（man 手册「PLUGIN-SPECIFIC SETTINGS」节）：

• enabled：插件开关。实测配置中只留 MediaExport 时，日志恰好只加载它（New plugin ?MediaExport? available）；
• title：对客户端暴露的设备名，支持 @REALNAME@/@USERNAME@/@HOSTNAME@/@PRETTY_HOSTNAME@ 变量。实测 title=Lab Media on @HOSTNAME@ 后，设备描述文档 friendlyName 即为 Lab Media on rygel-server；
• energy-management=true：设备加挂 EnergyManagement 服务（按 [EnergyManagement-网卡名] 分区配置 suspend 唤醒细节：mode-on-suspend、supported-transport、password）；
• diagnostics=true：设备加挂 BasicManagement:2 服务（支持远程 ping/nslookup/traceroute）；
• server-name：自定义 HTTP 响应 Server: 头（实测默认头为 MediaExport/0.42.5 rygel/0.42.5 DLNA/1.51 UPnP/1.0）。

5.7 MediaExport 插件（本地目录导出核心）

MediaExport 是 Ubuntu 主包默认的内容引擎：递归索引 uris 目录，元数据落 SQLite（$XDG_CACHE_HOME/rygel/media-export.db），实测首次收割 3 类媒体仅 0.014~0.099 秒。参数逐个说明：

• uris=/srv/media：导出目录（文件/目录/GVFS URI 均可，分号分隔；@MUSIC@;@VIDEOS@;@PICTURES@ 为默认）。手册示例：uris=@MUSIC@;/home/user/My Pictures;file:///home/user/My%20Videos；
• extract-metadata=true（默认）：GStreamer 提取时长/艺术家/分辨率。false 可大幅加速首次扫描，但客户端看不到元数据，且务必配 include 过滤避免暴露不可播文件；
• monitor-changes=true（默认）：inotify 目录监控，新文件自动入列；
• monitor-grace-timeout=5（默认）：文件出现后等待 5 秒再提取（等下载写完），下载目录场景可调大；
• virtual-folders=true（默认）：生成 Music/Pictures/Videos 虚拟分类。实测 SOAP Browse 根节点返回 5 个分类节点（Files & Folders、Music、Pictures、Videos 等），关闭后只剩目录树。

互斥规则（手册原文）：Tracker 与 MediaExport 同时启用时，MediaExport 自动让位于 Tracker 插件。Ubuntu 主包未装 Tracker 插件（rygel-tracker 独立包），所以 /etc/rygel.conf 里默认启用的 [Tracker3]/[Tracker] 分区在纯主包环境下不产生效果——实测日志中只出现 MediaExport 加载记录，这是「配置写了不生效」的头号原因。

5.8 Tracker/Tracker3 插件（需独立安装 rygel-tracker）

安装 apt install rygel-tracker 后生效（本文主包环境未装，以下为包模板与手册参数）：

• share-pictures/share-videos/share-music=true：分享 Tracker 全库对应类型媒体；
• only-export-from=@MUSIC@;@VIDEOS@;@PICTURES@：限定只导出来自这些目录的条目；
• strict-sharing=false：严格分享控制开关。

选型提示：桌面 GNOME 用户（系统已跑 Tracker 索引）用 Tracker 插件复用全系统索引；纯服务器/无 Tracker 环境用 MediaExport 自建索引，二者别同时开。

5.9 渲染器侧：Playbin 插件与 [Renderer] 区

rygel-playbin 独立包提供 Playbin 插件——把本机变成 DLNA 投放渲染器（DMR，旧名 GstRenderer）：

• audio-sink/video-sink：自定义输出 sink（gst-launch 语法片段），手册建议默认 playbin 自动选择，仅在无声/黑屏时手工指定（如 video-sink=fakesink 做无头测试）；
• [Renderer] image-timeout=15：幻灯播放时每张图片默认停留秒数（DLNA 规范要求 5~15 秒区间）。

主包环境 [Playbin] enabled=true 写了也无效（插件不存在），装 rygel-playbin 后即开箱可用。MPRIS 插件（主包自带）是另一条渲染器路线：把实现了 MPRIS2 D-Bus 规范的播放器（Rhythmbox/VLC/Banshee 等）注册为 DMR，配置按对端 D-Bus 名分区（如 [org.mpris.MediaPlayer2.banshee] title=...）。

5.10 GstLaunch 插件（管道即内容）

rygel-gst-launch 独立包提供 GstLaunch 插件，把任意 gst-launch 语法管道发布为 UPnP 媒体条目（如把 audiotestsrc 或摄像头发成网络流）：

• launch-items=audiotestsrc;videotestsrc：条目 ID 列表；
• 每个 ID 三个属性：<id>-title（标题）、<id>-mime（MIME 类型）、<id>-launch（管道定义），可选 <id>-dlnaprofile（DLNA profile）。

包模板示例（默认 enabled=false）：

[GstLaunch]
enabled=false
launch-items=audiotestsrc;videotestsrc;videotestoverlay
audiotestsrc-title=Audiotestsrc
audiotestsrc-mime=audio/x-wav
audiotestsrc-launch=audiotestsrc ! wavenc
videotestsrc-title=Videotestsrc
videotestsrc-mime=video/mpeg
videotestsrc-launch=videotestsrc ! video/x-raw,width=640,height=480 ! avenc_mpeg2video ! mpegtsmux

5.11 External、LMS、Ruih 与示例插件

• [External]（主包自带，默认 false）：消费 D-Bus MediaServer2 规范，把 Rhythmbox、gnome-dvb-daemon、Grilo 等应用的媒体转发为 UPnP；可按对端 D-Bus 名逐个开关（[org.gnome.UPnP.MediaServer2.Rhythmbox] enabled=false）；
• [LMS]（LightMediaScanner，默认 false）：导出 lightmediascanner 守护进程的库，无专属参数；
• [Ruih]（远程 UI，独立包 rygel-ruih）：title=Rygel Remote UI Server；
• [Test]/[ExampleServerPluginVala] 等（默认 false）：上游源码树自带的开发示例插件，生产保持关闭。

六、生产配置模板

6.1 轻量家庭服务器模板（4GB 内存 / 机械盘 / 数千文件）

适用：小型家庭 NAS、树莓派级设备，媒体库数千条目，客户端为电视/手机 DLNA App。

[general]
ipv6=false
port=8192
log-level=*:3
enable-transcoding=true
allow-upload=false
allow-deletion=false

[GstMediaEngine]
transcoders=mp3;lpcm;mp2ts

[MediaExport]
enabled=true
title=Home Media on @PRETTY_HOSTNAME@
uris=/srv/media
extract-metadata=true
monitor-changes=true
monitor-grace-timeout=30
virtual-folders=true

要点：日志降到 warning 减噪；上传/删除保持关闭；转码只留音频与 MPEG-TS 兜底（电视场景最常用）；下载目录的 grace 提到 30 秒防半成品入列。

6.2 高性能库模板（16GB 内存 / NVMe / 数万文件 / MP4 为主）

适用：独立媒体服务器，库已规范转码为 H.264/AAC，追求低 CPU 与快索引。

[general]
ipv6=true
port=8192
log-level=*:3
enable-transcoding=false
allow-upload=true
allow-deletion=false
video-upload-folder=/srv/incoming/videos
music-upload-folder=/srv/incoming/music
picture-upload-folder=/srv/incoming/pictures

[MediaExport]
enabled=true
title=MediaVault on @PRETTY_HOSTNAME@
uris=/srv/media;/mnt/nas-archive
extract-metadata=true
monitor-changes=true
monitor-grace-timeout=10
virtual-folders=true

要点：源文件已是通用格式，转码全关（enable-transcoding=false 等价于命令行 -t）把 CPU 留给并发拉流；上传开但落地到 incoming 隔离目录（不与 uris 交叉，避免半成品被元数据提取干扰）。

模板通用提示：两档模板都固定 port=8192 并配套 ufw 放行 8192/tcp 与 1900/udp；改配置后 systemctl --user restart rygel.service 生效，用 ss -tlnp | grep 8192 验证。

七、常见问题（FAQ）

Q1：改了 /etc/rygel.conf 为什么没生效？ 三个原因逐查：① 用户级 ~/.config/rygel.conf 优先级更高（存在即覆盖系统级）；② 配的是未安装插件的分区（如无 rygel-tracker 时 [Tracker3] 无效，Ubuntu 主包只带 media-export/external/mpris）；③ 改后未重启进程。验证方式：RYGEL_LOG="*:5" G_MESSAGES_DEBUG=all rygel 2>&1 | grep plugin 看实际加载了什么。

Q2：transcoders 里写了新转码器不生效？ 可选值仅 lpcm/mp3/mp2ts/aac/avc/wmv 六个，写其他值会被忽略；且 enable-transcoding=false（或 -t）时 transcoders 列表整体失效。同时确认对应 GStreamer 插件包已装（如 avc 需要 libav）。

Q3：媒体库里出现下载中的半成品文件？ 把 monitor-grace-timeout 调大（如 30 秒）；或把下载目录隔离在 uris 之外、完成后脚本移入。手册特别警告不要在开启 extract-metadata 的导出目录里直接做上传目标。

Q4：多网卡服务器只想对内网发布？ interface=eth1（或内网 IP）显式绑定；同时确认 ufw 只放行内网网段 ufw allow from 192.168.1.0/24 to any port 8192 proto tcp。

Q5：索引库损坏/想重建索引？ 停服务后删除 $XDG_CACHE_HOME/rygel/（root 为 /root/.cache/rygel/，含 media-export.db），重启自动全量重建。首次收割耗时与文件数量、extract-metadata 开关直接相关。

八、参考链接

• rygel.conf(5) 手册（noble）：https://manpages.ubuntu.com/manpages/noble/en/man5/rygel.conf.5.html（本篇默认值/互斥规则来源）
• 包内模板：/etc/rygel.conf（Rygel 0.42.5-1ubuntu3 附带，180 行全注释）
• 安装与托管：《Ubuntu 24.04 安装 Rygel 0.42.5 指南》
• 选型背景：《Rygel 介绍与选型指南》
• 同系列：《Rygel 0.42.5 常用 CLI 命令与工具详解》
• 上游仓库：https://gitlab.gnome.org/GNOME/rygel