cmvr-es/cmvr-es/config

Config 模块开发指南

config/ 保存 CMVR-ES 的默认运行配置。配置格式是 Protobuf TextFormat，Schema 位于 ../../protos/cmvr/config/。

返回项目总览。

配置树

cmvr_es.pb.txt
├── logger/logger.pb.txt
├── manager/device_manager.pb.txt
│   └── devices/<category>/*.pb.txt
└── manager/task_manager.pb.txt
    └── tasks/<task>/*.pb.txt

入口文件：

• cmvr_es.pb.txt
• manager/device_manager.pb.txt
• manager/task_manager.pb.txt

路径规则

无参数运行时，程序读取：

<cmvr_es 可执行文件所在目录>/config/cmvr_es.pb.txt

安装后的 output/bin/cmvr_es 因此会读取 output/bin/config/cmvr_es.pb.txt；直接运行 build/cmvr_es 则会查找 build/config/cmvr_es.pb.txt，不会自动跳到安装目录。传入显式根配置时：

./output/bin/cmvr_es /etc/cmvr-es/cmvr_es.pb.txt

设备、任务和证书等相对配置路径均以根配置文件所在目录解析。模型等资源通过 ConfigHelper::resolveResourceFile() 在配置根及父目录中查找；生产部署仍建议使用明确绝对路径。

日志配置中的相对 directory 以可执行文件目录解析，不以配置根解析。

新增设备配置

增加同类设备后端时：

1. 在 protos/cmvr/config/<category>_config/ 增加后端 message；
2. 在类别设备 message 的 oneof backend 中增加字段；
3. 在 devices/<category>/ 的 .pb.txt 中增加实例；
4. 实例外层 id 必须唯一；
5. 在 manager/device_manager.pb.txt 增加相同 id、正确 type 和配置路径；
6. 开发默认保持 enable: false；
7. 同步类别 factory 和 CMake；
8. 在无硬件环境验证关闭状态，在真机环境单独开启。

设备集合中的 ID 与 DeviceManager 条目 ID 不一致时，工厂会拒绝创建。

新增任务配置

1. 在 protos/cmvr/config/ 增加任务配置和 root message；
2. 在 tasks/<task_name>/ 增加默认 .pb.txt；
3. 在 task_manager.pb.txt 增加唯一任务 ID；
4. 配置正确的 TaskType 和 TaskRunMode；
5. 周期任务设置大于零的 control_period_s；
6. 服务任务使用 TASK_RUN_MODE_BLOCKING_SERVICE；
7. 默认关闭依赖网络、证书或硬件的新任务。

任务实现流程见 ../task/README.md。

默认值与校验

• 不依赖 proto3 数值零值表达危险的生产默认值；
• timeout、队列大小、帧大小和周期应在代码中校验；
• 新增 loader 对不认识的 enum 和未设置的 oneof 必须明确失败；当前个别历史路径仍有退化默认行为，不应复制；
• 设备端口、坐标系、速度和单位写入注释；
• enable 应由 manager 层控制，后端内部的 enable 字段不能替代 manager 开关；
• QUIC 需要 TaskManager 与 QuicEdgeConfig.enable 同时开启；
• QUIC 零媒体轨道是合法配置。

gRPC 相机实时流

tasks/grpc_server_task/grpc_server_task.pb.txt 中的两个低延迟参数仅作用于 gRPC RGB 编码流，不改变机械臂、AGV 等控制 RPC：

• camera_stream_max_pending_frames：单个客户端允许的待发送帧数，超过后清空该 客户端积压；默认 2；
• camera_stream_max_frame_age_ms：从设备回调进入边缘系统起计算的最大帧龄， 超过后不再发送；默认 250 ms。

两个字段填 0 或旧配置未包含字段时使用默认值。丢弃 H.264/H.265 帧后服务会请求 IDR 并等待关键帧恢复。如果现场采集、编码本身稳定超过 250 ms，应根据日志中的 age_ms 调高帧龄阈值，而不是增大环形队列。

新二进制可以读取未包含这两个字段的旧配置；旧二进制不能解析包含新字段的 TextFormat。部署时必须同步更新程序与配置，不能只把新版 grpc_server_task.pb.txt 复制给旧的 output/bin/cmvr_es。

配置验证

构建后可以用 protoc --encode 对单个 TextFormat 文件做语法和字段验证。例如：

output/bin/protoc \
  -I protos \
  --encode=cmvr.config.QuicEdgeRootConfig \
  protos/cmvr/config/quic_edge_config/quic_edge_config.proto \
  < cmvr-es/config/tasks/quic_edge_task/quic_edge_task.pb.txt \
  > /tmp/quic_edge_config.pb

该命令只验证 Proto Text 解析，不验证文件、设备、证书、网络和跨字段语义。最终仍需运行组件测试和进程烟雾测试。

生产配置

cmake --install 会重建 output/bin/config/。生产配置应复制到 /etc/cmvr-es/ 等外部目录并显式传入。

• 不提交真实设备密码、token、私钥和生产地址；
• 证书与私钥放在独立 certs/，使用最小读取权限；
• 为不同站点维护独立配置根，不在运行时修改仓库样例；
• 发布前检查所有 enable、IP、端口和设备 ID；
• 变更配置 Schema 时同步 Proto 兼容性文档和平台生成代码。

提交检查

• TextFormat 可以被对应 root message 解析
• ID、类别和引用路径完全一致
• 新硬件和新网络任务默认关闭
• 参数单位、范围和安全默认值明确
• 没有生产凭据
• 安装覆盖不会丢失现场配置
• 无设备启动仍然成功