# riscv-openstack-toolkit

**Repository Path**: openkylin/riscv-openstack-toolkit

## Basic Information

- **Project Name**: riscv-openstack-toolkit
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-09-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RISC-V OpenStack Toolkit

`riscv-openstack-toolkit` 是一套面向 openKylin RISC-V64 环境的 OpenStack 自动部署、节点接入、集群运维与故障诊断工具集。先安装 `main` 控制节点，之后所有计算节点使用同一个加入入口，由 main 自动依次分配 `compute1`、`compute2`、`compute3`……物理主机名和管理地址仅作为节点信息，不参与 compute 编号规则。

## 快速开始

在目标 Linux 节点克隆仓库，然后创建本地配置：

```bash
cp config/cluster.env.example config/cluster.env
vi config/cluster.env
```

安装完整 main 控制节点：

```bash
sudo bin/openstack-riscv main-install
```

在 main 上为每台计算节点生成首次启动加入包。以下地址和主机名仅为命令格式示例，
请替换为新机器的实际节点信息：

```bash
sudo bin/openstack-riscv join-compute 10.0.0.21 compute-node-a node-a
# 输出 compute1-join.tar.gz

sudo bin/openstack-riscv join-compute 10.0.0.22 compute-node-b node-b
# 输出 compute2-join.tar.gz
```

导入并准备 RISC-V 镜像、初始化云资源：

```bash
sudo bin/openstack-riscv image-import
sudo bin/openstack-riscv image-prepare
sudo bin/openstack-riscv cloud-bootstrap
```

外部 `public` 网络支持两种后端，部署前在 `config/cluster.env` 中选择
`PUBLIC_NETWORK_MODE=nat`（默认，控制节点 SNAT）或
`PUBLIC_NETWORK_MODE=physical`（专用物理网卡直通上游 LAN），然后执行：

```bash
sudo bin/openstack-riscv public-network-config
sudo bin/openstack-riscv cloud-bootstrap
```

物理模式必须填写专用、未配置 IPv4 地址的 `PUBLIC_PHYSICAL_INTERFACE`，并使用
上游网络中确实空闲且可路由的浮动 IP 地址池。不要把远程管理网卡用于物理模式，
除非已经准备好带外恢复。完整参数和切换说明见 [外部网络选择](docs/public-network.md)。

创建测试实例并验证：

```bash
sudo bin/openstack-riscv test-launch
sudo bin/openstack-riscv test-validate
sudo bin/openstack-riscv health
```

计算节点安装需要先安全传递由控制节点生成的服务凭据。完整步骤见 [部署指南](docs/deployment.md)。

## 统一入口

运行 `bin/openstack-riscv help` 可查看所有稳定入口。`scripts/` 中保留了完整的底层部署、诊断和恢复脚本，便于精细排障；统一入口只暴露经过验证的主流程。

```text
main-install        完整安装 main 控制节点
controller-phase1   控制节点第一阶段（高级入口）
controller-phase2   控制节点第二阶段（高级入口）
join-compute        自动分配下一个 computeN 并生成加入包
worker-install      节点描述调用的底层计算安装器
join-bundle         在控制节点生成新计算节点首次启动加入包
node-enroll         根据本机节点描述自动注册
controller-discovery 开启 Nova 周期性计算节点发现
image-import        下载、校验并导入 RISC-V 云镜像
image-prepare       提取内核/initrd，配置直接内核启动
public-network-config 应用 NAT 或物理 LAN 外部网络选择
cloud-bootstrap     创建网络、路由、规格、安全组和密钥
test-launch         创建测试实例与浮动 IP
test-validate       验证实例网络、SSH 和控制台日志
health              集群终态检查
memory-check        本机内存、slab、PSI、OOM 与调频状态只读巡检
node-memory-config  预览/应用计算节点内存预留及可选 K3 调频规避
  mariadb-capacity    修复数据库连接数耗尽
  cinder-controller  安装与 Nova 同版本系列的 Cinder 控制面
  cinder-types       为所有在线存储后端同步卷类型
  cinder-smoke       逐后端执行卷创建/删除测试
  cinder-attach      验证 Nova、os-brick、iSCSI 完整挂载链路
  webssh-install     编译 Guacamole 并安装 Horizon Web SSH
  webssh-sync        将控制节点现有私钥与 OpenStack 密钥对匹配
  webssh-user        设置单个实例的 Web SSH Linux 用户名
  check               仓库静态检查
```

## 文档

- [架构与工作流](docs/architecture.md)
- [从零部署](docs/deployment.md)
- [自动加入新的计算节点](docs/adding-compute-nodes.md)
- [RISC-V 镜像与兼容层](docs/riscv-images.md)
- [K3 QEMU/KVM 向量寄存器兼容补丁](docs/qemu-k3.md)
- [OOM 预防、内存巡检与 K3 调频规避](docs/oom-prevention.md)
- [Cinder 块存储](docs/block-storage.md)
- [扩容配额、实例登录与残留卷](docs/capacity-and-volume-recovery.md)
- [Horizon Web SSH](docs/webssh.md)
- [日常运维](docs/operations.md)
- [故障排查](docs/troubleshooting.md)
- [外部网络选择](docs/public-network.md)
- [脚本目录](docs/script-catalog.md)
- [安全说明](SECURITY.md)

## 安全边界

真实密码、OpenRC、SSH 私钥、云镜像和运行日志均不会进入 Git。控制节点的服务密码保存在 `/root/openstack-secrets.env`，计算节点仅接收其运行所需的子集。提交前运行：

```bash
bin/openstack-riscv check
```