Skip to documentation
OrbitMeshDocs
Browse documentation
Docs/Platform Systems

PLATFORM SYSTEMS

Traffic Policy Engine

Traffic Policy Engine 将用户或系统定义的连接意图转化为可执行的 Traffic 路由策略。
View source

1. 定位

Traffic Policy Engine 将用户或系统定义的连接意图转化为可执行的 Traffic 路由策略。

它不直接生成 runtime 配置，也不直接选择“Gateway”。它选择 Traffic Capability 下的候选角色和 endpoint。

2. 核心概念

TrafficPolicy

租户、用户、订阅或 Node 作用域下的 Traffic 策略。

MVP 阶段实际支持两类 scope：

  • tenant：参与 Runtime Desired State 编译，可生成 Entry Runtime 到 Traffic Path 的 runtime path。
  • subscription：参与订阅配置生成，并且只会编译进绑定了该 subscription credential 的 Entry Runtime。

subscription scope 不能被解释成租户全局 runtime path。它必须受 subscription_endpoints 和 runtime credential 约束：只有订阅实际绑定的入口节点会收到对应 path，Runtime Adapter 必须把 path 约束到 subscription principal，例如 sing-box 使用 auth_user。

后续可以把当前隐式关系提升为显式 Subscription Access Link / Route Binding 模型，把 subscription_id、entry_endpoint_id、exit_endpoint_id、principal_key 和 policy rule 持久化到独立资源中。

TrafficRule

具体路由规则，由三部分组成：

  • match_json：匹配目标地址、端口、网络和协议。
  • target_json：选择命中的 Traffic Path，最短路径为 Entry -> Exit，多跳路径为 Entry -> Relay* -> Exit。
  • failover_json：描述不可用时的降级策略。

Match

流量匹配条件。MVP 支持：

  • domain suffix。
  • destination port。
  • network，例如 tcp、udp。
  • protocol，例如 https、tls。

后续可以扩展 exact domain、keyword、regex、CIDR、SNI、HTTP path。

Target

目标选择条件。MVP 使用 traffic.path 表达路径：

{
  "type": "traffic.path",
  "segments": [
    {
      "role": "traffic.relay",
      "node_ids": ["node_relay_hk"]
    },
    {
      "role": "traffic.exit",
      "providers": ["tencent"],
      "regions": ["tencent-hk"]
    }
  ]
}

规则：

  • segments 至少包含一个 traffic.exit。
  • traffic.exit 必须是最后一个 segment。
  • traffic.relay 是可选的，可以有 0 个或多个。
  • 每个 segment 可通过 node_ids、provider/providers、region/regions、node_type/node_types 选择候选 Node。

MVP 支持：

  • selected Traffic Relay / Exit node IDs。
  • provider。
  • region。
  • capability role traffic.relay / traffic.exit。

Target 选择的是 Traffic Capability 的角色和候选 Node/RuntimeBinding。最终可连接地址必须来自 Endpoint 资源，而不是从 Node 地址字段临时推断。

Resolved Endpoint

Traffic Policy Engine 在生成 route plan 时解析出用于 runtime 间转发的 endpoint。

当前 Traffic Relay / Exit 解析条件：

  • role = traffic.relay 或 role = traffic.exit。
  • purpose = inter_node_proxy。
  • protocol = mixed。
  • network = tcp。

候选 endpoint 按状态、优先级、来源和 scope 排序。user 来源优先于 runtime_reported，runtime_reported 优先于 system。mesh 和 private scope 可以优先于 public，因为 OrbitMesh 后续会支持基于 Mesh 的节点互联。

Failover

主 exit 不可用时的备选顺序。

3. 策略模型

name: developer-default
scope:
  type: tenant
rules:
  - name: github
    match_json:
      domains:
        suffix:
          - github.com
          - githubusercontent.com
      ports: [443]
      networks: [tcp]
      protocols: [https]
    target_json:
      type: traffic.path
      segments:
        - role: traffic.exit
          providers: [tencent]
          regions: [tencent-hk]
    failover_json:
      strategy: ordered
      fallback: direct

4. 决策流程

input destination
  |
match route rule
  |
load candidate traffic.relay / traffic.exit bindings
  |
filter by tenant entitlement
  |
filter by quota enforcement
  |
filter by health
  |
score by latency/cost/provider
  |
choose primary path
  |
generate runtime path plan

5. 出口评分

评分可由以下因素组成：

score = health_score * 0.4
      + latency_score * 0.3
      + cost_score * 0.2
      + provider_score * 0.1

MVP 可以简化为：

  1. 过滤 unhealthy。
  2. 按配置优先级选择。
  3. 没有健康数据时使用默认 exit。

6. 与 Health Engine 集成

Traffic Policy Engine 依赖 Health Engine 提供：

  • service-level health。
  • Node health。
  • RuntimeBinding health。
  • CapabilityBinding health。
  • Provider 评分。
  • Region 评分。

7. 与 Compiler 集成

Traffic Policy Engine 输出 runtime-agnostic route plan。

Compiler 当前将 tenant scope policy 编译进所有可用 Entry Runtime。subscription scope policy 会先检查当前 Entry Runtime 是否持有该 subscription 的 active credential；只有匹配时才生成 runtime path，并在 path plan 中写入 principal constraint。

subscription 单链路强制路由路径为：

Subscription
  -> SubscriptionEndpoint
  -> Entry Runtime ClientCredential
  -> Principal Credential
  -> Selected Relay Endpoint(s)
  -> Selected Exit Endpoint
  -> Runtime Adapter per-principal path

当前 sing-box adapter 将 principal constraint 编译为 route rule 的 auth_user 字段。

Example:

{
  "paths": [
    {
      "rule_name": "github",
      "mode": "static",
      "match": {
        "domain_suffixes": ["github.com", "githubusercontent.com"],
        "ports": [443],
        "networks": ["tcp"],
        "protocols": ["https"]
      },
      "segments": [
        {
          "index": 0,
          "role": "traffic.relay",
          "target_node_id": "node_relay_hk",
          "resolved_endpoint": {
            "id": "endpoint_relay_hk",
            "address": "10.10.0.7",
            "port": 18080,
            "protocol": "mixed",
            "network": "tcp",
            "address_scope": "mesh"
          }
        },
        {
          "index": 1,
          "role": "traffic.exit",
          "target_node_id": "node_exit_hk",
          "resolved_endpoint": {
            "id": "endpoint_exit_hk",
            "address": "10.10.0.8",
            "port": 18080,
            "protocol": "mixed",
            "network": "tcp",
            "address_scope": "mesh"
          }
        }
      ]
    }
  ]
}

Compiler 再将其转为 runtime-specific config。

8. 数据模型

traffic_policies:

  • id。
  • tenant_id。
  • scope_type。
  • scope_id。
  • name。
  • description。
  • status。
  • priority。
  • created_at。
  • updated_at。
  • deleted_at。

traffic_rules:

  • id。
  • policy_id。
  • name。
  • match_json。
  • target_json。
  • failover_json。
  • priority。
  • enabled。
  • created_at。
  • updated_at。

9. API

GET  /api/v1/traffic-policies
POST /api/v1/traffic-policies
GET  /api/v1/traffic-policies/{id}
PUT  /api/v1/traffic-policies/{id}
POST /api/v1/traffic-policies/{id}/simulate
POST /api/v1/traffic-policies/preview
DELETE /api/v1/traffic-policies/{id}

simulate 请求：

{
  "destination_host": "github.com",
  "destination_port": 443,
  "network": "tcp",
  "protocol": "https"
}

响应：

{
  "matched": true,
  "matched_rule": "github",
  "selected_exit_node_ids": ["node_exit_hk"],
  "reason": "matched"
}

10. MVP

P0:

  • 静态 domain suffix/port/network/protocol 规则。
  • 默认 Traffic Exit。
  • failover 策略对象。
  • 编译到 sing-box route。
  • preview affected runtime bindings。
OrbitMesh DocumentationContent follows the repository's main branch.