Skip to documentation
OrbitMeshDocs
Browse documentation
Docs/Runtime and Control

RUNTIME AND CONTROL

Control Plane

Control Plane 是 OrbitMesh 的大脑。
View source

1. 定位

Control Plane 是 OrbitMesh 的大脑。

它负责把用户意图转换成 Desired State，并通过 Edge Runtime 让每个 Node 的实际状态收敛到期望状态。

Control Plane 不直接运行 sing-box、EasyTier、Traefik、frp 等 runtime，也不在用户流量路径上。

2. 领域模型

Control Plane 以 Capability Model 为准。

核心对象：

  • Tenant。
  • User。
  • Membership。
  • Node。
  • EdgeRuntime。
  • CapabilityBinding。
  • RuntimeBinding。
  • Endpoint。
  • Domain。
  • Certificate。
  • Subscription。
  • TrafficPolicy。
  • DesiredState。
  • RuntimeConfiguration。
  • UsageSample。
  • UsageRollup。
  • QuotaPolicy。

Gateway 不再作为所有主机的通用资源名。Gateway 只表示 Gateway Capability。

3. 服务边界

Auth Service
Tenant Service
Node Service
Capability Service
Runtime Service
Endpoint Service
Deployment Service
Subscription Service
Traffic Policy Service
Configuration Compiler
Certificate Service
Usage Service
Quota Service
Health Service
Audit Service

4. Node Service

Node Service 负责：

  • Node 创建和查询。
  • Edge Runtime 注册结果落库。
  • Node reachability。
  • Node 状态机。
  • Node source type。
  • Node labels and attributes。

Node source type:

  • byoh。
  • recommended_vps。
  • managed。

Reachability:

  • reported address。
  • public address。
  • private address。
  • mesh address。
  • inbound reachable。
  • outbound reachable。
  • relay required。

不应该通过字段名假设地址一定是公网 IP。

5. Capability Service

Capability Service 负责：

  • 在 Node 上启用 capability role。
  • 管理 CapabilityBinding 生命周期。
  • 聚合 readiness。
  • 生成 capability-level desired state input。

MVP roles:

  • traffic.entry。
  • traffic.exit。

Future roles:

  • traffic.relay。
  • mesh.node。
  • gateway.http。
  • tunnel.endpoint。

6. Runtime Service

Runtime Service 负责：

  • Runtime Catalog。
  • Runtime Install Profile。
  • Runtime Parameter Schema。
  • Runtime Binding。
  • Runtime status。

Runtime Binding 指向具体 runtime plugin，例如：

  • sing-box。
  • xray。
  • easytier。
  • traefik。
  • frp。

Runtime Catalog 必须声明：

  • runtime kind。
  • display name。
  • primary capability。
  • supported capabilities。
  • supported roles。
  • parameter schema。
  • install profile。
  • adapter status。

7. Endpoint Service

Endpoint Service 负责：

  • Endpoint 分配。
  • domain binding。
  • DNS reconciliation。
  • certificate binding。
  • readiness。
  • endpoint-to-capability binding。
  • endpoint-to-runtime binding。

Endpoint examples:

  • Traffic Entry Trojan endpoint。
  • Gateway HTTPS endpoint。
  • Tunnel public endpoint。
  • Mesh private address。

Endpoint 是证书、域名、端口、协议和 readiness 的主要归属点。

8. Deployment Service

Deployment Service 负责：

  • enrollment token。
  • install command。
  • initial capability intent。
  • registration transaction。
  • deployment result。

Deployment token 可以携带：

  • tenant_id。
  • created_by。
  • node source type。
  • initial capability intent。
  • expiration。
  • repeat registration policy。

9. Subscription Service

Subscription Service 负责：

  • subscription 创建。
  • token hash。
  • rotate。
  • revoke。
  • soft delete。
  • output format。
  • endpoint selection。
  • usage and quota status。

Subscription 是 Traffic 客户端配置分发的产品资源。

不要在新代码中继续使用 Client Configuration 作为领域模型名称。

10. Traffic Policy Service

Traffic Policy Service 负责：

  • policy scope。
  • selector。
  • Traffic Exit selection。
  • preview。
  • compile impact。
  • soft delete。

Traffic policy 输出应引用 traffic.exit capability binding 或 endpoint candidate，而不是 legacy egress gateway。

11. Certificate Service

Certificate Service 负责：

  • system domain。
  • tenant custom domain。
  • ownership validation。
  • ACME order。
  • DNS challenge。
  • certificate storage reference。
  • renewal。
  • certificate status。

Certificate 不直接等同于 endpoint。Endpoint 通过 TLS binding 引用 certificate。

12. Desired State

Desired State 是 Control Plane 下发给 Edge Runtime 的平台级状态。

Desired State references:

  • node_id。
  • capability_bindings。
  • runtime_bindings。
  • endpoints。
  • certificates。
  • secrets。
  • runtime configurations。

Desired State 不应该直接暴露 runtime-specific implementation details 给 Console。

13. API Direction

Target resource APIs:

/api/v1/nodes
/api/v1/nodes/{id}
/api/v1/nodes/{id}/capability-bindings
/api/v1/nodes/{id}/runtime-bindings
/api/v1/endpoints
/api/v1/subscriptions
/api/v1/traffic-policies
/api/v1/runtime-catalog
/api/v1/deployment-tokens
/api/v1/edge-runtime/register
/api/v1/edge-runtime/heartbeat
/api/v1/edge-runtime/desired-state

Old API resources should be removed during breaking alignment instead of kept as compatibility aliases.

14. Migration Policy

The model migration is breaking.

Rules:

  • SQL migrates old data into target tables and columns.
  • Program code does not perform historical backfill.
  • Ent schema represents only the target structure.
  • Proto and OpenAPI can break during this development phase.
  • Console routes should be renamed directly.
  • Old enum values should be replaced by capability roles.

15. MVP Acceptance

  • Node enrollment works.
  • Edge Runtime identity is stable.
  • Node heartbeat updates Node and RuntimeBinding status.
  • traffic.entry and traffic.exit can be enabled on Nodes.
  • sing-box RuntimeBinding can be installed and applied.
  • Traffic subscription can be generated from ready endpoints.
  • Traffic policy can recompile affected desired state.
  • Usage reports include tenant, user, subscription, node, capability role, runtime binding, runtime, and direction.
OrbitMesh DocumentationContent follows the repository's main branch.