内容
<!-- mcp-name: io.github.zw008/vmware-storage -->
# VMware 存储
> **作者**: Wei Zhou, VMware by Broadcom — wei-wz.zhou@broadcom.com
> 这是一个由 VMware 工程师发起的社区驱动项目，而不是官方 VMware 产品。
> 有关官方 VMware 开发者工具，请参阅 [developer.broadcom.com](https://developer.broadcom.com)。
[English](README.md) | [中文](README-CN.md)
VMware vSphere 存储管理：数据存储、iSCSI、vSAN — 11 个 MCP 工具，专注于领域且轻量级。
> 从 vmware-aiops 中分离出来，以便于更轻量的上下文和本地模型兼容性。
[](LICENSE)
## 配套技能
| 技能 | 范围 | 工具 | 安装 |
|-------|-------|:-----:|---------|
| **[vmware-aiops](https://github.com/zw008/VMware-AIops)** ⭐ 入口 | VM 生命周期、部署、访客操作、集群 | 31 | `uv tool install vmware-aiops` |
| **[vmware-monitor](https://github.com/zw008/VMware-Monitor)** | 只读监控、警报、事件、VM 信息 | 8 | `uv tool install vmware-monitor` |
| **[vmware-vks](https://github.com/zw008/VMware-VKS)** | Tanzu 命名空间、TKC 集群生命周期 | 20 | `uv tool install vmware-vks` |
| **[vmware-nsx](https://github.com/zw008/VMware-NSX)** | NSX 网络：段、网关、NAT、IPAM | 31 | `uv tool install vmware-nsx-mgmt` |
| **[vmware-nsx-security](https://github.com/zw008/VMware-NSX-Security)** | DFW 微分段、安全组、Traceflow | 20 | `uv tool install vmware-nsx-security` |
| **[vmware-aria](https://github.com/zw008/VMware-Aria)** | Aria Ops 指标、警报、容量规划 | 18 | `uv tool install vmware-aria` |
## 快速安装
```bash
# 通过 PyPI
uv tool install vmware-storage
# 或使用 pip
pip install vmware-storage
```
## 配置
```bash
mkdir -p ~/.vmware-storage
cp config.example.yaml ~/.vmware-storage/config.yaml
# 使用您的 vCenter/ESXi 凭证进行编辑
echo "VMWARE_MY_VCENTER_PASSWORD=your_password" > ~/.vmware-storage/.env
chmod 600 ~/.vmware-storage/.env
# 验证
vmware-storage doctor
```
## MCP 工具（11 个）
| 类别 | 工具 | 类型 |
|----------|-------|------|
| 数据存储 | `list_all_datastores`, `browse_datastore`, `scan_datastore_images`, `list_cached_images` | 读取 |
| iSCSI | `storage_iscsi_enable`, `storage_iscsi_status`, `storage_iscsi_add_target`, `storage_iscsi_remove_target`, `storage_rescan` | 读取/写入 |
| vSAN | `vsan_health`, `vsan_capacity` | 读取 |
## 自动修复模式（PoC）
[`patterns/`](patterns/) 目录中包含来自企业 Harness 工程框架的 L5 自动修复候选模式。第一个 PoC 模式 [`patterns/iscsi-target-stale-rescan.yaml`](patterns/iscsi-target-stale-rescan.yaml) 描述了 iSCSI HBA 重新扫描作为一种低风险、可逆、可重复的操作。模式架构仅在此处记录，运行时强制执行**尚未启用**，因此这是一个参考设计，而不是生产自动修复。
## 常见工作流程
### 在主机上设置 iSCSI 存储
1. 启用 iSCSI 适配器：`vmware-storage iscsi enable esxi-01`
2. 添加目标：`vmware-storage iscsi add-target esxi-01 10.0.0.100`
3. 验证：`vmware-storage iscsi status esxi-01`
`add-target` 命令会自动重新扫描存储。使用 `--dry-run` 预览任何写入命令。
### 跨数据存储查找可部署的镜像
1. 列出所有数据存储：`vmware-storage datastore list`
2. 扫描镜像：`vmware-storage datastore scan-images datastore01`
3. 使用模式浏览：`vmware-storage datastore browse datastore01 --pattern "*.iso"`
### vSAN 健康评估
1. 检查健康状况：`vmware-storage vsan health Cluster-Prod`
2. 检查容量：`vmware-storage vsan capacity Cluster-Prod`
3. 如果发现问题，请使用 `vmware-monitor` 检查警报和事件
## CLI
```bash
# 数据存储
vmware-storage datastore list
vmware-storage datastore browse datastore01
vmware-storage datastore scan-images datastore01
# iSCSI
vmware-storage iscsi status esxi-01
vmware-storage iscsi enable esxi-01
vmware-storage iscsi add-target esxi-01 192.168.1.100
vmware-storage iscsi remove-target esxi-01 192.168.1.100
vmware-storage iscsi rescan esxi-01
# vSAN
vmware-storage vsan health Cluster-Prod
vmware-storage vsan capacity Cluster-Prod
# 诊断
vmware-storage doctor
```
## MCP 服务器
**安装 `uv tool install vmware-storage` 后，使用以下命令启动 MCP 服务器** （v1.5.15+）：
```bash
# 推荐 — 单个命令，无需网络重新解析
vmware-storage mcp
# 使用自定义配置文件路径
VMWARE_STORAGE_CONFIG=/path/to/config.yaml vmware-storage mcp
# 或使用 Docker
docker compose up -d
```
### 代理配置
将以下内容添加到您的 AI 代理的 MCP 配置中：
```json
{
"mcpServers": {
"vmware-storage": {
"command": "vmware-storage",
"args": ["mcp"],
"env": {
"VMWARE_STORAGE_CONFIG": "~/.vmware-storage/config.yaml"
}
}
}
}
```
<details>
<summary>替代方案：uvx（无需安装）或旧入口点</summary>
```bash
# 无需安装即可运行（每次启动都需要 PyPI 访问）
uvx --from vmware-storage vmware-storage mcp
# 旧入口点（仍然有效，为向后兼容而保留）
vmware-storage-mcp
```
> **在企业 TLS 代理后面？** uvx 可能会因 `invalid peer certificate: UnknownIssuer` 而失败。
> 使用上述推荐的 `vmware-storage mcp` 形式（无需网络），或设置 `UV_NATIVE_TLS=true`。
</details>
## 为什么要单独使用一项技能？
`vmware-aiops` 有 33 个 MCP 工具 — 对于本地 LLM（7B-14B）来说太重了。通过将存储分离成自己的技能：
- **11 个工具** — 可以舒适地适应小型模型上下文窗口
- **领域聚焦** — 存储管理员仅获得所需的内容
- **可组合** — 根据需要与 vmware-monitor 或 vmware-aiops 一起使用
## 版本兼容性
**Python**：3.10+（自 v1.5.27 起 — 之前为 3.11+）。在 3.10 / 3.11 / 3.12 上测试。
| vSphere / VCF | 支持 | 备注 |
|---------|---------|-------|
| VCF 9.1 / vSphere 9.1 | 完整 | 发布于 2026-05-12。pyVmomi+vSAN SDK `<10.0` 通过 SOAP 工作。 |
| VCF 9.0 / vSphere 9.0 | 完整 | pyVmomi 8.0.3+ 带有捆绑的 vSAN SDK 连接到 vSphere 9。 |
| 8.0 | 完整 | vSAN SDK 构建到 pyVmomi 8.0.3+ 中 |
| 7.0 | 完整 | 所有存储 API 都有效 |
| 6.7 | 兼容 | iSCSI + 数据存储功能有效；vSAN 有限 |
#### 官方 Broadcom 参考资料
- **SDK**：<https://developer.broadcom.com/sdks> — VCF Python SDK，vSAN 管理 SDK（捆绑在 pyVmomi 中）
- **REST API**：<https://developer.broadcom.com/xapis> — vSAN 管理 API，VCF API
- **CLI 工具**：<https://developer.broadcom.com/tools> — PowerCLI 9.1，ESXCLI
## 安全
| 功能 | 描述 |
|---------|-------------|
| 读取为主 | 6/11 个工具是只读的 |
| 输入验证 | 在 iSCSI 操作前验证 IP 地址和端口 |
| 审计日志 | 所有操作记录到 `~/.vmware-storage/audit.log` |
| 无 VM 操作 | 无法创建、删除或修改 VM |
| 凭证安全 | 密码仅来自环境变量，绝不来自配置文件 |
## 故障排除
| 问题 | 原因和解决方法 |
|---------|-------------|
| iSCSI 启用失败，提示“已启用” | 不是错误 — 适配器已激活。运行 `iscsi status` 查看已配置的目标。 |
| 浏览时“数据存储未找到” | 数据存储名称**区分大小写**。运行 `datastore list` 获取确切名称。 |
| vSAN 健康状况显示“未知” | vSAN 健康状况需要**vCenter 连接**，而非独立的 ESXi。 |
| 重新扫描后未发现新的 LUN | 在添加目标后等待 15-30 秒，然后再次重新扫描。验证目标 IP 是否可从 ESXi 访问。 |
| “密码未找到”错误 | 变量名称遵循 `VMWARE_<TARGET_UPPER>_PASSWORD`（连字符 → 下划线）。检查 `~/.vmware-storage/.env`。 |
| 连接到 vCenter 的超时 | 使用 `vmware-storage doctor --skip-auth` 在高延迟网络上绕过身份验证检查。 |
| “数据存储浏览未在 Ns 内完成” | 数据存储非常大或繁忙。使用子路径和特定模式（例如 `datastore browse ds01 --path templates --pattern "*.ova"`）而不是浏览根目录 — 不要只是重试相同的广泛浏览。 |
## 许可证
[MIT](LICENSE)
