Proxbase

Name: Proxbase
Author: virtbase

本地服务

github.com云与基础设施14 天前更新

代码仓库访问官网

关于 Proxbase

Proxbase 是用于在 Linux 主机上创建 Proxmox VE 集群实验环境的工具，面向实验、演示和 CI。它以 QEMU/KVM 虚拟机安装真实节点，并支持集群生命周期管理、故障注入和自动化；其 MCP 服务也可让 Agent 操作集群。

主要功能

01通过 QEMU/KVM 创建真实 Proxmox VE 节点
02配置 ZFS 或 Ceph 存储与内部网络
03管理集群节点、生命周期和快照
04注入断电、网络分区等故障
05提供 Terraform、Ansible 和 CI 自动化支持

适用场景

01搭建 Proxmox VE 集群实验或演示环境
02测试高可用、隔离和 Ceph 恢复行为
03在 CI 中创建并销毁集群以运行集成测试

MCP 相关

`proxbase mcp` 提供 MCP 服务，供 Agent 创建集群、调用 API、在节点上运行命令、诊断问题、恢复快照及注入故障。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "virtbase-proxbase": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/virtbase/proxbase:0.4.0"
      ]
    }
  }
}

启动命令docker run -i --rm ghcr.io/virtbase/proxbase:0.4.0

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

ocighcr.io/virtbase/proxbase:0.4.0stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Proxbase

在你的 Linux 机器上，约三分钟即可启动真实的 Proxmox VE 集群，用于实验室、演示和 CI。

Proxbase 将每个节点作为 QEMU/KVM 虚拟机启动，通过自动化安装程序使用官方 Proxmox VE ISO 安装系统，并通过 Proxmox API 将节点加入集群，同时配置 ZFS 或 Ceph 存储、内部网络，以及可供 Terraform 或 Ansible 使用的 API 令牌。无需 root、无需 Docker，也无需手动点击。

$ proxbase create lab --nodes 3
…
created in 2m56s
Cluster lab: ready, quorate: yes, switch: running
NODE  VM       CLUSTER  IP           WEB UI                   SSH
pve1  running  online   10.10.10.11  https://127.0.0.1:18001  127.0.0.1:18101
pve2  running  online   10.10.10.12  https://127.0.0.1:18002  127.0.0.1:18102
pve3  running  online   10.10.10.13  https://127.0.0.1:18003  127.0.0.1:18103

功能

**真实节点：**每个节点都是一台从原版 ISO 安装系统、拥有独立内核的虚拟机；借助嵌套虚拟化，可在集群中运行来宾虚拟机。
**存储：**每个节点都可使用 ZFS 池，或使用超融合 Ceph（RBD 和 CephFS），并等待其达到 HEALTH_OK 状态。
**无需 root 的网络：**多个带角色的内部网络（corosync link0/link1、Ceph 公共网络/集群网络、迁移网络）、支持 VLAN 的桥接和仅限 L2 的桥接，以及巨型帧。
**生命周期：**启动/停止、添加和移除节点（含 Ceph 数据迁移）、整个集群的一致性快照、可在数秒内恢复运行中集群的实时快照，以及可恢复的创建操作。
**故障注入：**断电、节点挂起、拔除网线、网络分区、延迟和丢包，用于测试 HA、隔离和 Ceph 恢复。
**可用于自动化：**导出 API 令牌和 CA、通过 proxbase env 配置 Shell 环境、支持 JSON 和 bpg/proxmox Terraform 提供程序、为脚本提供 -o json 和 --progress json，以及可在 CI 中将就绪集群缓存为模板的 GitHub Action。
面向 AI Agent：proxbase mcp 是一个 MCP 服务：Agent 可通过工具创建集群、调用 API、在节点上运行命令、进行诊断、恢复到快照和注入故障。技能可指导其工作流；在 Claude Code 中使用：/plugin install proxbase --marketplace virtbase/proxbase。
快速：--golden 从缓存的基础映像克隆节点：一分钟内即可创建 3 节点集群（Ceph：1.5 分钟），且每个节点都有唯一身份。
**声明式：**使用一个带有 JSON Schema 的 YAML 文件；每个标志都可覆盖相应字段。
Docker Compose：proxbase up 在前台运行集群，并提供正常关闭和健康检查。

快速开始

要求：运行于 amd64 架构且带有 /dev/kvm 的 Linux、QEMU 7.2+（qemu-system-x86_64、qemu-img），以及每个节点约 4 GiB RAM。要在节点内运行来宾虚拟机，需要启用嵌套虚拟化。

go install github.com/virtbase/proxbase/cmd/proxbase@latest   # or see docs/install.md
proxbase doctor                                               # checks KVM, QEMU, memory, ports
proxbase create lab --nodes 3

然后打开 https://127.0.0.1:18001（用户名为 root，密码可通过 proxbase env lab 获取），或者：

proxbase ssh lab pve2 -- pvecm status
eval "$(proxbase env lab)"            # PROXMOX_VE_ENDPOINT, PROXMOX_VE_API_TOKEN, …
proxbase destroy lab --yes            # removes everything

用法

proxbase create ceph --nodes 3 --storage ceph       # hyperconverged Ceph
proxbase create fast --nodes 3 --golden             # clone from a cached base image
proxbase create -f examples/networks.yaml           # separate networks and VLANs
proxbase node add lab --count 1                     # grow the cluster
proxbase node remove lab pve2                       # shrink it again
proxbase stop lab && proxbase snapshot save lab base
proxbase snapshot restore lab base && proxbase start lab
proxbase env lab --format terraform                 # provider block for bpg/proxmox
proxbase fault partition lab pve3                   # isolate a node, then: fault clear
proxbase status lab --check                         # exit code for CI and health checks
claude mcp add proxbase -- proxbase mcp             # let an AI agent drive proxbase
proxbase upgrade                                    # install the latest release

在 GitHub Actions 中：

- id: pve
  uses: virtbase/proxbase@v0          # KVM, QEMU, cache, create; outputs endpoint, api-token, env-file
- env: {PVE_ENV: "${{ steps.pve.outputs.env-file }}"}
  run: . "$PVE_ENV" && go test ./... -tags integration
- if: always()
  run: proxbase destroy ci --yes

集群配置文件示例如下（所有字段都有默认值）：

apiVersion: proxbase.virtbase.com/v1alpha1
kind: Cluster
name: lab
nodes:
  count: 3
  defaults: {cpus: 4, memory: 4G, dataDisks: [{size: 32G}]}
networks:
  - {name: cluster, cidr: 10.10.10.0/24, roles: [corosync]}
storage:
  zfs: [{name: tank, raid: single}]

文档

主题
入门	第一个集群、Web UI、凭据
安装	软件包、Homebrew、容器映像、验证发行版本
配置	每个字段、默认值和限制
网络 · 存储 · 生命周期	工作原理及预期表现
故障注入 · 黄金映像	主动破坏集群、加快创建速度
CI 和自动化 · MCP 服务	GitHub Action、JSON 进度、AI Agent
Docker · CLI 参考 · 故障排查
架构	软件包、创建流程、磁盘上的状态
示例	常见设置的即用型集群配置文件

状态与限制

Proxbase 还处于早期阶段；文件格式在 v1.0 发布前可能会发生变化。它已在 Debian 13 上的 Proxmox VE 9.2（QEMU 10.0，AMD）中通过测试。集群需要配备 KVM 的 Linux 主机：macOS 版本尚处于实验阶段，且 Docker Desktop 不提供 /dev/kvm。节点可通过转发到 127.0.0.1 的端口从主机访问；可从主机访问的桥接网络已完成设计，但尚未实现。Proxbase 用于构建实验环境：它会将生成的密码和密钥以未加密形式存储在其状态目录中。