Fast-DDS 3.6.2 配置参数详解

目标：逐项实测 eProsima Fast DDS 3.6.2 的 XML Profiles 配置体系——dds/profiles 双根形态与命名空间陷阱、FASTDDS_DEFAULT_PROFILES_FILE 环境变量与 DEFAULT_FASTDDS_PROFILES.xml 默认文件的加载顺序与优先级、transport/participant/QoS 参数的生效验证（/dev/shm 段文件与收发匹配双探针）、<log> 日志配置的版本陷阱，以及 fastdds xml validate 校验器的全部错误形态。全部命令与回显均在 Ubuntu 22.04 实机实测通过，组件定位与架构背景见本专栏 《Fast-DDS 3.6.2 介绍与选型指南》，编译安装步骤见 《Ubuntu 22.04 安装 Fast-DDS 3.6.2 指南》；命令行工具用法见本专栏《Fast-DDS 3.6.2 常用 CLI 命令详解》。

一、实验环境与验证方法

本文实测环境与 《Ubuntu 22.04 安装 Fast-DDS 3.6.2 指南》 同机同源码工作区，读者按相同版本操作可直接复现：

每个 shell 均先加载环境：

source /root/fastdds_ws/install/setup.bash
HW=/root/fastdds_ws/build/fastdds/examples/cpp/hello_world/hello_world

💡 验证方法说明：XML 配置是否「真正生效」不能只看进程不报错。本文采用三种探针交叉验证——

探针	原理	能证明什么
收发匹配	hello_world 订阅端输出 Subscriber matched. 与逐条 Message: 'Hello world' with index: 'N' RECEIVED	domainId、QoS 等影响发现与匹配的配置是否生效
/dev/shm 段文件	默认内置传输含 SHM（共享内存），参与者启动会在 /dev/shm 创建 fastdds_* 段与信号量	传输层配置（如关闭内置传输）是否生效
fastdds xml validate	按 fastdds_profiles.xsd 规范校验	文件结构合法性、错误位置与原因

收发探针的标准输出形态（实拍）：

Subscriber running. Please press Ctrl+C to stop the Subscriber at any time.
Subscriber matched.
Message: 'Hello world' with index: '1' RECEIVED
Message: 'Hello world' with index: '2' RECEIVED
...
Subscriber unmatched.

二、XML Profiles 体系总览：根元素与命名空间

XML Profiles 是 Fast DDS 的免编译配置体系：不改一行代码，即可覆盖参与者（Participant）、数据读写者（DataWriter/DataReader）、传输层、日志等几乎所有默认行为。与「配置文件驱动」的消息队列（如 BlazingMQ 的 bmqbrkrcfg.json，见 《BlazingMQ 0.95.20 配置参数详解》）不同，Fast DDS 的配置载体是带规范 XSD 的 XML。

2.1 四种根元素

fastdds_profiles.xsd 顶层共定义四个元素（XSD 原文节选）：

<xs:element name="dds">
    ├ <profiles>  minOccurs=0 maxOccurs=1
    ├ <types>     minOccurs=0 maxOccurs=1
    └ <log>       minOccurs=0 maxOccurs=1
<xs:element name="profiles" type="profilesType"/>
<xs:element name="types"    type="typesType"/>
<xs:element name="log"      type="logType"/>

即配置文件可以写成两种常见形态：

• profiles 根：只放 profile 定义（本文大部分示例的形态）；
• dds 根：外层 <dds> 包裹，内部 <profiles>、<types>（动态类型）、<log>（日志）三节可共存。

2.2 实测：双根形态等价有效，命名空间是第一陷阱

对同一段传输配置分别按两种根形态写文件，fastdds xml validate 实测双双通过：

$ fastdds xml validate /root/xmltest/udp_only.xml
Valid XML file: /root/xmltest/udp_only.xml          # profiles 根
$ fastdds xml validate /root/xmltest/dds_udp_only.xml
Valid XML file: /root/xmltest/dds_udp_only.xml      # dds 根

两者运行时行为也等价（/dev/shm 探针均不再创建 SHM 段，见第四章）。

⚠️ 命名空间陷阱：根元素命名空间必须是 xmlns="http://www.eprosima.com"。实测把命名空间误写成 XSD 自身的 http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles（网上不少博客这么抄），校验直接失败：

$ fastdds xml validate /root/xmltest/dds_wrongns.xml
NOT valid XML file: /root/xmltest/dds_wrongns.xml
failed validating <Element '{http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles}dds' ...>

Reason: '{http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles}dds' is not an element of the schema
...
Path: /{http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles}dds

EXIT=1

2.3 profiles 根下合法子元素清单

<profiles> 下能放什么，不必靠猜——把非法子元素塞进去，校验器的报错会把完整合法清单吐出来（实测 <log> 放在 profiles 根下时的报错）：

Reason: Unexpected child with tag '{http://www.eprosima.com}log' at position 1.
Tag ('{http://www.eprosima.com}domainparticipant_factory' |
     '{http://www.eprosima.com}participant' |
     '{http://www.eprosima.com}data_writer' |
     '{http://www.eprosima.com}data_reader' |
     '{http://www.eprosima.com}transport_descriptors' |
     '{http://www.eprosima.com}topic' |
     '{http://www.eprosima.com}replier' |
     '{http://www.eprosima.com}requester') expected.

即 <profiles> 合法子元素共八类：domainparticipant_factory、participant、data_writer、data_reader、transport_descriptors、topic、replier、requester。<log> 不在其中——它只能放在 <dds> 根下（第七章实测）。

三、配置加载机制：环境变量与默认文件（重点实测）

3.1 官方加载链

Fast DDS 进程启动时自动加载的 XML 共三级，顺序在源码 XMLProfileManager::loadDefaultXMLFile() 中写死（src/cpp/xmlparser/XMLProfileManager.cpp）：

1. 内置默认 profiles：编译进库的默认配置；
2. 环境变量 FASTDDS_DEFAULT_PROFILES_FILE 指向的文件（先加载）；
3. 当前工作目录下的 DEFAULT_FASTDDS_PROFILES.xml（后加载）；若环境变量 SKIP_DEFAULT_XML_FILE=1 则跳过第 3 步。

两个关键常量定义在 src/cpp/xmlparser/XMLParserCommon.cpp：

const char* DEFAULT_FASTDDS_ENV_VARIABLE = "FASTDDS_DEFAULT_PROFILES_FILE";
const char* DEFAULT_FASTDDS_PROFILES     = "DEFAULT_FASTDDS_PROFILES.xml";
const char* SKIP_DEFAULT_XML_FILE        = "SKIP_DEFAULT_XML_FILE";

⚠️ 优先级结论（实测）：环境变量文件先加载、cwd 默认文件后加载；当两个文件都含 is_default_profile="true" 的同类型 profile 时，后加载的 cwd 默认文件覆盖先加载的环境变量文件。多文件加载按顺序覆盖、is_default_profile="true" 才会被自动选用，是理解本节所有实测现象的钥匙。

3.2 实测矩阵：六种加载场景

实验方法统一：订阅端带被测配置启动，发布端不带（固定 domain 0）。若订阅端配置把 domainId 改成 55，则两者无法匹配（sub_matched=0）；能匹配（sub_matched=1 且有 RECEIVED 计数）说明配置未生效。

其中 5c 的实测回显（发布端分别以 domain 51 / 52 探测）：

[t5c] sub_matched=1 recv=6
      pub51_matched=1 sent51=6
      pub52_matched=0 sent52=0

订阅端最终落在 domain 51——正是 cwd DEFAULT_FASTDDS_PROFILES.xml 里的值，证明它覆盖了环境变量指向的 domain 52。

3.3 两个静默降级陷阱的原始回显

环境变量指向不存在的文件：

2026-10-23 18:51:43.768 [XMLPARSER Error] realpath failed No such file or directory -> Function loadDefaultXMLFile
Subscriber running. Please press Ctrl+C to stop the Subscriber at any time.

环境变量指向非法 XML（内容不是 XML 的 bad.xml）：

2026-10-23 18:51:48.413 [XMLPARSER Error] Error opening '/root/xmltest/bad.xml' -> Function loadXML
2026-10-23 18:51:48.413 [XMLPARSER Error] Error parsing '/root/xmltest/bad.xml' -> Function loadXMLFile
Subscriber running. Please press Ctrl+C to stop the Subscriber at any time.

⚠️ 排障要点：XML 加载失败不会让进程退出，应用带着内置默认配置继续运行。生产环境变更配置文件后若「看起来没生效」，第一时间在标准错误里搜 XMLPARSER Error；更稳妥的做法是上线前用 fastdds xml validate 预检（第八章）。

四、transport_descriptors：传输层配置与生效验证

4.1 传输描述符结构与常用参数

Fast DDS 内置五种传输（UDPv4/UDPv6/TCPv4/TCPv6/SHM），默认组合为 UDPv4 + SHM。自定义传输分两步：在 <profiles> 根下声明 <transport_descriptors>，再在 participant profile 的 <rtps> 里引用。transport_descriptor 常用子元素（来自 XSD）：

完整字段清单以 fastdds_profiles.xsd 为准（grep -A30 'name="transportDescriptorType"' 可查）。

4.2 实测样例：纯 UDP（禁用内置 SHM）

udp_only.xml（profiles 根形态）：

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com">
    <transport_descriptors>
        <transport_descriptor>
            <transport_id>udp_only</transport_id>
            <type>UDPv4</type>
        </transport_descriptor>
    </transport_descriptors>
    <participant profile_name="udp_only_participant" is_default_profile="true">
        <rtps>
            <userTransports>
                <transport_id>udp_only</transport_id>
            </userTransports>
            <useBuiltinTransports>false</useBuiltinTransports>
        </rtps>
    </participant>
</profiles>

dds 根形态只需在文件外加 <dds> 包裹层、内层缩进一档，其余完全相同。

两个 participant 侧参数配合使用：

• userTransports：引用上面声明的传输（按 transport_id）；
• useBuiltinTransports：false 表示彻底弃用内置传输组合，只用 userTransports 列表——只声明不引用、或只引用不关内置，都会出现「两套传输并存」的意外行为。

4.3 生效验证：/dev/shm 段文件探针

默认传输组合含 SHM，参与者启动会在 /dev/shm 创建段文件。实测对比（订阅端运行中查看）：

基线场景的文件清单实拍：

shm files: 5
fastdds_e19cdfc507edb353
fastdds_e19cdfc507edb353_el
fastdds_port7411
fastdds_port7411_el
sem.fastdds_port7411_mutex

⚠️ 两个实操注意：

1. 探针必须在进程运行中查看。timeout 6 hello_world subscriber 这种前台跑完再看 /dev/shm 的方式永远数到 0——进程优雅退出时会把段清理掉，笔者第一次就是这么测出「基线 0 个文件」的假象的。
2. kill -9 会留僵尸段。实测 kill -9 掉订阅端后 5 个文件全部残留，需要 fastdds shm clean 清理（见本专栏《Fast-DDS 3.6.2 常用 CLI 命令详解》）。

4.4 participant profile 常用参数

本文实测过的 participant 配置项：

更多项（发现协议、初始对端、监听地址、内建元数据端口等）在 participantProfileType 下，结构同上，完整清单见 XSD。

五、participant profile：domainId 与 is_default_profile

5.1 domainId 隔离实测

domain55.xml：

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com">
    <participant profile_name="domain55_participant" is_default_profile="true">
        <domainId>55</domainId>
        <rtps>
            <name>domain55_participant</name>
        </rtps>
    </participant>
</profiles>

三组对照实测（-s 6 表示发布端发 6 条即退出）：

5.2 is_default_profile 的语义

4c 是理解该属性的关键实验：同一个 XML 文件，仅把 is_default_profile 改为 false，加载后配置完全不被应用（参与者留在默认 domain 0），进程亦无任何报错。

💡 规则总结：只有 is_default_profile="true" 的 profile 才会被自动应用到实体上；非默认 profile 必须在代码里按 profile_name 显式选用，或通过 URI 的 @ 片段选择（fastdds discovery -x 的帮助原文提到：多 profile 文件默认取 is_default_profile="true" 的那个，除非用 @ 指定）。同一文件里声明了 profile 却忘了 is_default_profile="true"，是 XML 配置「不生效」的最常见原因之一。

六、data_writer / data_reader profile 与 QoS

<data_writer>/<data_reader> profile 控制发布/订阅侧的 QoS 与资源限制。一组官方示例同款的实测文件（历史上正是 Fast RTPS 的经典示例配置）：

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com" >
    <data_writer profile_name="hello_world_datawriter_profile" is_default_profile="true">
        <qos>
            <durability>
                <kind>TRANSIENT_LOCAL</kind>
            </durability>
            <reliability>
                <kind>RELIABLE</kind>
            </reliability>
        </qos>
        <topic>
            <historyQos>
                <kind>KEEP_LAST</kind>
                <depth>100</depth>
            </historyQos>
            <resourceLimitsQos>
                <max_samples>100</max_samples>
                <max_instances>1</max_instances>
                <max_samples_per_instance>100</max_samples_per_instance>
            </resourceLimitsQos>
        </topic>
        <times>
            <heartbeat_period>
                <sec>0</sec>
                <nanosec>100000000</nanosec>
            </heartbeat_period>
        </times>
    </data_writer>

    <data_reader profile_name="hello_world_datareader_profile" is_default_profile="true">
        <qos>
            <durability>
                <kind>TRANSIENT_LOCAL</kind>
            </durability>
            <reliability>
                <kind>RELIABLE</kind>
            </reliability>
        </qos>
        <topic>
            <historyQos>
                <kind>KEEP_LAST</kind>
                <depth>100</depth>
            </historyQos>
            <resourceLimitsQos>
                <max_samples>100</max_samples>
                <max_instances>1</max_instances>
                <max_samples_per_instance>100</max_samples_per_instance>
            </resourceLimitsQos>
        </topic>
    </data_reader>
</profiles>

结构分三节：

• <qos>：DDS 标准 QoS（durability、reliability 等）；
• <topic>：主题级历史深度（historyQos）与资源限额（resourceLimitsQos，预分配内存即由此而来）；
• <times>：仅 writer 有，RTPS 协议定时器（如 heartbeat 周期）。

实测：该文件 fastdds xml validate 通过；与 5.1 的 domain 55 文件叠加使用后（4b 场景），发布/订阅正常完成 6 条收发——QoS profile 的加载不干扰发现与匹配链路。

💡 QoS 匹配提醒：durability/reliability 属于「请求-提供」协商的 QoS，读写者两侧不兼容时会静默不匹配（无报错、无数据）。排查这类「进程都活着但没数据」的问题，先用第五章 domain 探针法确认是否匹配，再对齐两侧 QoS。

七、log 配置的实测陷阱（3.6.2 专版）

Fast DDS 的日志配置在 3.x 经历过接口重构，网上流传的 2.x 写法在 3.6.2 上全部翻车，本章三陷阱均为实拍。

7.1 3.6.2 的 <log> 合法结构

XSD 中 logType 的完整定义（原文）：

<xs:complexType name="logType">
    <xs:sequence minOccurs="1" maxOccurs="unbounded">
        <xs:choice minOccurs="1">
            <xs:element name="use_default" type="booleanCaps" .../>
            <xs:element name="consumer" type="logConsumerType" .../>
            <xs:element name="thread_settings" type="threadSettingsType" .../>
        </xs:choice>
    </xs:sequence>
</xs:complexType>

即顶层只认三个子标签：use_default、consumer、thread_settings。consumer 的 class 枚举值为 StdoutConsumer、StdoutErrConsumer、FileConsumer，可配 property 属性键值。没有 verbosity、filename、stderr 等 2.x 时代的顶层子标签。

7.2 陷阱一：<log> 写进 profiles 根 → 级联解析失败

<log> 只能放在 <dds> 根下。误放进 <profiles> 根（哪怕 fastdds xml validate 已经能报错拦截），运行时的表现是同文件后续 profile 一起解析失败：

2026-10-23 18:51:53.517 [XMLPARSER Error] Not expected tag: 'log' -> Function parseProfiles
2026-10-23 18:51:53.517 [XMLPARSER Error] Error parsing profile's tag log -> Function parseProfiles
2026-10-23 18:51:53.517 [XMLPARSER Error] Error parsing profile's tag participant -> Function parseProfiles

注意第三行：跟在非法 <log> 后面的正常 <participant> 也被殃及——不是「忽略非法段落继续」，而是整个 profiles 解析中断。

7.3 陷阱二：旧文档的 <verbosity> 顶层子标签不被 3.6.2 接受

按 2.x 文档写 <dds><log><verbosity>LOG_INFO</verbosity></log></dds>，运行时实测：

2026-10-23 14:25:49.646 [XMLPARSER Error] Not expected tag: 'verbosity' -> Function parseLogConfig
2026-10-23 14:25:49.646 [XMLPARSER Error] Error parsing '/root/xmltest/log_info3.xml' -> Function loadXMLFile

7.4 陷阱三：FASTDDS_LOG_VERBOSITY 环境变量实测无效

社区教程常见的 FASTDDS_LOG_VERBOSITY=LOG_DEBUG 启动方式，实测对 3.6.2 完全无效（与不设该变量时输出逐字相同，均为 3 行；故意设非法值 NOPE 也无任何报错）：

$ FASTDDS_LOG_VERBOSITY=LOG_DEBUG hello_world subscriber
Subscriber running. Please press Ctrl+C to stop the Subscriber at any time.

SIGTERM received, stopping Subscriber execution.

源码佐证：3.6.2 日志实现（src/cpp/fastdds/log/）中不存在任何 getenv 调用，verbosity 只能通过代码 API Log::SetVerbosity(Log::Kind)（include/fastdds/dds/log/Log.hpp）调整。

7.5 正确姿势：dds 根 + consumer 配置

合法且运行时无错的日志配置写法（实测 fastdds xml validate 通过、启动无 XMLPARSER Error）：

<?xml version="1.0" encoding="UTF-8" ?>
<dds xmlns="http://www.eprosima.com">
    <log>
        <use_default>FALSE</use_default>
        <consumer>
            <class>StdoutErrConsumer</class>
        </consumer>
    </log>
    <profiles>
        <participant profile_name="p0" is_default_profile="true">
            <domainId>0</domainId>
        </participant>
    </profiles>
</dds>

八、fastdds xml validate：XML 校验器

写完配置文件先过校验器，是规避 3.3/7.x 全部「静默降级」陷阱的最省事手段。用法与五种实测回显：

fastdds xml validate <file.xml> [-x <custom.xsd>]

-x 可指定自定义 XSD（默认使用安装目录 share/fastdds/fastdds_profiles.xsd）；-d 输出调试信息。该命令的完整上下文（所属的 fastdds CLI 工具族）见本专栏《Fast-DDS 3.6.2 常用 CLI 命令详解》。

九、排障速查表

本章汇总本篇全部实测过的故障形态，按「现象 → 实测回显 → 根因 → 处置」组织：

十、小结

3.6.2 的 XML Profiles 体系一句话总结：结构以 XSD 为唯一权威，生效以探针实测为准。本篇要点回顾：

1. 根元素四选一（dds/profiles/types/log），常用前两种；命名空间必须 http://www.eprosima.com；
2. 加载链三级：内置默认 → FASTDDS_DEFAULT_PROFILES_FILE → cwd DEFAULT_FASTDDS_PROFILES.xml，后者覆盖前者的默认 profile，SKIP_DEFAULT_XML_FILE=1 可跳过；
3. XML 加载失败一律静默降级，上线前必须 fastdds xml validate；
4. transport 配置的生效可用 /dev/shm 段文件探针客观验证，注意在进程运行中查看；
5. <log> 配置在 3.6.2 与 2.x 完全不兼容，老教程照抄必翻车。

配套阅读：组件选型背景 《Fast-DDS 3.6.2 介绍与选型指南》、安装与环境准备 《Ubuntu 22.04 安装 Fast-DDS 3.6.2 指南》、fastdds discovery/fastdds shm 等命令行工具逐参数实测见本专栏《Fast-DDS 3.6.2 常用 CLI 命令详解》；同为消息中间件、以 JSON 文件驱动配置的 Bloomberg BlazingMQ 配置对照可读 《BlazingMQ 0.95.20 配置参数详解》。