源码导读
CubeSandbox 是多语言、多组件仓库。读源码时不要从目录树第一层挨个看；更好的方式是沿着“一个沙箱如何被创建”这条链路读。
仓库结构速查
| 目录 | 语言 | 主要内容 |
|---|---|---|
CubeAPI/ | Rust | E2B 兼容 REST API、OpenAPI、鉴权、请求转发。 |
CubeMaster/ | Go | 调度、生命周期、模板中心、HTTP/gRPC 服务。 |
Cubelet/ | Go | 节点本地管理、containerd 集成、网络插件、运行时控制。 |
CubeShim/ | Rust | containerd Shim v2、MicroVM 资源准备和启动恢复。 |
hypervisor/ | Rust | CubeHypervisor / VMM、KVM、设备模型。 |
cubecow/ | Rust | CoW 存储、reflink 快照、克隆。 |
network-agent/ | Go | 网络配置下发、CubeVS 对接。 |
CubeEgress/ | OpenResty/Lua | L7 出网代理、规则、注入、审计。 |
CubeProxy/ | OpenResty/Go | 反向代理、沙箱路由、自动暂停/恢复 sidecar。 |
web/ | React/TypeScript | WebUI 控制台。 |
docs/ | VitePress | 官方文档站。 |
examples/ | Python/Go 等 | SDK 示例和端到端场景。 |
推荐阅读链路
1. 从 API 模型开始
先看：
openapi.ymlCubeAPI/src/models/CubeAPI/src/handlers/CubeAPI/src/routes.rs
目标：理解对外 API 形态、请求参数、响应字段和错误处理。
2. 看创建沙箱如何进入 CubeMaster
继续看：
CubeAPI/src/cubemaster/CubeMaster/pkg/service/sandbox/CubeMaster/pkg/scheduler/CubeMaster/pkg/lifecycle/
目标：理解调度、timeout、lifecycle、模板身份和路由元数据。
3. 看节点如何启动沙箱
继续看：
Cubelet/services/Cubelet/plugins/cube/CubeShim/shim/src/hypervisor/vmm/src/
目标：理解 containerd Shim v2、rootfs、内存快照、VMM 启动和恢复。
4. 看存储和模板
继续看：
CubeMaster/pkg/templatecenter/CubeMaster/pkg/templatecenter/image/cubecow/src/docs/zh/guide/templates.md
目标：理解 OCI 镜像到模板、artifact、CoW 快照、跨节点分发。
5. 看网络和安全
继续看：
network-agent/internal/Cubelet/network/CubeEgress/lua/CubeProxy/sidecar/
目标：理解网络策略下发、eBPF map、L7 规则、自动暂停/恢复协调。
读代码时抓住的关键对象
| 对象 | 为什么重要 |
|---|---|
sandbox_id | 路由、日志、生命周期、Redis key 都围绕它展开。 |
template_id | 连接模板中心、artifact、调度和启动路径。 |
lifecycle | 自动暂停/恢复的跨组件契约。 |
CubeNetworkConfig | 网络策略从 API 到节点的核心载体。 |
artifact | 模板文件和运行时文件的分发单元。 |
| Redis key | 跨进程共享状态的事实来源之一。 |
如何验证修改
不同模块测试方式不同，先优先跑你改动附近的测试：
bash
# Go 模块示例
cd CubeMaster && go test ./...
cd Cubelet && go test ./...
cd network-agent && go test ./...
# Rust 模块示例
cd CubeAPI && cargo test
cd CubeShim && cargo test
cd cubecow && cargo test
# 文档站
cd docs && npm run docs:build仓库较大，完整测试可能耗时很久；贡献前至少说明你跑过哪些测试、哪些没跑以及原因。
贡献注意事项
- 先读 CONTRIBUTING_zh.md。
- 双语文档通常需要同时更新英文和中文。
- 不要在 AI 生成提交中添加
Signed-off-by，DCO 只能由人类提交者认证。 - 如果由 AI 辅助生成 commit 或 PR 描述，需要按仓库
AGENTS.md里的规则加入Assisted-by或Autonomously-by标签。 - 修改跨组件契约时，优先补 parity test 或 schema test，避免控制面和 sidecar 漂移。
下一步
回到 学习中心，按你的角色继续深入部署、网络、模板或示例。