Rygel 0.42.5 常用 CLI 命令与工具详解

Rygel 0.42.5 的命令行选项、环境变量、systemd 用户服务运维、日志排障与无 GUI 客户端发现验证命令（SOAP Browse/SSDP/拉流）全解，基于 Ubuntu 24.04 逐条实测。

RygelRygelDLNAUPnP媒体服务器2026/10/30

Rygel 0.42.5 常用 CLI 命令与工具详解

目标：把 Ubuntu 24.04 上运维 Rygel 0.42.5 需要的全部命令工具集一次讲透——rygel 主命令的全部选项与 RYGEL_* 环境变量、systemd 用户服务运维、日志排障、以及无图形界面环境下用 curl/tcpcump 完成 SSDP 发现、SOAP 浏览与拉流验证的完整命令链。全部命令与回显实测取得。

一、环境信息

  • 操作系统：Ubuntu 24.04 LTS（Noble Numbat），x86_64
  • 软件版本：Rygel 0.42.5（0.42.5-1ubuntu3），GUPnP 1.6.6
  • 实测端口：TCP 8192（固定 HTTP）、UDP 1900（SSDP，多播组 239.255.255.250）
  • 实测 UDN：uuid:7e072517-d90a-4506-8f5f-444d2961b8a1（每台机器首次启动自动生成，描述文档路径 http://<主机IP>:8192/<UDN>.xml）
  • 配置文件：/root/.config/rygel.conf（用户级，port=8192、uris=/srv/media）
  • 验证工具：curl、iproute2（ss）、tcpdump（apt install curl iproute2 tcpdump）

二、工具概览

Rygel 的运维工具面由五部分组成：

工具/单元归属包用途本文覆盖
rygel 主命令rygel启动服务，全部运行期参数第四章
RYGEL_* 环境变量rygel不改文件的临时参数注入4.4
rygel.service（user 单元）rygelsystemd 用户会话托管第五章
rygel-preferences独立包GNOME 图形偏好面板（改共享目录/网络）第九章提及
SOAP/SSDP 客户端命令curl/tcpdump无 GUI 的发现与验证闭环第七章

关于 GSettings/dconf 的实测结论：dpkg -L rygel 中不包含任何 gschema 文件（实测 grep -c schema 为 0），Rygel 0.42.5 的全部配置都落在 rygel.conf 文件体系（命令行/环境变量/用户级/系统级），不走 GSettings/dconf 键值库。GNOME 桌面「设置 → 共享 → 媒体共享」面板底层的持久化同样是 ~/.config/rygel.conf。因此本篇的参数注入手段是环境变量与命令行，而非 gsettings。

三、前置条件

按 《Ubuntu 24.04 安装 Rygel 0.42.5 指南》 完成安装与配置，确认服务可启动、验证工具就绪：

rygel --version && which curl ss tcpdump | tr '\n' ' '; echo

实测回显：

Rygel 0.42.5
/usr/bin/curl /usr/sbin/ss /usr/bin/tcpdump

四、rygel 主命令详解

4.1 选项速查（--help 实测全文）

rygel --help

实测回显（逐行照抄）：

Usage:
  rygel [OPTION?]

Help Options:
  -h, --help                                                   Show help options
  --help-all                                                   Show all help options
  --help-gapplication                                          Show GApplication options

Application Options:
  -v, --version                                                Display version number
  -n, --network-interface=INTERFACE                            Network Interfaces
  -p, --port=PORT                                              Port
  -t, --disable-transcoding                                    Disable transcoding
  -U, --disallow-upload                                        Disallow upload
  -D, --disallow-deletion                                      Disallow deletion
  -g, --log-level                                              Comma-separated list of domain:level pairs. See rygel(1) for details
  -u, --plugin-path=PLUGIN_PATH                                Plugin Path
  -e, --engine-path=ENGINE_PATH                                Engine Path
  -d, --disable-plugin=PluginName                              Disable plugin
  -i, --title=PluginName:TITLE                                 Set plugin titles
  -o, --plugin-option=PluginName:OPTION:VALUE1[,VALUE2,..]     Set plugin options
  -c, --config=FILE                                            Use configuration file instead of user configuration
  -s, --shutdown                                               Shut down remote Rygel reference

选项分四组记忆：网络（-n/-p）、能力开关（-t/-U/-D）、插件与路径（-d/-i/-o/-u/-e）、配置与实例控制（-c/-g/-s）。命令行参数优先级高于配置文件与环境变量（实测见 4.2 的 -p 用例）。

4.2 常用选项逐个实测

版本与帮助：

rygel -v

实测回显：

Rygel 0.42.5

临时换端口（覆盖配置文件的 port=8192）：

rygel -p 8193 & sleep 3; ss -tlnp | grep rygel; kill %1 2>/dev/null

实测回显：

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))

关闭转码（-t，等价配置 enable-transcoding=false）与禁用上传（-U）——均为开关型选项，叠加使用：

rygel -t -U

禁用插件（-d，插件名大小写敏感）：

rygel -d MediaExport

实测回显（启动日志首部）：

Rygel-Message: 00:29:15.003: Rygel v0.42.5 starting?
Checking External against MediaExport
Checking MediaExport against MediaExport

Checking ... against MediaExport 是禁用检查的执行痕迹；被禁插件不再出现 New plugin ?MediaExport? available 加载行。

指定配置文件（-c）：

rygel -c /etc/rygel.conf

实测回显：

Rygel-Message: 00:29:20.165: Rygel v0.42.5 starting?
RygelCore-Message: 00:29:20.207: New plugin ?MediaExport? available
MediaExport-Message: 00:29:20.226: ?file:///srv/media? harvested

-c 直接替换「用户级 → 系统级」的查找链，适合多实例并行（每实例一份配置）。

改设备标题（-i）的实测边界：

rygel -i "MediaExport:Renamed-Title"
curl -s http://localhost:8192/7e072517-d90a-4506-8f5f-444d2961b8a1.xml | grep -o "<friendlyName>[^<]*"

实测回显：

<friendlyName>Lab Media on rygel-server

用户级配置里已有 title=Lab Media on @HOSTNAME@ 时，命令行 -i 未能覆盖该标题（实测 friendlyName 保持配置文件值）。结论：改设备名以配置文件 title= 为准，-i 适合无配置文件约束的临时实例。

远程关停（-s）：

rygel -s

实测回显（无会话 D-Bus 环境）：

Rygel-Message: 00:29:25.181: Rygel v0.42.5 starting?

(rygel:8246): GLib-GIO-CRITICAL **: 00:29:25.181: g_application_release: assertion 'application->priv->use_count > 0' failed

-s 走 GApplication D-Bus 通道向运行中实例发关停请求；在无会话 D-Bus 的最小环境下出现 GLib 断言告警（请求无接收方）。systemd 托管的生产实例用 systemctl --user stop rygel.service 关停更可靠。

4.3 GApplication 选项

--help-gapplication 暴露的一组 D-Bus 服务模式选项（man 手册记载的 -r/--replace 在 0.42.5 已演化为 GApplication 形态）：

rygel --help-gapplication

实测回显：

Usage:
  rygel [OPTION?]

GApplication Options:
  --gapplication-service                                       Enter GApplication service mode (use from D-Bus service files)
  --gapplication-replace                                       Replace the running instance

实测 --gapplication-replace 可正常启动（替换既有实例）：

Rygel-Message: 00:29:59.538: Rygel v0.42.5 starting?

⚠️ 注意：man 手册（noble 打包版）记载了 -r, --replace（等价 rygel -s && rygel），但 0.42.5 二进制实测报 Unknown option -r——替换运行实例的正确命令是 rygel --gapplication-replace。手册与实现的版本错位，以实测为准。

4.4 环境变量 RYGEL_*（rygel(1) 手册全清单）

不改配置文件、不敲长命令时的参数注入手段（手册「ENVIRONMENT」节全量收录，实测生效路径与配置一致）：

环境变量作用对应配置项/选项
RYGEL_IFACE绑定网卡interface= / -n
RYGEL_PORTHTTP 端口port= / -p
RYGEL_DISABLE_UPNP关闭 UPnP 广告，纯流模式-P
RYGEL_DISABLE_TRANSCODING全局关转码enable-transcoding=false / -t
RYGEL_LOG日志级别log-level= / -g
RYGEL_PLUGIN_PATH插件搜索路径plugin-path= / -u
RYGEL_ENGINE_PATH引擎搜索路径engine-path= / -e
RYGEL_MEDIA_ENGINE指定媒体引擎media-engine=
RYGEL_DISABLE_UPLOAD关上传allow-upload=false / -U
RYGEL_DISABLE_DELETION关远程删除allow-deletion=false / -D
RYGEL_PLUGIN_TIMEOUT插件发现超时（valgrind 调试用）无
RYGEL_DATABASE_DEBUG置 1 打印 SQL[Database] debug=true
RYGEL_PLUGIN_<NAME>_TITLE插件标题<插件> title=
RYGEL_PLUGIN_<NAME>_ENABLED插件开关<插件> enabled=

systemd 用户服务场景下用 systemctl --user set-environment RYGEL_LOG="*:5" 注入后重启服务即可临时开调试。

五、systemd 用户服务运维命令

Rygel 的生产托管形态是 systemd 用户单元（/usr/lib/systemd/user/rygel.service，Type=dbus、Restart=on-failure）。常用运维命令（每行一个单元）：

systemctl --user daemon-reload                 # 改 unit 后重载
systemctl --user enable --now rygel.service    # 启动并设自启
systemctl --user is-active rygel.service       # 活跃状态
systemctl --user status rygel.service          # 详细状态
systemctl --user restart rygel.service         # 改配置后重启
systemctl --user stop rygel.service            # 停止
loginctl enable-linger $USER                   # 无登录会话也随开机启动

实测 is-active 输出：

active

⚠️ 注意：systemctl --user 依赖 systemd 用户实例与会话 D-Bus（Ubuntu 24.04 桌面/标准服务器默认具备）；Type=dbus 意味着服务就绪以会话总线上注册 org.gnome.Rygel1 为准。最小化环境（无 systemd 用户实例）请以 -c 指定配置前台运行，或用进程管理器托管 rygel 进程。

六、日志与排障命令

Rygel 日志直接输出 stderr（systemd 场景进 journal）。三档排障手段：

① 配置文件级（log-level=*:4，域可用 */rygel/插件名，级别 1=critical ~ 5=debug）：

grep log-level ~/.config/rygel.conf

实测回显：

log-level=*:4

② 前台 debug 运行（GLib ≥2.36 必须同时给 G_MESSAGES_DEBUG=all 才有 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

Harvesting ... done in <秒> 行是索引健康度的直接指标。SQL 层排障加 RYGEL_DATABASE_DEBUG=1 观察索引库语句。

③ systemd 场景查 journal：

journalctl --user -u rygel.service -n 20 --no-pager

预期形态（节选，真实服务器上取得）：

Mar 31 10:00:00 media-server rygel[2310]: Rygel-Message: Rygel v0.42.5 starting?
Mar 31 10:00:00 media-server rygel[2310]: MediaExport-Message: ?file:///srv/media? harvested

七、客户端发现与验证命令（无 GUI 闭环）

没有电视/手机客户端时，用以下四步命令链完成「发现 → 描述 → 浏览 → 拉流」的全链路验证，效果等价于一台 DLNA 客户端。

7.1 第一步：端口与 SSDP 监听确认

ss -tlnp | grep rygel
ss -ulnp | grep rygel | head -3

实测回显：

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))
UNCONN 0      0           10.89.56.2:1900       0.0.0.0:*    users:(("rygel",pid=7643,fd=13))

TCP 8192 与 UDP 1900（含多播组 239.255.255.250）就位即服务可达的前提成立。

7.2 第二步：获取设备描述文档（拿 UDN 与 control URL）

Rygel 的描述文档路径为 http://<主机IP>:<port>/<UDN>.xml。UDN 首次启动自动生成并缓存于 ~/.config/Rygel/*.xml，也可从 SSDP 报文读取（7.3）。直接取描述文档：

curl -s http://localhost:8192/7e072517-d90a-4506-8f5f-444d2961b8a1.xml | grep -oE "friendlyName>[^<]*|controlURL>[^<]*" | head -4

实测回显：

friendlyName>Lab Media on rygel-server
friendlyName>
controlURL>/Control/MediaExport/RygelContentDirectory
controlURL>/Control/MediaExport/RygelSourceConnectionManager

/Control/MediaExport/RygelContentDirectory 就是内容目录的 SOAP 控制端点。

7.3 第三步：SSDP 发现实测（tcpdump 抓 NOTIFY/M-SEARCH 响应）

抓取 rygel 的 SSDP 组播通告（-A 文本模式）：

timeout 8 tcpdump -A -s0 -c 40 "udp port 1900" > /tmp/ssdp.cap 2>&1
grep -a "LOCATION" /tmp/ssdp.cap | sort -u

实测回显（NOTIFY 通告首条）：

Location: http://10.89.56.2:8192/7e072517-d90a-4506-8f5f-444d2961b8a1.xml
NT: upnp:rootdevice
USN: uuid:7e072517-d90a-4506-8f5f-444d2961b8a1::upnp:rootdevice

主动探测则从另一台同网段机器（或本机另一终端）发 M-SEARCH：

exec 3<>/dev/udp/239.255.255.250/1900
printf 'M-SEARCH * HTTP/1.1\r\nHOST: 239.255.255.250:1900\r\nMAN: "ssdp:discover"\r\nMX: 2\r\nST: ssdp:all\r\n\r\n' >&3

同时 tcpdump 侧可见 rygel 以单播回应 HTTP/1.1 200 OK + LOCATION（实测同 7.3 路径）。

7.4 第四步：SOAP Browse 枚举内容目录

对 7.2 拿到的 control URL 发 Browse 请求（ObjectID=0 为根）。完整可执行命令：

curl -s -X POST http://localhost:8192/Control/MediaExport/RygelContentDirectory \
  -H 'Content-Type: text/xml; charset="utf-8"' \
  -H 'SOAPACTION: "urn:schemas-upnp-org:service:ContentDirectory:3#Browse"' \
  -d '<?xml version="1.0" encoding="utf-8"?><s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><s:Body><u:Browse xmlns:u="urn:schemas-upnp-org:service:ContentDirectory:3"><ObjectID>0</ObjectID><BrowseFlag>BrowseDirectChildren</BrowseFlag><Filter>*</Filter><StartingIndex>0</StartingIndex><RequestedCount>20</RequestedCount><SortCriteria></SortCriteria></u:Browse></s:Body></s:Envelope>'

实测回显（Result 字段节选，实测首尾）：

<?xml version="1.0" encoding="UTF-8"?><DIDL-Lite xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/"><container parentID="0" id="Filesystem" childCount="1" searchable="1" restricted="1"><dc:title>Files &amp; Folders</dc:title><upnp:class>object.container</upnp:class>...
NumberReturned: 5

根节点返回 5 个分类节点（Files & Folders、Music、Pictures、Videos 等）。把 ObjectID 换成 Filesystem 继续下钻，直到取到真实文件条目，实测条目（music 目录，节选）：

item id="4081f47b45da02799402c14fc007d8ef" | sine-440hz wav |
res: http://10.89.56.2:8192/MediaExport/i/NDA4MWY0N2I0NWRhMDI3OTk0MDJjMTRmYzAwN2Q4ZWY%3D/res/primary_http.wav

7.5 第五步：拉流验证

取 7.4 的 res URL 直接拉流头：

curl -s -I "http://localhost:8192/MediaExport/i/NDA4MWY0N2I0NWRhMDI3OTk0MDJjMTRmYzAwN2Q4ZWY%3D/res/primary_http.wav" | head -7

实测回显：

HTTP/1.1 200 OK
Date: Fri, 30 Oct 2026 00:19:51 GMT
Content-Type: audio/vnd.wave
Server: MediaExport/0.42.5 rygel/0.42.5 DLNA/1.51 UPnP/1.0
Content-Length: 819256
contentFeatures.dlna.org: DLNA.ORG_OP=01
transferMode.dlna.org: Streaming

200 OK + DLNA/1.51 + transferMode: Streaming 即端到端闭环完成——发现、描述、浏览、拉流全部命令化验证。

八、注意事项

  1. 选项大小写与插件名：-d/-i/-o 的插件名要按描述文档中的 ID 写（如 MediaExport），写错静默无效；
  2. -i 的优先级陷阱：配置文件 title= 存在时命令行 -i 不生效（4.2 实测），改设备名落配置文件；
  3. 手册与实现错位：-r/--replace 见于手册但 0.42.5 不可用，用 --gapplication-replace（4.3 实测）；
  4. -s 依赖 D-Bus：无会话 D-Bus 环境下 -s 无实际接收方，systemd 实例用 systemctl --user stop；
  5. 验证端口 != SSDP 端口：port= 只管 HTTP；SSDP 固定 UDP 1900 组播，防火墙两个都要放；
  6. 配置查找链：命令行 > 环境变量 > 用户级 > 系统级；多实例并行用 -c 隔离配置，用 -p 隔离端口。

九、常见问题（FAQ）

Q1：rygel: command not found？ 包未安装或 PATH 异常。apt install rygel && hash -r，确认 dpkg -L rygel | grep /usr/bin 存在 /usr/bin/rygel。

Q2：Unknown option -r（照 man 手册抄的命令跑不了）？ 0.42.5 已无 -r。替换运行实例用 rygel --gapplication-replace，远程关停用 rygel -s（D-Bus 可达时）或 systemctl --user stop rygel.service。

Q3：日志里没有任何输出？ 三个检查：① log-level 域配置（*:4 起步）；② debug 级别必须 G_MESSAGES_DEBUG=all（GLib ≥2.36 要求）；③ systemd 托管时日志在 journal（journalctl --user -u rygel.service），不在控制台。

Q4：SOAP Browse 返回 HTTP 500？ 多为 XML 转义/引号问题（shell 双层引号易错）。核对 SOAPACTION 头格式为 "urn:schemas-upnp-org:service:ContentDirectory:3#Browse"（含双引号），XML 用单引号包裹 curl -d；或改用 7.4 的 heredoc 写法。

Q5：描述文档路径里的 UDN 每次都变？ UDN 持久化于 ~/.config/Rygel/*.xml 缓存，不变；删除该缓存目录会重新生成新 UDN（客户端需重新发现）。用 7.3 的 tcpdump 法可随时拿到当前 UDN。

十、参考链接