# xebs

**Repository Path**: cdevel/xebs

## Basic Information

- **Project Name**: xebs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# XEBS 通用块存储系统

[![License](https://img.shields.io/github/license/cdevel/xebs)](LICENSE)

XEBS 是一个高性能、高可用的通用块存储系统，基于 SPDK 和 Rust 构建，支持 NVMe-oF 导出、存储池管理、逻辑卷创建等功能。

## 特性

- **高性能 I/O**：基于 SPDK (Storage Performance Development Kit) 构建，提供极低的 I/O 延迟
- **高可用性**：支持 HA Agent 故障自动切换
- **NVMe-oF 支持**：支持 NVMe over Fabrics 协议导出块设备
- **存储池管理**：支持存储池 (Pool) 和逻辑卷 (LVS) 管理
- **可扩展架构**：分离数据平面 (xebs_engine) 和控制平面 (xebs_control)
- **原生独立部署**：支持裸机/systemd 方式部署与运维
- **gRPC API**：高效的 gRPC 接口进行存储管理

## 系统架构

### 数据平面 - xebs_engine

数据平面负责实际的数据 I/O 处理，运行在每个存储节点上：

- **SPDK Reactor 线程模型**：高性能异步 I/O 处理
- **Nexus 聚合层**：聚合多个后端存储设备
- **块设备层**：支持多种 bdev 类型
- **NVMe-oF Target**：通过网络导出块设备
- **gRPC API**：与控制平面通信

### 控制平面 - xebs_control

控制平面负责资源编排和集群管理：

- **Core Agent**：存储资源编排
- **HA Agent**：高可用故障检测与恢复
- **REST API**：提供 HTTP REST 接口
- **CLI / API**：通过 xebs-cli（资源域命令）与 REST 进行统一管理

## 快速开始

### 环境要求

- Linux 系统 (推荐 Ubuntu 20.04+)
- Rust 1.70+
- SPDK 依赖库
- 开发者工具 (make, gcc, etc.)

### 构建步骤

```bash
# 1. 初始化子模块
git submodule update --init --recursive

# 2. 编译 SPDK + Control + Engine
make build

# 或者使用构建脚本
./scripts/build.sh
```

### 部署

```bash
# 安装二进制文件和配置
sudo ./scripts/install.sh

# 启动存储节点 Engine
sudo systemctl start xebs-engine

# 启动控制面 Core（编排/调度/注册）
sudo systemctl start xebs-control

# 启动管理面 REST（HTTPS，可选 JWT）
sudo systemctl start xebs-rest
```

## Ubuntu/Rocky 系统包（deb/rpm）

除了容器镜像与 `scripts/install.sh` 的裸机安装方式，本仓库也支持生成：

- Ubuntu 22.04: `.deb`
- Rocky 9.7: `.rpm`

打包工具使用 `nfpm`（只负责把已构建的 `build/` 产物打成系统包）。

```bash
# 1) 安装 nfpm（二选一）
go install github.com/goreleaser/nfpm/v2/cmd/nfpm@latest

# 2) 构建 release 产物并生成 deb/rpm
make packages

# 产物输出到 dist/
ls -lh dist/
```

说明：包默认把二进制安装到 `/usr/bin`，配置到 `/etc/xebs`，systemd 单元默认通过 drop-in 将 `XEBS_PREFIX` 设置为 `/usr`。

### 启用 REST JWT（可选，HS256 JWK）

默认安装配置会以 `--no-auth` 启动 REST，便于首次 bring-up。若需要开启 JWT 校验：

1) 修改 `/etc/xebs/xebs-rest.env`，移除 `--no-auth`，并加入：

```bash
--jwk /etc/xebs/jwk.json
```

2) 重启 REST：

```bash
sudo systemctl restart xebs-rest
```

3) 生成 token（使用仓库自带无依赖脚本）：

```bash
TOKEN=$(./scripts/mint-jwt.py --jwk /etc/xebs/jwk.json --sub admin --exp 3600)
```

4) 验证未带 token 访问应失败（示例期望 401）：

```bash
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8080/v1/nodes
```

5) 验证带 token 访问应成功（示例期望 200）：

```bash
curl -sk -o /dev/null -w '%{http_code}\n' \
	-H "Authorization: Bearer ${TOKEN}" \
	https://127.0.0.1:8080/v1/nodes
```

说明：默认使用 `--dummy-certificates`，因此 curl 需要 `-k`（跳过证书校验）。

## 配置

配置文件位于 `config/` 目录：

- `xebs-core.env` - 控制面 core（systemd EnvironmentFile）
- `xebs-rest.env` - 管理面 REST（systemd EnvironmentFile）
- `xebs-engine.env` - 数据面 io-engine（systemd EnvironmentFile）
- `jwk.json` - REST JWT 校验用的 JWK（默认提供 HS256 示例 key）

兼容保留（可能不会被当前 systemd 单元使用）：

- `xebs-control.toml`
- `xebs-engine.toml`

## 项目结构

```
├── config/              # 配置文件
├── deploy/              # 部署相关 (systemd)
├── docs/                # 架构文档
├── scripts/             # 构建和部署脚本
├── xebs-control/        # 控制平面 (Rust)
└── xebs-engine/         # 数据平面 (Rust + SPDK)
```

## 文档

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

独立部署（单机冒烟）Runbook： [docs/runbook-standalone.md](docs/runbook-standalone.md)

## 许可证

本项目基于 [LICENSE](LICENSE) 中指定的许可证开源。