Cube Sandbox

简体中文

English

简体中文

English

Appearance

源码对象索引：模板、沙箱、节点、快照、端口 ​

读源码时最常遇到的问题不是"这段代码做了什么"，而是"这个对象到底存在哪个文件里"。

这份索引帮你快速定位 CubeSandbox 中最核心的源码对象。

1. 对象关系总览 ​

2. 核心对象速查表 ​

2.1 模板相关 ​

对象类型所在模块关键文件说明
CreateCubeSandboxReq请求结构体CubeMasterpkg/service/sandbox/types/创建沙箱的完整请求
TemplateDefinition持久化对象CubeMasterpkg/templatecenter/store.go模板定义，保存在 DB 中
NormalizeRequest()函数CubeMasterpkg/templatecenter/store.go将原始请求规范化为模板语义
RootFS Artifact文件产物CubeMasterpkg/templatecenter/template_image.go从 OCI 镜像导出的 rootfs
AppSnapshot状态对象CubeMasterpkg/templatecenter/cache.go模板的运行快照信息
LocalRunTemplate节点对象Cubeletplugins/cube/节点本地的运行模板

2.2 沙箱相关 ​

对象类型所在模块关键文件说明
SandboxAPI 响应CubeAPIsrc/models/mod.rs对外暴露的沙箱对象
SandboxDetailAPI 响应CubeAPIsrc/models/mod.rs沙箱详情（含资源信息）
NewSandboxAPI 请求CubeAPIsrc/models/mod.rs创建沙箱的外部请求体
RunCubeSandboxRequestgRPC 请求CubeMasterapi/services/cubebox/v1/发给 Cubelet 的创建请求
RunCubeSandboxResponsegRPC 响应CubeMasterapi/services/cubebox/v1/Cubelet 返回的创建结果
createSandboxContext内部上下文CubeMasterpkg/service/sandbox/sandbox_run.go创建事务的完整状态
SandboxProxyMap路由对象CubeMasterpkg/base/types/sandboxID → hostIP:port 映射

2.3 节点相关 ​

对象类型所在模块关键文件说明
Node节点对象CubeMasterpkg/base/node/节点元数据（IP、资源、标签）
SelectorCtx调度上下文CubeMasterpkg/scheduler/selctx/调度器使用的上下文
ReqRes资源需求CubeMasterpkg/scheduler/selctx/CPU / 内存 / 磁盘需求
NodeSelector亲和性CubeMasterpkg/scheduler/affinity/节点选择条件

2.4 网络相关 ​

对象类型所在模块关键文件说明
CubeVSContext网络上下文CubeAPIsrc/cubemaster/mod.rsCubeVS 网络配置
ExposedPort端口映射CubeMasterpkg/service/sandbox/exposed_port_endpoint.go沙箱对外暴露端口
TAP网络设备network-agentinternal/service/TAP 设备管理
SessionNAT 会话CubeVSCubeNet/src/session.hNAT session map 条目

2.5 运行时相关 ​

对象类型所在模块关键文件说明
Sandbox (agent)guest 对象agentsrc/sandbox.rsguest 内沙箱状态
Container容器对象CubeShimshim/src/container/Shim 管理的容器
Task任务对象CubeMasterpkg/task/异步任务（创建/销毁/恢复）

3. 按模块查找 ​

CubeAPI（Rust） ​

CubeAPI/src/
├── main.rs              # CLI 参数、server 启动
├── routes.rs            # 路由注册：build_router() → e2b + cubeapi
├── state.rs             # AppState: rate_limiter, http_client, services, logger, config
├── config.rs            # ServerConfig
├── constants.rs         # 常量定义
├── handlers/
│   ├── sandboxes.rs     # create / list / get / kill / pause / resume / connect
│   ├── templates.rs     # create / list / get / rebuild / delete / update
│   ├── cluster.rs       # cluster_overview / list_nodes / get_node
│   ├── health.rs        # health check
│   ├── store.rs         # store meta / refresh
│   └── config.rs        # get config
├── services/
│   └── sandboxes.rs     # SandboxService: 字段映射 + CubeMaster 调用
├── cubemaster/
│   └── mod.rs           # CubeMasterClient: HTTP 客户端封装
├── middleware/
│   ├── auth.rs          # unified_auth: Bearer / API-Key 鉴权
│   └── rate_limit.rs    # governor token bucket 限流
├── error/
│   └── mod.rs           # AppError 枚举 → HTTP status 映射
└── models/
    └── mod.rs           # Sandbox / SandboxDetail / NewSandbox 等

CubeMaster（Go） ​

CubeMaster/
├── cmd/cubemaster/
│   ├── main.go          # 进程入口
│   └── app/main.go      # App.Run() → coreInit() → server.New()
├── pkg/
│   ├── server/server.go # gorilla/mux HTTP server + 路由注册
│   ├── service/
│   │   ├── httpservice/cube/sandbox_create.go  # 创建 handler
│   │   └── sandbox/sandbox_run.go              # CreateSandbox + createSandboxContext
│   ├── scheduler/
│   │   ├── init.go      # InitScheduler()
│   │   ├── schedule.go  # Select() 五阶段
│   │   └── selctx/      # SelectorCtx
│   ├── selector/
│   │   ├── prefilter/   # 预过滤
│   │   ├── filter/      # CPU / MEM / Disk / template_locality
│   │   ├── score/       # 打分
│   │   ├── postscore/   # 后处理
│   │   └── backofffilter/ # 降级选择
│   ├── templatecenter/  # 模板中心：store / cache / image
│   ├── localcache/      # 节点本地缓存 + Redis 路由表
│   ├── instancecache/   # 实例缓存
│   ├── nodemeta/        # 节点元数据
│   ├── task/            # 异步任务系统
│   └── cubelet/         # Cubelet gRPC 客户端
└── api/services/cubebox/v1/  # gRPC proto 定义

Cubelet（Go） ​

Cubelet/
├── cmd/                 # 进程入口
├── services/cubebox/    # 沙箱生命周期：create / destroy / update
├── plugins/
│   ├── workflow/        # 工作流引擎
│   ├── cube/            # 容器/MicroVM 创建
│   ├── network/         # 网络准备
│   ├── snapshots/       # 快照恢复
│   ├── mount/           # 存储挂载
│   └── metadata/        # 元数据管理
├── internal/            # 内部工具
└── api/                 # 节点 API 定义

4. 快速查找技巧 ​

找某个 API 的实现：

  1. 先在 CubeAPI/src/routes.rs 找路由注册
  2. 再去对应的 handlers/*.rs 找 handler
  3. handler 调用 services/*.rs 中的 service 方法
  4. service 通过 cubemaster/mod.rs 中的 client 调用 CubeMaster

找某个控制面逻辑：

  1. 先在 CubeMaster/pkg/server/server.go 的 registerHandlers() 找路由
  2. 再去 pkg/service/httpservice/ 找 handler
  3. handler 调用 pkg/service/sandbox/ 中的核心逻辑

找某个调度相关的代码：

  1. CubeMaster/pkg/scheduler/schedule.go — Select() 入口
  2. CubeMaster/pkg/selector/ — 各阶段 selector 实现
  3. CubeMaster/pkg/scheduler/selctx/ — 调度上下文

延伸阅读 ​