Fast-DDS 3.6.2 常用 CLI 命令详解

目标：逐参数实测 eProsima Fast DDS 3.6.2 自带的 fastdds 命令行工具——discovery（Discovery Server 启动/守护进程管理，含 -l/-p/-t/-q/-b/-x/-i 全参数与 start/stop/list 守护子命令）、shm（共享内存僵尸文件清理）、xml（配置校验）三个命令族，以及客户端 XML 对接、参数覆盖优先级、退出码行为等排障要点。全部命令与回显均在 Ubuntu 22.04 实机实测通过。组件背景见本专栏《Fast-DDS 3.6.2 介绍与选型指南》，安装步骤见《Ubuntu 22.04 安装 Fast-DDS 3.6.2 指南》，XML Profiles 配置详解见《Fast-DDS 3.6.2 配置参数详解》。

一、CLI 总览与实测环境

fastdds 是随库一同安装的运维入口，负责三件事：起 Discovery Server、清理共享内存、校验 XML。本文实测环境与专栏前几篇同机同源码工作区：

项目	值
操作系统	Ubuntu 22.04 LTS（x86_64，root 用户）
Fast DDS 版本	v3.6.2（源码 colcon 编译安装，工作区 `/root/fastdds_ws`）
CLI 安装位置	`/root/fastdds_ws/install/fastdds/bin/`（`fastdds`、`fast-discovery-server`、`fast-discovery-server-1.0.1`、`ros-discovery`）
实测目录	`/root/clitest`
实测日期	2026-10-23

每个 shell 先加载环境（不加载则直连库失败，见第九章排障第 1 条）：

source /root/fastdds_ws/install/setup.bash

版本与命令清单：

fastdds -v

实测回显：

Fast DDS version: 3.6.2.0

fastdds -h

实测回显：

usage: fastdds <command> [<command-args>]

    Commands:

    	discovery     Server-Client discovery auxiliary generator

    	shm           Shared-memory commands

    	xml           XML commands

    fastdds <command> [-h] shows command usage

顶层只有三个子命令：discovery、shm、xml。下文逐族展开。

💡 说明：fastdds 本体是 Python 包装脚本，discovery 真正拉起的 server 进程是同目录下的 C++ 二进制 fast-discovery-server-1.0.1（守护进程模式下即以该进程常驻）。ros-discovery 是面向 ROS 2 场景的辅助工具，不属于本文范围。

二、fastdds discovery：Discovery Server 命令族

Discovery Server 是 Fast DDS 的中央发现服务：参与者作为 CLIENT 只与 SERVER 交换发现信息，不再组播广播，适合跨网段、禁组播的大规模生产网络（四种发现范式的对比见《Fast-DDS 3.6.2 介绍与选型指南》）。

2.1 参数全景

fastdds discovery -h

实测逐参数整理（原文见 -h 输出，此处按语义归档）：

参数	默认值	说明
`-l` / `--udp-address`	`0.0.0.0/::0`	UDP 监听地址（可给接口名，可多次出现）
`-p` / `--udp-port`	`11811`	UDP 监听端口（可多次出现，与 `-l` 成对）
`-t` / `--tcp-address`	`0.0.0.0/::0`	TCP 监听地址
`-q` / `--tcp-port`	`42100`	TCP 监听端口
`-b` / `--backup`	关	启动带备份文件的服务端（崩溃重启可恢复状态），必须搭配 `-i`
`-x` / `--xml-file`	无	从 XML 读配置；与 CLI 参数冲突时 CLI 参数覆盖 XML
`-i` / `--server-id`	无	服务端 ID，生成固定 GUID 前缀（帮助原文标注 deprecated 但仍可用）
`-e` / `--examples`	—	打印用法示例（10 条常规 + 7 条守护进程示例）

fastdds discovery -e 的示例原文节选（第 1/2/6 条最有生产价值）：

Examples:
	1.  Launch a default server listening on all available interfaces on
	    UDP port 11811. Only one server can use default values per machine.

	    $ fastdds discovery

	2.  Launch a default server listening on localhost on UDP port 14520.
	    Only localhost clients can reach the server, for example using
	    ROS_DISCOVERY_SERVER=127.0.0.1:14520

	    $ fastdds discovery -l 127.0.0.1 -p 14520

	6.  Launch a default server listening on 172.31.44.1 on UDP port 12345
	    and provided with a backup file. If the server crashes it will
	    automatically restore its previous state when reenacted.

	    $ fastdds discovery -l 172.31.44.1 -p 12345 -b

2.2 UDP 服务端：-l / -p 实测

timeout 8 fastdds discovery -l 127.0.0.1 -p 11811

实测回显（完整生命周期，含 timeout 发出 SIGTERM 后的优雅退出）：

#### Server started ####
  GUID prefix: 01.0f.2b.9f.6e.28.b5.14.00.00.00.00
  Running on:  UDPv4:[127.0.0.1]:11811

### Server shut down ###

Running on: 一行就是客户端要对接的监听地址；不传 -l 时监听 0.0.0.0。

2.3 -i：固定 GUID 前缀

timeout 8 fastdds discovery -i 1 -p 11811

实测回显：

#### Server started ####
  GUID prefix: 44.53.01.5f.45.50.52.4f.53.49.4d.41
  Running on:  UDPv4:[0.0.0.0]:11811

### Server shut down ###

对比 2.2 节：不带 -i 时 GUID 前缀是随机值（01.0f.2b.9f.6e.28.b5.14.00.00.00.00），每次重启都变；带 -i 1 后固定为 44.53.01.5f.45.50.52.4f.53.49.4d.41——这串字节实际是 ASCII "DS" + \x01 + "_EPROSIMA"（44 53=DS，5f 45 50 52 4f 53 49 4d 41=_EPROSIMA），服务端 ID 就编码在第 3 字节。客户端 XML 里的 RemoteServerPrefix 必须填这个值，所以生产部署一定带 -i 固定它，否则服务端一重启全集群失联。

2.4 -b：备份服务端

裸 -b（不带 -i）实测直接被拒：

2026-10-23 19:02:06.105 [CLI Error] Specifying a GUID prefix is mandatory for BACKUP Discovery Servers. Use the -i argument. -> Function fastdds_discovery_server

退出码 1。这是硬约束而非警告：备份依赖固定 GUID 在磁盘上建立状态文件。正确用法：

timeout 6 fastdds discovery -b -i 2 -p 11812

实测回显（注意横幅从 Server started 变成了 Backup Server started）：

#### Backup Server started ####
  GUID prefix: 44.53.02.5f.45.50.52.4f.53.49.4d.41
  Running on:  UDPv4:[0.0.0.0]:11812

### Server shut down ###

退出后在当前工作目录生成 5 个状态文件（文件名内嵌 GUID，实测清单）：

server-44-53-02-5f-45-50-52-4f-53-49-4d-41.json
server-44-53-02-5f-45-50-52-4f-53-49-4d-41_queue.json
server-44-53-02-5f-45-50-52-4f-53-49-4d-41_reader.db
server-44-53-02-5f-45-50-52-4f-53-49-4d-41_writer.db
server-44-53-02-5f-45-50-52-4f-53-49-4d-41_writer.db-journal

两个 .db 是 SQLite 持久化文件，-journal 是其回滚日志。这组文件就是崩溃恢复的载体——服务端重启后按 GUID 前缀找到它们续接状态。

2.5 -t / -q：TCP 监听

timeout 8 fastdds discovery -t 127.0.0.1 -q 42100

实测回显：

#### Server started ####
  GUID prefix: 01.0f.2b.9f.9a.28.32.f0.00.00.00.00
  Running on:  TCPv4:[127.0.0.1]:42100-42100

### Server shut down ###

TCP 模式默认端口 42100。-e 示例 10 特意提示：TCP 传输端口不能共享，同一服务端监听多个网卡地址时要分别指定不同 -q。

2.6 -x：从 XML 启动服务端与参数覆盖优先级

XML 侧只需一个 discoveryProtocol=SERVER 的 participant profile（完整结构见《Fast-DDS 3.6.2 配置参数详解》），关键片段：

<participant profile_name="ds_server_xml" is_default_profile="true">
    <rtps>
        <builtin>
            <discovery_config>
                <discoveryProtocol>SERVER</discoveryProtocol>
            </discovery_config>
            <metatrafficUnicastLocatorList>
                <locator>
                    <udpv4>
                        <address>127.0.0.1</address>
                        <port>11813</port>
                    </udpv4>
                </locator>
            </metatrafficUnicastLocatorList>
        </builtin>
    </rtps>
</participant>

timeout 6 fastdds discovery -x ds_server_xml.xml

实测回显——服务端按 XML 里声明的 11813 端口监听：

#### Server started ####
  GUID prefix: 01.0f.2b.9f.b8.29.8d.35.00.00.00.00
  Running on:  UDPv4:[127.0.0.1]:11813

### Server shut down ###

再叠加 -p 11814 验证帮助原文「the XML argument will be overriden」的覆盖方向：

$ timeout 6 fastdds discovery -x ds_server_xml.xml -p 11814
#### Server started ####
  GUID prefix: 01.0f.2b.9f.c9.29.92.3d.00.00.00.00
  Running on:  UDPv4:[0.0.0.0]:11814

实测结论：-p 覆盖了 XML 的端口，连 XML 里的监听地址一并回到默认 0.0.0.0（CLI 参数生成自己的监听配置）。混用 -x 与 CLI 参数时，以「CLI 完全接管对应项」理解最准确。

-x 还支持 profile_name@file.xml 语法从多 profile 文件中点名取一个（-e 示例 8 原文），未点名的多 profile 文件默认取 is_default_profile="true" 那个。

2.7 非法参数回显

$ fastdds discovery -z
2026-10-23 19:02:14.171 [CLI Error] Unknown option: z -> Function initial_options_fail

eProsima Discovery Server auxiliary generator tool. Version 1.0.1
It can be used for both deploying Servers and inspecting active ones.

报错后自动跟随帮助文本。

2.8 守护进程子命令：start / stop / list / info

discovery -h 中 Daemon options 一节的子命令实测如下（add/set 用于多服务器互联，单机场景无回显差异，本文未展开）：

list（守护进程未运行）：

$ fastdds discovery list
The Fast DDS daemon is not running. No servers to list.

info：帮助原文已标注未实现，实测确认：

$ fastdds discovery info -d 0
Info mode not implemented yet.

start（启动守护进程并在其下挂服务端）：

$ fastdds discovery start -d 1 "127.0.0.1:11811"
The Fast DDS daemon has been started.
Server for Domain ID [1] started on port 7652

注意两点实测现象：

端口与 -p 无关：start 的地址参数（IP:port）指的是要对接的远端服务端，本地域服务端的端口由守护进程按 RTPS 规则自动分配——实测 domain 1 → 7652、domain 2 → 7902、domain 3 → 8152，严格按 250 递增；
守护进程是单进程多域：第二次 start -d 2 不再报 started，而是：

The Fast DDS daemon is already running.
Server for Domain ID [2] started on port 7902

list（运行中）：

$ fastdds discovery list
### Servers running ###
- Server:
    Domain ID: 1
    Port: 7652
    Address: 0.0.0.0

#######################

stop：stop -d 1 只停指定域（Discovery Server for Domain ID '1' stopped.，守护进程保持存活）；不带 -d 全部停止且守护进程退出：

$ fastdds discovery stop
Discovery Server for Domain ID '2' stopped.
Discovery Server for Domain ID '3' stopped.
The Fast DDS daemon has been stopped.

停止后再 list 回到 The Fast DDS daemon is not running. No servers to list.

2.9 端到端闭环：CLI 服务端 + XML 客户端

用 2.3 节的固定 GUID 服务端，两个 hello_world 参与者全部以 CLIENT 模式经它撮合（客户端 XML 结构，GUID 取自服务端输出的 GUID prefix 行）：

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com">
    <participant profile_name="ds_client" is_default_profile="true">
        <rtps>
            <builtin>
                <discovery_config>
                    <discoveryProtocol>CLIENT</discoveryProtocol>
                    <discoveryServersList>
                        <RemoteServerPrefix>44.53.01.5f.45.50.52.4f.53.49.4d.41</RemoteServerPrefix>
                        <metatrafficUnicastLocatorList>
                            <locator>
                                <udpv4>
                                    <address>127.0.0.1</address>
                                    <port>11811</port>
                                </udpv4>
                            </locator>
                        </metatrafficUnicastLocatorList>
                    </discoveryServersList>
                </discovery_config>
            </builtin>
        </rtps>
    </participant>
</profiles>

fastdds discovery -i 1 -p 11811 &          # 服务端
FASTDDS_DEFAULT_PROFILES_FILE=ds_client.xml hello_world subscriber &
FASTDDS_DEFAULT_PROFILES_FILE=ds_client.xml hello_world publisher -s 6

实测结果（订阅端匹配并收满 6 条）：

[e2e] sub_matched=1 recv=6 | pub_matched=1 sent=6

💡 ROS 2 用户注意：-e 示例 2 原文提到的 ROS_DISCOVERY_SERVER=127.0.0.1:14520 环境变量是 ROS 2 侧的对接入口（格式 IP:port，多服务端用分号分隔，序号即服务端 ID），与本文 -i 的固定 GUID 是同一套编号体系。

三、fastdds shm：共享内存维护

Fast DDS 默认传输含 SHM，参与者进程被 SIGKILL 或崩溃时来不及清理 /dev/shm 下的段文件，日积月累会污染共享内存。fastdds shm 就是清理入口，只有一个子命令：

$ fastdds shm -h
usage: fastdds shm [<shm-command>]

    shm-commands:

    	clean     clean SHM zombie files

options:
  -h, --help   show this help message and exit
  -f, --force  Force the clean of data sharing segments

3.1 清理实测

先构造僵尸段（订阅端跑起来后 kill -9，/dev/shm 残留 5 个文件）：

fastdds_2ff6bf8f5d5b23f4
fastdds_2ff6bf8f5d5b23f4_el
fastdds_port7411
fastdds_port7411_el
sem.fastdds_port7411_mutex

fastdds shm clean

实测回显：

shm.clean:
0 ports in use
0 segments in use
1 zombie ports cleaned
1 zombie segments cleaned

执行后 /dev/shm 中 fastdds_* 文件数归 0（实测 after clean: 0 files）。

fastdds shm clean -f

实测回显（此时已无垃圾，-f 额外扫描 data sharing 段并打印清单）：

Datasharing segments: []
shm.clean:
0 ports in use
0 segments in use
0 zombie ports cleaned
0 zombie segments cleaned
0 datasharing segments cleaned

⚠️ 使用建议：shm clean 只清「属主已死」的僵尸文件，不会动活进程的段，可以放心在运行中的机器上执行；-f 会强制清理 data sharing 段，存在误伤正在使用的数据共享段的风险，仅在确认无读写方时使用。段文件名中的 port7411 对应内置元数据通信端口，_el 后缀文件与主段成对出现。

四、fastdds xml：配置校验

$ fastdds xml -h
usage: fastdds xml [<xml-command>]

Script for the validation of the XML files that define the profiles of the DDS
entities in Fast DDS.

positional arguments:
  validate              validate XML profiles files using an XSD schema

options:
  -h, --help            show this help message and exit
  -d, --debug           print debug info (default: False)
  -x XSD_FILE, --xsd-file XSD_FILE
                        Fast DDS XSD schema for validation (default: None)

用法 fastdds xml validate <file.xml>，五种输入形态（合法/结构非法/命名空间错误/非 XML 内容/文件缺失）的完整实测回显与退出码，已在《Fast-DDS 3.6.2 配置参数详解》第八章逐条归档，此处不重复。生产建议：任何 XML 配置上线前先过一遍 fastdds xml validate，因为 Fast DDS 加载失败一律静默降级为内置默认配置（同篇 3.3 节）。

五、排障与坑位实录

本篇全部实测过的坑，按「现象 → 实测回显 → 处置」归档：

#	现象	实测回显（关键词）	根因与处置
1	直接执行 `fast-discovery-server-1.0.1` 报错	`error while loading shared libraries: libfastdds.so.3.6: cannot open shared object file`	环境未加载（`LD_LIBRARY_PATH` 为空）。先 `source /root/fastdds_ws/install/setup.bash`，或用会自动定位库的 `fastdds` 包装命令
2	`-b` 启动失败	`[CLI Error] Specifying a GUID prefix is mandatory for BACKUP Discovery Servers. Use the -i argument.`	备份服务端必须固定 GUID；加 `-i <id>`（2.4 节）
3	服务端重启后客户端全部失联	`Running on:` 正常但客户端 `Subscriber unmatched.`	未带 `-i`，GUID 前缀随机化，客户端 `RemoteServerPrefix` 对不上（2.3 节）
4	`discovery info` 无输出可用	`Info mode not implemented yet.`	3.6.2 未实现，排查守护进程状态改用 `list`
5	`start` 后端口不是预期的 11811	`Server for Domain ID [1] started on port 7652`	守护进程按 RTPS 规则自动分配（250 递增）；`start` 的 `IP:port` 参数是对接远端，不是本地监听端口（2.8 节）
6	`-x` 与 CLI 参数同用，端口变了连地址也变了	`Running on: UDPv4:[0.0.0.0]:11814`	CLI 参数完全接管对应项并回到默认地址；要么纯 XML 要么纯 CLI，避免混用（2.6 节）
7	脚本里判断 CLI 失败失效	`fastdds foo` 输出 `Invalid command: 'foo'. Use 'fastdds -h' for help.` 但退出码 0	顶层命令错误退出码为 0（实测），`fastdds xml` 无参数时为 1——脚本判断必须看输出，不能只看 `$?`
8	重复启动默认端口服务端失败	`-e` 示例 1 原文：`Only one server can use default values per machine.`	每机每端口只能一个服务端；多实例用不同 `-p` + 不同 `-i`
9	异常退出后 `/dev/shm` 残留	`fastdds_2ff6bf8f5d5b23f4` 等 5 个文件	SIGKILL 跳过清理钩子；`fastdds shm clean`（3.1 节）

六、小结

fastdds CLI 的使用心法一句话：discovery 管发现拓扑，shm 管内存卫生，xml 管配置质量。要点回顾：

生产部署服务端三件套：-i 固定 GUID、-p 明确端口、-b 备份（且 -b 强制要求 -i）；
客户端通过 RemoteServerPrefix + metatrafficUnicastLocatorList 对接服务端，实测闭环收发正常；
守护进程单进程多域、端口按 250 递增自动分配，list/stop 管理其生命周期；
XML 加载失败静默降级 + CLI 参数覆盖 XML 配置，是两类最隐蔽的行为差异；
fastdds shm clean 是唯一需要定期执行的维护命令。

配套阅读：《Fast-DDS 3.6.2 介绍与选型指南》（选型与架构）、《Ubuntu 22.04 安装 Fast-DDS 3.6.2 指南》（编译安装与 systemd 托管）、《Fast-DDS 3.6.2 配置参数详解》（XML Profiles 全参数实测）；同为 C++ 消息中间件、以命令行工具 bmqbrkrmgr/bmqtool 驱动运维的 Bloomberg BlazingMQ 命令对照可读《BlazingMQ 0.95.20 常用 CLI 命令详解》。