Skip to documentation
OrbitMeshDocs
Browse documentation
Docs/Runtime and Control

RUNTIME AND CONTROL

Edge Runtime

Edge Runtime 是运行在每个 OrbitMesh Node 上的本地运行时。
View source

1. 定位

Edge Runtime 是运行在每个 OrbitMesh Node 上的本地运行时。

它负责将控制平面的 Desired State 落地为本机 Runtime 配置，并持续上报 Node、Runtime Binding、Capability Binding 和 Endpoint 状态。

Edge Runtime 不承载产品业务逻辑。它只负责让本机实际状态收敛到 Control Plane 下发的期望状态。

2. 设计目标

  • 不依赖控制平面 SSH。
  • Node 主动连接控制平面。
  • 本地保留 last known good config。
  • 支持配置回滚。
  • 支持 runtime plugin / adapter。
  • 支持 capability-aware desired state。
  • 支持健康探针和指标上报。
  • 支持自动升级。

3. 组件

orbitmeshd
  Bootstrap Manager
  Identity Manager
  Control Plane Client
  Desired State Sync
  Reconciler
  Runtime Manager
  Runtime Adapter Registry
  Capability Status Reporter
  Endpoint Materializer
  Health Probe
  Metrics Collector
  Usage Collector
  Secret Store
  Certificate Store
  Upgrade Manager

Local user operations are handled by the orbitmesh CLI. The CLI talks to orbitmeshd through a local Unix socket and should not directly mutate daemon-owned identity or runtime state.

4. 本地文件结构

/etc/orbitmesh/
  edge-runtime.yaml
  node.json
  secrets.json

/var/lib/orbitmesh/edge-runtime/
  identity.json
  identity.key
  desired-state.json
  desired-state.previous.json
  runtime-configuration.json
  runtime-configuration.last-good.json
  apply-result.json

/var/lib/orbitmesh/certs/
  <certificate-id>/
    cert.pem
    key.pem

/var/log/orbitmesh/
  edge-runtime.log

Update metadata:

/var/lib/orbitmesh/edge-runtime/install.json
/opt/orbitmesh/versions/
/opt/orbitmesh/current

Runtime-owned files are managed by each runtime adapter, for example:

/etc/sing-box/config.json

5. Edge Runtime 配置

edge-runtime.yaml:

control_plane_url: https://api.orbitmesh.dev
node_id: node_xxx
edge_runtime_id: er_xxx
sync_interval: 30s
heartbeat_interval: 15s
log_level: info

Runtime selection must come from desired state runtime bindings, not from a single top-level runtime field.

Device identity:

/var/lib/orbitmesh/edge-runtime/identity.json
/var/lib/orbitmesh/edge-runtime/identity.key

6. 注册流程

installer receives enrollment token
  |
Edge Runtime starts in bootstrap mode
  |
POST /api/v1/edge-runtime/register
  |
receive node_id + edge_runtime_id
  |
write local identity
  |
switch to managed mode

7. 配置同步流程

timer tick
  |
GET /api/v1/edge-runtime/desired-state
  |
compare version/checksum
  |
install or update runtime dependencies
  |
materialize secrets and certificates
  |
render runtime config
  |
validate runtime config
  |
apply or reload runtime
  |
health check
  |
POST /api/v1/edge-runtime/apply-result

8. Runtime Manager

Runtime Manager 负责：

  • 安装 runtime。
  • 启动 runtime。
  • 停止 runtime。
  • reload runtime。
  • 检查 runtime 状态。
  • 管理 runtime 版本。
  • 上报 runtime binding 状态。

MVP runtime:

  • sing-box。

未来 runtime:

  • Xray。
  • EasyTier。
  • Tailscale。
  • NetBird。
  • Traefik。
  • NGINX。
  • frp。

9. Runtime Adapter 接口

Edge Runtime adapter interface:

type RuntimeAdapter interface {
    Name() string
    Install(ctx context.Context, profile RuntimeInstallProfile) error
    Validate(ctx context.Context, manifest RuntimeManifest) error
    Apply(ctx context.Context, manifest RuntimeManifest) error
    Reload(ctx context.Context, binding RuntimeBinding) error
    Stop(ctx context.Context, binding RuntimeBinding) error
    Status(ctx context.Context, binding RuntimeBinding) RuntimeStatus
    Version(ctx context.Context) string
    CollectMetrics(ctx context.Context, binding RuntimeBinding) ([]MetricSample, error)
    CollectUsage(ctx context.Context, binding RuntimeBinding) ([]UsageSample, error)
}

10. 配置回滚

应用新配置前：

  1. 备份当前 config。
  2. 写入 pending config。
  3. validate。
  4. reload runtime。
  5. health check。
  6. 成功则标记 applied。
  7. 失败则恢复 last-good config。

Rollback is per runtime binding.

11. 心跳

Heartbeat should report Node, Edge Runtime, Runtime Binding, and Capability state:

{
  "node_id": "node_xxx",
  "edge_runtime_id": "er_xxx",
  "edge_runtime_version": "0.1.0",
  "runtime_statuses": [
    {
      "runtime_binding_id": "rb_xxx",
      "runtime": "sing-box",
      "runtime_version": "1.x",
      "status": "running"
    }
  ],
  "capability_statuses": [
    {
      "capability_binding_id": "cb_xxx",
      "capability": "traffic",
      "role": "traffic.entry",
      "status": "ready"
    }
  ],
  "uptime_seconds": 3600,
  "cpu_usage": 0.2,
  "memory_usage": 0.5,
  "disk_usage": 0.3
}

12. 安全

  • device private key 仅本地 root 可读。
  • Edge Runtime API 请求使用 Ed25519 签名。
  • 日志不得输出 secret。
  • Desired State 必须校验 checksum。
  • TLS 必须校验服务端证书。

13. MVP 开发任务

当前新增功能暂停，先对齐现有 Traffic MVP。

P0 alignment:

  • orbitmesh up/login/logout/down local CLI。
  • Node enrollment。
  • heartbeat。
  • desired-state pull。
  • sing-box config apply。
  • apply-result。
  • systemd service。
  • runtime binding status。
  • capability binding status。

P1:

  • rollback。
  • metrics。
  • health probe。
  • auto update。

Auto update details are defined in specs/edge-runtime-update.md. The update system must support manual updates, automatic updates, package-manager installs, standalone fallback, and rollback after failed daemon restart.

14. 验收标准

  • 新主机执行安装命令后 Edge Runtime 能注册为 Node。
  • Edge Runtime 重启后能读取本地身份。
  • 控制平面修改 Desired State 后 Edge Runtime 能应用。
  • 错误配置不会覆盖 last-good。
  • 心跳超时能被控制平面识别。
  • sing-box runtime binding 状态能上报。
  • traffic.entry 和 traffic.exit readiness 能上报。
OrbitMesh DocumentationContent follows the repository's main branch.