# volta

**Repository Path**: cdevel/volta

## Basic Information

- **Project Name**: volta
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: feature/volta-osa-foundation
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-29
- **Last Updated**: 2026-06-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Volta

Volta 是一个用 C 编写的存储系统原型，目标是验证类似 vSAN OSA 的分层数据路径：上层由 client/QEMU 接入块设备语义，下层由 server/OSD 管理缓存、容量、元数据持久化、故障恢复和生产验收证据。

当前仓库包含：

- `libvolta` client ABI。
- OSD/server 侧运行程序和复制、恢复、健康检查逻辑。
- QEMU BlockDriver 集成代码。
- 可选 SPDK 数据面实验和生产准入脚本。
- UAT、生产、Parity、归档和发布验收 gate。
- Debian 双包构建工具。

完整设计说明见 [架构文档](docs/architecture.md)。

## 包模型

DEB 是 Volta 的主要分发边界。源码树构建和 CTest 用于开发门禁，
生产安装、升级、回滚和验收都以 Debian 包为准。

Debian 包按部署角色拆分，不做单一大包。

### `volta-server`

server 端包，包含运行和运维侧内容：

- `volta-osd-replica`。
- QEMU 迁移、重加入、共享盘场景的 gate 辅助程序。
- 使用 `--spdk` 打包时包含 SPDK 版 `volta-osd`。
- 使用 `--spdk` 打包时包含 `/usr/lib/volta/spdk` 下的 DPDK runtime
  共享库，安装后的 server 二进制不能依赖 `/codes/volta` 源码树。
- WebUI/API 生产服务：`/usr/bin/volta-webui-api`、
  `volta-webui-api.service`、`/usr/share/volta/webui` 静态资产和
  `/usr/share/volta/examples/webui.env`。
- UAT、生产准入、性能准入、Parity 审计、归档、发布验收脚本。
- 生产 runbook 和验收文档。

### `libvolta-client-dev`

client 端包，提供 QEMU 或其他客户端编译、链接 Volta 所需的开发面：

- `libvolta.a`。
- `/usr/include/volta` 下的公共 ABI 头文件。
- `/usr/include/volta/qemu` 下的 QEMU glue 头文件。
- 当前 QEMU glue 仍需要的内部适配头文件，位于 `/usr/include/volta/internal`。
- `volta-client.pc` pkg-config 文件，以及兼容旧 QEMU 查找名的 `volta.pc`
  别名。
- QEMU 适配源文件 `/usr/share/volta/qemu/block-volta.c`。

QEMU 链接 libvolta-client-dev。下游 QEMU 构建使用：

```sh
pkg-config --cflags --libs volta-client
pkg-config --cflags --libs volta
```

当前 QEMU 集成是源码级集成：QEMU 编译 Volta 提供的 BlockDriver 适配源文件和头文件，然后链接 `libvolta.a`。

## 构建

默认非 SPDK 构建：

```sh
cmake -S . -B build -DBUILD_SHARED_LIBS=OFF
cmake --build build -j2
ctest --test-dir build --output-on-failure
```

SPDK 构建需要先准备 `third_party/spdk`，并确保 SPDK/DPDK 的头文件和 pkg-config 文件可用：

```sh
cmake -S . -B build-spdk -DVOLTA_SPDK_ENABLED=ON
cmake --build build-spdk -j2
ctest --test-dir build-spdk --output-on-failure
```

如果需要构建 QEMU BlockDriver 模块，设置 `VOLTA_QEMU_SOURCE_DIR` 指向 QEMU 源码树。该源码树必须包含 `include/block/block_int-common.h`。

## Debian 打包

构建默认双包：

```sh
tools/build_deb_packages.sh
```

默认输出到 `dist/volta/`：

- `volta-server_<version>_<arch>.deb`
- `libvolta-client-dev_<version>_<arch>.deb`

常用参数：

```sh
tools/build_deb_packages.sh --dry-run
tools/build_deb_packages.sh --version 1.0.0 --arch amd64
tools/build_deb_packages.sh --build-dir build-deb --output-dir dist/volta
tools/build_deb_packages.sh --spdk
tools/build_deb_packages.sh --qemu-source-dir /path/to/qemu
```

安装后，WebUI/API 不应通过 `npm run dev` 或源码树里的 `tsx` 作为生产入口运行。
复制并按现场调整 `/usr/share/volta/examples/webui.env` 到
`/etc/volta/webui.env`，再启用 systemd 服务：

```sh
sudo install -m 0644 /usr/share/volta/examples/webui.env /etc/volta/webui.env
sudo systemctl enable --now volta-webui-api.service
```

`/etc/volta/webui.env` 管理 API 绑定地址、证据目录、静态前端目录、
集群节点、管理 token hash，以及 QEMU/SuperVM/guest-fio 工具路径。

`--spdk` 会把 SPDK 版 `volta-osd` 放入 `volta-server`，并把当前
仓库构建出的 DPDK runtime 共享库放到 `/usr/lib/volta/spdk`。该模式
会安装 `/etc/ld.so.conf.d/volta-server.conf`，并通过 package
maintainer scripts 执行 `ldconfig`，让 DPDK 的递归共享库依赖也能从
包内 runtime 目录解析。打包会保留 DPDK soname symlink，避免
`ldconfig` 在安装或升级时把版本化 runtime 当成异常普通文件。该模式
要求本地 SPDK 已经配置、构建到足以通过 Volta CMake 检查的状态。
安装后应使用 `readelf -d` 和 `ldd` 确认 `volta-server` 二进制不再
解析到 `/codes/volta` 或 `third_party/spdk`。

输出目录保持 Volta 为主体。`--spdk` 是 `volta-server` 的构建 flavor，
不是单独的分发身份；默认产物路径仍是 `dist/volta/`。

即使使用 `--spdk` 构建 server 包，client 包仍然从非 SPDK 构建树取 libvolta.a。
`libvolta-client-dev` 不携带 SPDK/DPDK runtime，
`volta-client.pc` 也不暴露 SPDK/DPDK 链接参数；公共头文件可以保留
SPDK 数据路径枚举和配置字段，但不能让客户端包产生 SPDK/DPDK
链接或运行时依赖。

## 运维 gate

`tools/` 下的 gate 脚本支持 dry-run 和实际运行。它们会进入 `volta-server` 的 `/usr/lib/volta/tools`：

```sh
tools/volta_osa_uat_gate.sh --dry-run
tools/volta_osa_production_gate.sh --dry-run
tools/volta_osa_release_gate.sh --dry-run
tools/volta_enterprise_three_node_gate.sh --run \
  --evidence-root evidence/deb-three-node \
  --webui-root webui
```

这些 gate 用来固化 UAT、生产准入、性能准入、Parity 审计、归档、发布验收和三节点企业验证路径。
`volta_enterprise_three_node_gate.sh` 只读取证据，不执行破坏性操作；它汇总三节点包安装、runtime closure、升级、硬件 smoke、性能 admission、发布 gate、磁盘安全证据、QEMU rejoin/failback、迁移 dirty-sync 和 WebUI 管理能力，输出 `enterprise_three_node_ready` 与 `live_disk_migration_verified` 判定。物理盘操作仍由 final guard 和 WebUI preflight token 保护。生产环境执行前应先阅读 `docs/production/` 下的 runbook。

## 当前边界

- 默认打包路径构建非 SPDK 版本，适合 client ABI、QEMU glue 和基础 server 工具验证。
- SPDK 版 OSD 属于高级路径，构建时依赖本地 SPDK 子模块；分发时
  通过 `volta-server` 携带 `/usr/lib/volta/spdk` runtime，并依赖
  Debian 系统库包提供 libc、libaio、libnuma、OpenSSL、lz4、uring
  和 keyutils。
- `--spdk` 打包时 server 和 client 使用不同构建树，client 包保持
  非 SPDK 链接面。
- QEMU 集成面当前仍包含少量内部头文件，后续可以继续收敛成更稳定的公开 client/QEMU SDK。
- `build-deb/` 和 `dist/` 是生成目录，已在 `.gitignore` 中忽略。