总体架构

1. 架构目标

OrbitMesh 的架构必须满足：

• 控制面和数据面分离。
• Node 上的 Edge Runtime 主动连接控制面。
• 支持 BYOH。
• 支持多租户。
• 支持策略路由。
• 支持配置版本化和回滚。
• 支持未来替换 Data Plane Runtime。
• 支持从个人版演进到企业版。
• 支持 Traffic、Mesh、Gateway、Tunnel 四大 Capability。

当前架构以 Capability Model 为准。早期 Gateway + ingress/egress + sing-box 模型已经废弃，后续不做兼容抽象。

2. 系统分层

Presentation Layer
  Next.js Console on Cloudflare Pages
  CLI
  Public API

Control Plane
  Go Kratos Monolith
  Auth Service
  Tenant Service
  Node Manager
  Capability Manager
  Runtime Manager
  Endpoint Manager
  Deployment Service
  Traffic Policy Engine
  Configuration Compiler
  Subscription Service
  Health Service
  Metrics Service
  Billing Service

Persistence Layer
  PostgreSQL
  Redis
  Object Storage
  Metrics Store

Edge Runtime
  Go standalone CLI: orbitmesh
  Go standalone daemon: orbitmeshd
  Runtime Manager
  Runtime Adapter
  Health Probe
  Metrics Collector

Data Plane
  Runtime Plugins
  Capability Endpoints

2.1 技术框架选型

MVP 技术路线：

Dashboard Frontend
  Next.js
  Cloudflare Pages
  shadcn/ui

Control Plane Backend
  Go
  Kratos
  PostgreSQL
  Redis

Edge Runtime
  Go standalone binary
  systemd
  sing-box adapter

Data Plane
  sing-box

框架边界：

• Next.js 只负责 Dashboard、官网和用户交互，不承载核心控制平面。
• Kratos 承载 Control Plane API、Edge Runtime API、Desired State、Compiler、Policy、Health、Billing。
• Edge Runtime 使用 Go 单二进制，不引入 Kratos 框架本身。
• sing-box 是 MVP Data Plane Runtime，不是业务模型中心。
• sing-box 只作为 Traffic Runtime Plugin 存在，不是 Gateway、Ingress 或 Egress 本身。

3. 控制流

User
  |
Dashboard / API
  |
Control Plane
  |
Desired State
  |
Edge Runtime Pull
  |
Runtime Apply
  |
Status Report

控制平面生成状态，Edge Runtime 拉取并执行。

4. 用户流量

Client
  |
Traffic Entry Endpoint
  |
Traffic Exit Role
  |
GitHub / Claude / OpenAI / Docker / npm

控制平面不在用户流量路径上。

5. 核心服务

5.1 API Gateway

负责：

• 认证。
• 租户解析。
• 限流。
• 请求追踪。
• 错误格式统一。

5.2 Node Manager

负责：

• Node 注册。
• Edge Runtime 状态。
• Node 元数据。
• Node reachability。
• Node 生命周期。

5.3 Capability Manager

负责：

• Capability Binding。
• Capability Role。
• Node capability enablement。
• Capability readiness。
• Capability lifecycle。

5.4 Runtime Manager

负责：

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

5.5 Endpoint Manager

负责：

• Endpoint 分配。
• 域名。
• DNS。
• 证书绑定。
• Endpoint readiness。

5.6 Deployment Service

负责：

• 部署 token。
• 安装脚本。
• Bootstrap。
• 部署结果。

5.7 Traffic Policy Engine

负责：

• 路由策略。
• 健康感知。
• 成本感知。
• 租户权限。

5.8 Configuration Compiler

负责：

• Desired State -> Runtime Config。
• Runtime 能力适配。
• 配置版本。
• checksum。

5.9 Health Service

负责：

• Node 健康。
• Capability 健康。
• Runtime 健康。
• 目标服务探测。
• 路由评分。

6. Runtime 架构

MVP 使用 sing-box 作为 Traffic Runtime Plugin：

• traffic.entry：Trojan + TLS。
• traffic.entry 到 traffic.exit：Shadowsocks 2022。
• traffic.exit outbound：direct。

未来支持：

• Xray。
• EasyTier。
• Tailscale。
• NetBird。
• WireGuard。
• Traefik。
• NGINX。
• Envoy。
• frp。
• 自研 Runtime Plugin。

7. 数据存储

PostgreSQL：

• 租户。
• 用户。
• Node。
• Edge Runtime。
• Capability Binding。
• Runtime Binding。
• Endpoint。
• 策略。
• Desired State。
• Subscription。
• 计费。
• 审计。

Redis：

• Session。
• Rate limit。
• 缓存。
• 分布式锁。

Metrics Store：

• Node 指标。
• Runtime 指标。
• Capability 指标。
• 路由指标。
• 健康探测。

8. 高可用设计

MVP 不要求完整 HA，但必须具备：

• Edge Runtime 保留 last known good config。
• 控制面短暂不可用不影响已有流量。
• 配置应用失败可回滚。
• Node 离线可被标记。
• Capability readiness 可被降级。

商业化阶段：

• API 多副本。
• PostgreSQL 备份。
• Redis 高可用。
• 多区域控制面。

9. 架构验收

架构实现完成后应满足：

• 能 enroll Node。
• 能在 Node 上启用 traffic.entry 和 traffic.exit Capability Binding。
• 能为 Node 绑定 sing-box Runtime Binding。
• 能生成 Desired State。
• 能编译 sing-box 配置。
• Edge Runtime 能应用配置。
• Node、Runtime 和 Capability 状态能回传。
• 路由策略能影响配置输出。
• 控制面停止后，已应用配置的 Traffic path 仍按 last known good config 工作。