# KVMCloud下一代高弹性公有云管理平台

**Repository Path**: yuntianojo/kvmcloud

## Basic Information

- **Project Name**: KVMCloud下一代高弹性公有云管理平台
- **Description**: KVMCloud 是一个基于 Go 语言与 Vue 3 构建的现代化开源公有云管理平台。项目致力于统一纳管计算、存储与网络资源，覆盖产品编排、客户自助开通、计费、监控和运维全流程。
KVMCloud 首创了“端口级保障带宽 + 共享池突发借用”模型，并原生支持 CPU、内存、存储、带宽的四维超开调度，旨在为中小型云服务商、私有云建设者提供一套功能完备、部署极简、高度灵活的 IaaS 底座。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-11-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# kvmcloud

四维超开的轻量 KVM 云平台：**CPU / 内存 / 磁盘 / 网络带宽**统一超分调度，带宽支持 **保障（min）— 借用（borrow）— 抢占（preempt）** 语义与租户共享带宽池。

```
┌────────────────────────── 控制面 kvmcloud-control ──────────────────────────┐
│  HTTP API :8080（Gin）      gRPC :9443（节点注册/心跳）    水位监控（≥90% 告警） │
│  ├─ 四维超开放置 PlaceVM    ├─ Register（JOIN_TOKEN，幂等） └─ overcommit_alerts │
│  ├─ 带宽仲裁（保障/借用/抢占）└─ Heartbeat（快照 + 看门狗 offline）              │
│  └─ 共享池管理                                          PostgreSQL（squirrel）  │
└────────────────────────────────────┬────────────────────────────────────────┘
                               gRPC（9443）
┌────────────────────────────────────┴──────────── 计算节点 kvmcloud-agent ─────┐
│  注册/心跳 · TC HTB QoS（rate=min, ceil 动态）· 资源采集 · 内存气球 · KSM        │
└──────────────────────────────────────────────────────────────────────────────┘
```
![示例图片](.github/light-nodes.png)
示例图片
## 核心语义

**四维超开**（每节点可独立调优）：

| 维度 | 校验公式 | 默认比 |
| --- | --- | --- |
| CPU | `ΣvCPU ≤ physical × ratio` | 4.0 |
| 内存 | `Σmem ≤ physical × ratio` | 1.5 |
| 磁盘（精简置备） | `Σdisk ≤ physical × ratio` | 2.0 |
| 带宽 | `Σmin_kbps ≤ NIC × ratio` | 1.0 |

放置请求任一维超限即拒绝（`409 overcommit_exceeded`，错误含维度名），四维同事务原子更新。

**带宽三场景**（`internal/bandwidth`，纯函数 + advisory lock 串行化同池）：

1. **保障**：创建策略时两级校验——节点侧 `Σmin ≤ NIC×ratio`、池侧 `Σmin ≤ capacity`；
2. **借用**：池余量充足直接授予（`granted`），ceil 从 min 提升到 min+granted；
3. **抢占**：余量不足按优先级压回低优先级借用方（永不低于其 min），凑足授予（`preempted`）；凑不足整体拒绝（`denied`）。全部事件落 `borrow_events` 审计。

**水位告警**：任一维 `allocated/(physical×ratio) ≥ 0.90` 写入告警（阈值可配，10 分钟冷却），心跳回执携带四维水位。

## 快速开始

**极客模式**一行命令（两步式：下载后校验执行；自动识别发行版、换国内源、自动建库）：

```bash
curl -fsSL https://gitee.com/yuntianojo/kvmcloud/raw/main/install.sh -o /tmp/kvmcloud-install.sh \&& sudo bash /tmp/kvmcloud-install.sh all-in-one      # 或 control / agent --control-addr IP:9443 --token TOKEN
```

**海外用户**走自建德国 CDN 分发（默认 `--mirror cdn`，二进制与安装器均从 CDN 分发并 sha256 校验）：

```bash
curl -fsSL https://cdn.kvm.mianyun.cloud/install-overseas.sh -o /tmp/kc-os.sh && sudo bash /tmp/kc-os.sh all-in-one
```

**控制台（Web 前端）**：`v0.5.0` 起已内嵌进主控二进制（go:embed），安装主控即自带控制台——默认藏在 `http://<IP>:<随机端口>/<随机路径>/`（安装完成摘要打印完整入口；隐身防扫描，`/` 与 API 均不受影响，`cat /var/lib/kvmcloud/control-ui-path` 可找回）。无需 nginx / 单独安装。旧的独立安装器（nginx + CDN 分发）继续兼容；如需自定义域名/HTTPS，见下节「内置 HTTPS」。

```bash
curl -fsSL https://cdn.kvm.mianyun.cloud/frontend-install.sh -o /tmp/kc-web.sh && sudo bash /tmp/kc-web.sh
# 控制面在其它机器时：sudo bash /tmp/kc-web.sh --api-addr http://<主控IP>:8080
```

控制面没装时会提示先跑主控安装；重新执行脚本即覆盖升级。

**经典方式**：

```bash
# 单机全栈（开发/体验/小规模生产）
export DATABASE_URL="postgres://kvmcloud:<密码>@127.0.0.1:5432/kvmcloud"
sudo -E ./install.sh all-in-one

# 生产：主控
sudo -E ./install.sh control

# 生产：每台计算节点（不装 PG/Redis/NATS，只装 KVM/libvirt/TC）
sudo ./install.sh agent --control-addr 10.0.0.10:9443 --token <JOIN_TOKEN> \
    --cpu-ratio 4 --mem-ratio 1.5 --disk-ratio 2 --bw-ratio 1
```

三形态（all-in-one / control+多 agent / agent-only）行为完全一致：依赖服务只装一份；Agent 不监听端口；端口规划 8080/9443/5432/6379/4222。完整步骤与验收见 [docs/deploy.md](docs/deploy.md)，功能全景见 [docs/features.md](docs/features.md)。

## 内置 HTTPS（控制台证书）

控制台证书两种配置方式（互斥，部署配置优先）：

1. **control.env（推荐生产）**：`/etc/cloud/control.env` 配置 `CONTROL_TLS_CERT` / `CONTROL_TLS_KEY`（PEM 绝对路径）后重启 `cloud-control`，主控额外监听 `CONTROL_HTTPS_ADDR`（默认 :443）；外部 acme.sh 续期替换文件后**热生效无需重启**（调一次 Reload 或重启均可）。
2. **控制台上传**：打开控制台 → 「系统设置」→ 粘贴/选择证书 + 私钥 PEM 与访问域名，保存即热生效；证书持久化在主控数据目录（`$KVCLOUD_DATA_DIR/tls/`，0600），重启自动恢复。env 模式已配置时上传被拒绝（409），防止静默覆盖部署配置。

证书校验 fail-closed：cert/key 必须配对（`tls.X509KeyPair`），上传时校验证书域名与所填域名匹配（精确或单级通配）；私钥只写主控数据目录，不入数据库、不回显。

## 开发

```bash
make build     # bin/kvmcloud-control（自动先构建前端 embed 进二进制）+ bin/kvmcloud-agent
make test      # 单元测试（调度/仲裁/水位/QoS 命令生成）
make coverage  # 覆盖率
cd web && npm ci && npm run build   # 仅前端产物（已包含在 make build 中）
```

控制台 14 个页面：仪表盘（水位总览 + 新架构聚合）/ 虚拟机（创建 + 变配/迁移/回收站 + 任务轮询）/ 镜像市场（源同步 + 远端多选拉取 + 本地状态轮询）/ 云盘快照 / 安全组 / 端口转发 / 流量包 / 节点（超开比调优 + Pull 式接入向导）/ 带宽策略（借用/抢占 + VM 指标图）/ 共享池 / 任务 / 审计 / 水位告警 / **系统设置（TLS 证书上传与热生效）**。

控制台鉴权：新架构 API 走 `Bearer <KVMCLOUD_CONSOLE_TOKEN>`（主控 control.env，安装器随机生成，浏览器首次访问时粘贴一次）；前置缺失（Redis/令牌/基线迁移）时主控自动降级为 legacy-only。

## 自动更新

`kvmcloud-control` / `kvmcloud-agent` 内置自更新（默认开启）：定时检测 Gitee/GitHub 双通道新版本 → `checksums.txt` SHA-256 校验下载 → 原子替换二进制 → `systemctl restart` + 健康探测，失败自动回滚旧版。`KC_AUTO_UPDATE=check` 仅检测告警，`off` 关闭；详见 [docs/deploy.md](docs/deploy.md#6-本体自动更新)。

## 安全设计

- **源码零 SQL 文本**：语句经 squirrel 构建器生成，参数一律绑定占位符；DDL 为内嵌静态文件。
- **凭据不落源码**：`DATABASE_URL`、`CONTROL_JOIN_TOKEN` 等只从环境变量读取；env 文件 0600；`config/*.env.example` 不含可用凭据。
- **命令白名单**：Agent 侧仅 tc/virsh/nproc/df/free 可达，参数列表执行不经 shell，接口名正则白名单校验。
- **令牌校验**：注册令牌常量时间比较，支持有效期与一次性使用。

## 目录

```
api/proto/           gRPC 协议（Register/Heartbeat/QoS 下发）
cmd/control|agent    两个入口
internal/            store / bandwidth / monitor / grpcserver / api / agentlib / auth / model / pb
deploy/              systemd 单元
web/                 Vue3 控制台
install.sh           三形态安装/卸载
docs/deploy.md       部署指南（含 API 示例与故障排查）
```

## 赞助者
我们衷心感谢各位赞助者为我们提供的资金、服务器以及其他帮助。在大多数情况下，即使几乎没有反馈或回赠，他们依然慷慨地给予了我们这些支持。
这不仅推动了我们的开发进度，也为后续优化提供了更多可执行的建议，并为我们提供了部分可用于测试的硬件。
我们特别感谢以下赞助者：

企业赞助

[九霄云](https://idc.jiuxiaoyunidc.top/)——买服务器就找九霄云
![佛系云](.github/666576ed39582674ac58cedce2fbc406.png)
[佛系云](https://idc.idcfx.com/)——轻松上云，自营/合作资源主打一体化云资源

个人赞助


## License

Apache-2.0