主题命名

目录

主题层次结构设计

主题命名是消息系统的 API。设计良好的层次结构可以实现高效的路由、过滤和访问控制,同时让开发者易于理解。


设计原则

原则理由
层次化支持在任意层级进行通配符订阅
可预测开发者无需查询即可构造主题
环境感知将生产环境与预发布/开发环境分开
可过滤可订阅单个载具、一个分组或整个机队
可扩展无需重构即可添加新的消息类型

核心主题模式

所有机队主题都遵循以下模式:

fleet.<env>.veh.<vid>.<category>.<type>
段描述示例
fleet根命名空间始终为 “fleet”
<env>环境prod、staging、dev
veh资源类型载具(未来:gcs 用于地面控制)
<vid>载具 IDVID-001、drone-alpha-7
<category>消息类别state、evt、cmd、cmdack
<type>具体类型position、battery、takeoff

消息类别

状态:fleet.<env>.veh.<vid>.state.*

载具的当前状态,持续发布:

主题描述频率
state.position纬度/经度/高度、速度10 Hz
state.attitude横滚/俯仰/偏航10 Hz
state.battery电压、电流、剩余电量1 Hz
state.mode飞行模式(AUTO、MANUAL、RTL)变化时
state.health系统健康摘要1 Hz

发布示例:

subject := fmt.Sprintf("fleet.prod.veh.%s.state.position", vehicleID)
nc.Publish(subject, positionJSON)

事件:fleet.<env>.veh.<vid>.evt.*

离散事件,在发生时发布:

主题描述
evt.armed载具已解锁
evt.disarmed载具已上锁
evt.takeoff已开始起飞
evt.landed着陆完成
evt.waypoint已到达航点
evt.failsafe已触发失效保护
evt.geofence越出地理围栏
evt.battery.low低电量警告

事件是状态转换,而非连续数据。它们是持久化的——存储在 JetStream 中用于审计追踪。

命令:fleet.<env>.veh.<vid>.cmd.*

发送给载具的指令:

主题描述
cmd.arm解锁电机
cmd.disarm上锁电机
cmd.takeoff开始起飞
cmd.land开始着陆
cmd.rtl返航
cmd.goto导航至指定位置
cmd.mission.upload上传任务
cmd.mission.start开始任务
cmd.param.set设置参数

命令向下游流动,从机队管理系统发往载具。

命令确认:fleet.<env>.veh.<vid>.cmdack.*

对命令的响应:

主题描述
cmdack.arm解锁命令结果
cmdack.takeoff起飞命令结果
cmdack.gotoGoto 命令结果

确认消息负载包括:

{
  "cmd_id": "cmd-123456",
  "status": "accepted|rejected|completed|failed",
  "error": "optional error message",
  "timestamp": "2024-01-15T10:30:00Z"
}

通配符订阅

NATS 通配符支持灵活的订阅方式:

通配符含义示例
*单个令牌fleet.prod.veh.*.state.position
>一个或多个令牌fleet.prod.veh.VID-001.>

常见订阅模式

模式用例
fleet.prod.veh.*.state.position所有载具的位置
fleet.prod.veh.VID-001.>单个载具的所有消息
fleet.prod.veh.*.evt.>所有载具的所有事件
fleet.prod.veh.*.state.battery所有电池状态
fleet.*.veh.VID-001.>单个载具在所有环境中的消息

KV 存储:数字孪生影子

JetStream KV 存储维护期望状态和上报状态:

主题模式(KV)

fleet/<env>/veh/<vid>/desired
fleet/<env>/veh/<vid>/reported

注意:KV 使用 / 分隔符(存储桶路径),而发布/订阅使用 . 分隔符。

期望状态

机队管理系统希望载具执行的操作:

{
  "mode": "AUTO",
  "mission_id": "mission-456",
  "geofence_enabled": true,
  "max_altitude": 120,
  "home_position": {
    "lat": 37.7749,
    "lon": -122.4194
  }
}

上报状态

载具实际上报的内容:

{
  "mode": "AUTO",
  "mission_id": "mission-456",
  "mission_progress": 0.45,
  "geofence_enabled": true,
  "armed": true,
  "in_flight": true,
  "battery_remaining": 0.72
}

影子协调

载具网关持续执行以下操作:

  1. 从 KV 读取期望状态
  2. 与载具的实际状态进行比较
  3. 发出命令,使实际状态与期望状态保持一致
  4. 更新上报状态

这实现了声明式机队管理——设置期望状态,让载具自行收敛。


访问控制

NATS 授权将用户映射到其被允许的主题:

# Vehicle can publish its own state/events
publish: fleet.prod.veh.VID-001.state.>
publish: fleet.prod.veh.VID-001.evt.>
publish: fleet.prod.veh.VID-001.cmdack.>

# Vehicle can subscribe to commands for itself
subscribe: fleet.prod.veh.VID-001.cmd.>

# Vehicle can read/write its own shadow
kv: fleet/prod/veh/VID-001/*
# Fleet operator can subscribe to all state/events
subscribe: fleet.prod.veh.*.state.>
subscribe: fleet.prod.veh.*.evt.>
subscribe: fleet.prod.veh.*.cmdack.>

# Fleet operator can publish commands
publish: fleet.prod.veh.*.cmd.>

# Fleet operator can manage shadows
kv: fleet/prod/veh/*/desired

这确保了载具无法冒充其他载具,也无法发布未经授权的命令。

有关授权模型的详细介绍,包括第三方授权和凭证管理,请参阅 授权与授予。


主题设计权衡

为什么不使用扁平主题?

像 vehicle-001-position 这样的扁平主题不支持:

  • 通配符订阅
  • 层次化访问控制
  • 逻辑分组

为什么不使用更深的层次结构?

像 fleet.prod.region.us-west.site.warehouse-a.veh.VID-001.state.position 这样的主题:

  • 更难以通过编程方式构造
  • 通配符会变得复杂
  • 变更会波及整个系统

四级层次结构在灵活性与简洁性之间取得了平衡。


消息格式

所有消息都使用结构一致的 JSON:

{
  "vid": "VID-001",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "seq": 12345,
  "data": {
    // message-specific payload
  }
}
字段描述
vid载具 ID(与主题重复,但对消费者很有用)
timestamp毫秒精度的 ISO 8601 时间戳
seq用于排序的单调递增序列号
data特定于消息的负载

总结

类别主题模式方向
状态fleet.<env>.veh.<vid>.state.<type>载具 → 中心
事件fleet.<env>.veh.<vid>.evt.<type>载具 → 中心
命令fleet.<env>.veh.<vid>.cmd.<type>中心 → 载具
确认fleet.<env>.veh.<vid>.cmdack.<type>载具 → 中心
期望fleet/<env>/veh/<vid>/desired(KV)中心 → 载具
上报fleet/<env>/veh/<vid>/reported(KV)载具 → 中心

下一步

流配置 →