# sandbox-node

**Repository Path**: secretpad/sandbox-node

## Basic Information

- **Project Name**: sandbox-node
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-10
- **Last Updated**: 2025-12-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sandbox Node - 燕云隐私计算平台沙箱节点

[![Go Version](https://img.shields.io/badge/Go-1.21+-blue.svg)](https://golang.org)
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)

## 项目简介

Sandbox Node 是燕云隐私计算平台的沙箱节点服务，负责在数据使用方提供安全、隔离的计算环境。基于 Kata Containers / TEE 提供硬件级隔离，确保数据"可用不可见"。

### 核心特性

- **强安全隔离**：基于 Kata Containers / TEE 的硬件级隔离
- **数据主权**：数据提供方掌控密钥，沙箱内仅运行时解密
- **全链路审计**：从任务发起到结果归档的每一步均可追溯
- **多阶段开发**：支持调试→自测→生产的完整研发流程
- **证书体系**：自签发CA，动态生成沙箱证书
- **工件管理**：支持代码版本化和回滚机制

## 快速开始

### 环境要求

- Go 1.21+
- Kubernetes 1.29+
- protoc 3.20+
- Docker 20.10+

### 安装依赖

```bash
make init
```

### 构建

```bash
# 编译所有程序
make build

# 仅编译 sandbox-agent
make build-agent

# 仅编译 terminal-proxy
make build-terminal
```

### 运行

```bash
# 运行 sandbox-agent
make run-agent

# 运行 terminal-proxy
make run-terminal
```

## 项目结构

```
sandbox-node/
├── cmd/                    # 可执行程序入口
│   ├── agent/             # Sandbox Agent 主程序
│   └── terminal-proxy/    # Terminal Proxy 独立程序
├── internal/              # 私有应用代码
│   ├── agent/            # Agent 核心逻辑
│   ├── lifecycle/        # 沙箱生命周期管理
│   ├── artifact/         # 工件管理
│   ├── data/             # 数据管理
│   ├── terminal/         # Terminal 代理
│   ├── cert/             # 证书管理
│   └── api/              # API 服务
├── pkg/                   # 公共库
│   ├── logger/           # 日志模块
│   ├── config/           # 配置模块
│   ├── errors/           # 错误处理
│   ├── metrics/          # 监控指标
│   ├── k8sclient/        # K8s 客户端
│   ├── minioclient/      # MinIO 客户端
│   ├── crypto/           # 加密工具
│   └── utils/            # 通用工具
├── api/proto/             # Protobuf 定义
├── configs/               # 配置文件
├── deployments/           # 部署文件
│   ├── kubernetes/       # K8s 部署
│   └── docker/           # Docker 配置
└── scripts/               # 脚本工具
```

## 配置

配置文件位于 `configs/config.yaml`，主要配置项包括：

- **节点配置**：节点ID、部署Token、标签
- **中心连接**：中心节点地址、TLS配置、重试策略
- **API服务**：REST和gRPC监听地址
- **运行时**：Kata/TEE运行时配置
- **存储**：MinIO配置
- **日志**：日志级别、格式、输出
- **监控**：Prometheus指标配置

详细配置说明请参考 [configs/config.example.yaml](configs/config.example.yaml)

## 开发指南

### 生成 protobuf 代码

```bash
make proto
```

### 代码检查

```bash
make lint
```

### 运行测试

```bash
# 运行所有测试
make test

# 仅运行单元测试
make test-unit

# 运行集成测试
make test-integration
```

### 代码格式化

```bash
make fmt
```

## 部署

### Docker 部署

```bash
# 构建镜像
make docker-build

# 推送镜像
make docker-push
```

### Kubernetes 部署

```bash
# 本地部署
make deploy-local

# 部署到开发环境
make deploy-dev

# 部署到生产环境
make deploy-prod
```

## 监控

Prometheus 指标暴露在 `:9090/metrics` 端点，主要指标包括：

- `sandbox_agent_sandbox_total` - 沙箱总数
- `sandbox_agent_sandbox_created_total` - 沙箱创建次数
- `sandbox_agent_api_request_duration_seconds` - API 请求耗时
- `sandbox_agent_heartbeat_latency_seconds` - 心跳延迟
- `sandbox_agent_connection_status` - 连接状态

## API 文档

详细 API 文档请参考 [docs/api.md](docs/api.md)

## 架构设计

详细架构设计请参考 [docs/architecture.md](docs/architecture.md)

## 贡献指南

欢迎贡献代码！请遵循以下规范：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 许可证

本项目采用 Apache 2.0 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

## 联系方式

- 作者：杨方帆
- 项目主页：https://github.com/privcalc/sandbox-node
- 问题反馈：https://github.com/privcalc/sandbox-node/issues

## 版本历史

- v0.1.0 (2025-11-28) - 初始版本，完成基础脚手架