> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/zh/mo-kuai-9-jian-kong-yu-gu-zhang-pai-chu/06-common-issues.md).

# 常见问题与解决方案

## 故障排除快速参考

本页汇总了 VergeOS 管理员最常遇到的问题，并按子系统分类整理。每个部分都包含症状、根本原因以及分步解决流程。

```mermaid
graph TD
    A["识别症状"] --> B{"哪个子系统？"}
    B -->|VM| C["网络 / 内存"]
    B -->|存储| D["vSAN / NAS"]
    B -->|硬件| E["SEL / IPMI"]
    B -->|安装| F["引导 / 加入"]

    C --> G["解决步骤"]
    D --> G
    E --> G
    F --> G
    G --> H{"已解决？"}
    H -->|是| I["记录并关闭"]
    H -->|否| J["升级至支持团队"]

    style A fill:#4a90d9,color:#fff
    style B fill:#2c3e50,color:#fff
    style G fill:#27ae60,color:#fff
    style J fill:#e74c3c,color:#fff
```

***

## VM 网络连接

网络连接问题是最常见的支持主题。在深入排查之前，请先确认 **其他 VM** 在同一环境中是否可以访问互联网。如果都不能，问题很可能出在 VergeOS 上游（交换机、防火墙、ISP）。如果其他 VM 正常工作，那么问题几乎总是出在受影响 VM 的配置遗漏。

### 缺少 NIC 配置

**症状：** VM 已启动，但客户机操作系统中看不到网络接口。

**解决方法：**

1. 打开 VM 仪表板并检查 **网卡** 部分
2. 如果未列出 NIC，请点击 **添加 NIC**
3. 选择正确的网络，并将接口类型设置为 **VirtIO** （推荐）或 **E1000** 以兼容旧系统
4. 当启用热插拔（默认）时，NIC 会立即出现在客户机中——某些操作系统可能需要在客户机内重新扫描；只有在禁用热插拔时才需要重启电源。

### 错误的网络分配

**症状：** VM 有 NIC，但无法访问其他 VM 或互联网。

**解决方法：**

1. 导航到 VM 仪表板 → **网卡**
2. 验证 NIC 状态为 **已连接**
3. 确认 **网络** 列显示的是正确的网络——请与同一环境中的正常 VM 进行对比
4. 如果不正确，请编辑 NIC 并重新分配到正确的网络
5. 重启 VM 电源

### 缺少 VirtIO 驱动

**症状：** Windows VM 在设备管理器中没有显示网络适配器，尽管 VergeOS 中已配置了 NIC。

**解决方法：**

1. 验证 VM 的 **网卡** 部分中是否存在 NIC
2. 通过 **远程控制台**
3. 连接到 VM，并从客户机代理 ISO 安装 VirtIO 驱动——请参阅 VergeOS 文档中的 [VM 客户机代理](https://docs.verge.io/product-guide/virtual-machines/vm-guest-agent/) 以获取下载和安装步骤
4. 安装驱动后，Windows 会自动检测网络适配器

### 客户机 IP 配置不正确

**症状：** NIC 已存在且驱动已安装，但 VM 仍然无法访问网络。

**解决方法：**

1. 在客户机操作系统内，验证网络适配器已被检测到并已启用
2. 对于 DHCP：确保网络上有正在运行的 DHCP 服务（检查 **网络 → \[网络] → DHCP**)
3. 对于静态 IP：确认 IP 地址、子网掩码、网关和 DNS 设置与网络设计一致
4. 使用 **网络诊断** 工具（ping、ARP 扫描）从 VergeOS 网络上下文中验证二层连接性

***

## 客户机内存报告

从 VMware 或 Nutanix 迁移过来的管理员经常会注意到 VergeOS 报告的内存使用量比预期更高。这是设计如此——不是问题。

### 已分配内存与活动内存

**症状：** VergeOS 显示某个 VM 使用了 8 GB RAM，但客户机操作系统任务管理器仅显示使用了 2 GB。

**说明：** VergeOS 显示的是 **已分配的** 内存——即主机上为该 VM 保留的物理 RAM。当你给 VM 分配 8 GB 时，虚拟机监控器会立即保留 8 GB 的物理内存，不管客户机实际消耗了多少。这才是主机上的真实资源承诺。

### 没有内存气球机制

与依赖内存气球机制回收未使用客户机内存的平台不同， **VergeOS 有意不使用气球机制**。这种设计带来：

* **可预测的性能** ——没有气球驱动开销或突发的内存压力
* **更简单的容量规划** ——已分配 = 已承诺；无需猜测超分配比例
* **更高的可靠性** ——不会在客户机内部因气球机制导致 OOM  పరిస్థిత
* **迁移尺寸更准确** ——你分配多少，目标主机就需要多少

### 容量规划最佳实践

| 指标               | 查看位置                        | 含义              |
| ---------------- | --------------------------- | --------------- |
| **VM 已分配 RAM**   | 虚拟机仪表板                      | 为此 VM 保留的物理 RAM |
| **客户机活动 RAM**    | 客户机操作系统内（任务管理器 / `free -h`) | 客户机实际使用的内存      |
| **节点可用 RAM**     | 节点仪表板 → 内存                  | 主机 RAM 还剩多少未分配  |
| **集群目标最大 RAM %** | 系统 → 设置 → 高级                | VM 放置决策的阈值      |

{% hint style="success" %}
**VM 合理配置大小**

由于 VergeOS 会分配全部内存，因此与使用气球机制的平台相比，合理配置 VM 内存更为重要。请从保守分配开始，仅在客户机监控显示持续高使用率时才增加。
{% endhint %}

***

## SEL 噪音（误报的 IPMI 日志）

某些服务器硬件会生成重复且无害的 IPMI 日志条目，填满系统事件日志（SEL）并触发不必要的告警。最常见的“罪魁祸首”是 **“Get SEL Info command failed”** 消息。

### 了解 SEL

系统事件日志存储在硬件中（位于 BMC/IPMI 控制器上），容量有限。一旦满了， **新事件就无法记录** ，直到清空日志。节点仪表板会以百分比条显示 SEL 容量。

### 通过 API 过滤 SEL 噪音

要在不丢失真实硬件告警的情况下抑制误报消息：

1. 导航至 **系统 → API 文档**
2. 找到 **设置** 表并展开它
3. 点击 **POST** 选项并输入此正文：

```json
{
  "key": "syslog_regex_list",
  "value": "2E2A4765742053454C20496E666F20636F6D6D616E64206661696C65642E",
  "default_value": "",
  "description": "要从 syslog 中过滤掉的正则表达式的十六进制编码行"
}
```

4. 单击 **执行**

该值是一个十六进制编码的正则表达式： `.*Get SEL Info command failed.` ——你可以在十六进制编码工具中编码其他模式，并用 `|`.

**示例——过滤两个模式：**

正则表达式 `(Get SEL Info command failed|Unable to send command: Device or resource busy)` 会编码为：

```
284765742053454C20496E666F20636F6D6D616E64206661696C65647C556E61626C6520746F2073656E6420636F6D6D616E643A20446576696365206F72207265736F75726365206275737929
```

### 重启 IPMI 服务

应用过滤器后，在每个受影响节点上重新启动日志捕获：

**选项 A —— 通过 UI：**

1. 导航至 **基础设施 → 节点 → \[节点]**
2. 编辑节点， **取消勾选** “捕获系统日志”，提交
3. 等待 15 秒
4. 再次编辑节点， **重新启用** “捕获系统日志”

**选项 B —— 通过 SSH：**

```bash
sudo systemctl restart openipmi
```

### 清空已满的 SEL

如果 SEL 已经满了：

1. 导航至 **基础设施 → 节点 → \[节点]**
2. 单击 **清空 SEL** 左侧菜单中的
3. 使用 **是**

***

## NAS 共享问题

### Windows：无法连接到 CIFS 共享

**症状：** Windows 10/11 客户端无法访问 CIFS 共享，即使凭据正确，也会收到“访问被拒绝”或“无法连接”错误。

**根本原因：** 现代 Windows 默认会禁用 SMB 连接中的不安全来宾登录。

**解决方法——启用不安全来宾登录：**

1. 按 `Win + R`，输入 `gpedit.msc`，按 Enter
2. 导航到： **计算机配置 → 管理模板 → 网络 → Lanman Workstation**
3. 找到 **启用不安全的来宾登录** → 右键单击 → **编辑**
4. 选择 **已启用** → 点击 **确定**
5. **重启** 该 Windows 设备

{% hint style="warning" %}
**Windows 家庭版**

`gpedit.msc` 不适用于 Windows 家庭版。请改用注册表编辑器：导航到 `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\LanmanWorkstation\Parameters` 并设置 `AllowInsecureGuestAuth` （DWORD）为 `1`.
{% endhint %}

### macOS：连接失败或性能不佳

**症状：** macOS Finder 无法连接到 CIFS 共享、连接间歇性断开，或者性能无法使用。

**解决方法——通过 `nsmb.conf`:**

1. 强制使用 SMB3。打开终端并创建或编辑 SMB 配置：

```bash
sudo nano /etc/nsmb.conf
```

2. 添加以下内容：

```ini
[default]
smb_neg=smb3_only
signing_required=no
```

3. **清除 macOS SMB 缓存：**

```bash
sudo rm -rf /var/db/samba/*
sudo rm -rf /var/db/smb/*
```

4. **重启 Mac** 以应用更改

**macOS 客户端的高级配置选项：** 为了获得更好的 macOS 兼容性，请在 NAS CIFS 设置（ `vfs objects = fruit streams_xattr` 以及相关的 `fruit:*` 选项）下添加面向 macOS 的指令（包括 **高级配置选项** 中的**NAS → CIFS**）。这将启用原生 Apple SMB 扩展。

### 权限被拒绝错误

**症状：** 即使用户能看到共享名称，在浏览或打开共享中的文件时仍会收到“访问被拒绝”。

**解决检查清单：**

1. **有效用户列表：** 导航至 **NAS → 共享 → \[共享]** 并确认该用户或组已在有效用户列表中
2. **可浏览设置：** 确保该共享已设置为 **可浏览** ，如果用户需要发现它
3. **强制用户 / 强制组：** 如果已配置，请验证强制用户/组对底层卷具有读写权限
4. **NAS 服务重启：** 更改权限后，重启 NAS 服务以应用

### CIFS 性能缓慢

**症状：** 通过 CIFS 的文件传输速度明显慢于预期。

**解决方法：**

1. **SMB 协议版本：** 在 **NAS → 卷 → \[卷] → 高级配置**，验证最小 SMB 协议版本。设置得太低（SMB1）会强制使用旧版协商
2. **网络路径：** 使用网络诊断（ping、traceroute）检查客户端子网与 NAS 网络之间的延迟
3. **连接负载：** 使用 NAS 诊断 → **Samba 状态** 检查活动连接并识别过载的共享
4. **NAS 资源：** 检查 NAS 服务的 CPU 和内存分配——资源配置不足的 NAS VM 会成为吞吐瓶颈

***

## 安装故障排除

### 引导问题

**症状：** 节点无法从 VergeOS USB 安装程序启动。

**解决方法：**

* 验证 BIOS/UEFI 启动设置与安装介质类型一致（建议使用 UEFI）
* 在已知正常工作的系统上测试 USB 介质，以排除驱动器损坏
* 确认硬件兼容性——检查 CPU 是否支持带硬件虚拟化的 64 位（VT-x/AMD-V）
* 如果安装程序无法加载，请在 BIOS 中禁用 Secure Boot

### 网络配置不匹配

**症状：** 安装完成，但节点无法与其他节点或网络通信。

**解决方法：**

* 在安装过程中， **请立即停止** 如果检测到的任何 IP 或接口与您的网络设计不匹配
* 验证 VLAN 配置与交换机端口设置一致
* 检查物理网线连接——安装程序会自动检测接口；布线不匹配会导致接口分配错误
* 确认 IP 地址分配不会与网络中现有设备冲突

### 存储控制器 JBOD 模式

**症状：** VergeOS 安装程序未检测到所有预期的驱动器。

**解决方法：**

* VergeOS 要求驱动器以独立磁盘（JBOD/直通模式）呈现， **不** 而不是 RAID 阵列
* 进入存储控制器 BIOS（例如 PERC、MegaRAID）并将每个驱动器配置为 JBOD 卷或单独的 RAID-0
* 某些控制器需要固件更新才能支持 JBOD 模式——请查阅硬件厂商文档

### 二级节点加入失败

**症状：** 二级控制器或计算节点无法加入现有集群。

**解决方法：**

1. 确认你已选择 **“否”** 当被问及这是否为新安装时（针对二级节点）
2. 确认你输入了 **来自主控制器的管理员凭据** 正确
3. 确保两个节点在同一网络上并且彼此可达（检查交换机端口 VLAN 分配）
4. 与主控制器的加密设置完全一致
5. 与主控制器的驱动器层级分配一致
6. 如果二级节点已启动但未在主界面中显示，请检查核心 fabric 网络配置并验证节点之间的交换机连通性

***

## 存储问题

### vSAN 降级状态

**症状：** 仪表板显示某个 vSAN 层处于“降级”或“非冗余”状态。

**说明：** 降级状态表示某一层中的一个或多个驱动器已故障或不可用，但 vSAN 仍在运行。由于 VergeOS 在各节点之间保持冗余，数据仍然可以访问。

**解决方法：**

1. 导航至 **系统 → vSAN → 驱动器** 以识别故障驱动器
2. 通过查看驱动器的 SMART 数据 **节点诊断 → S.M.A.R.T. 诊断测试**
3. 如果需要物理更换，请使用 **节点诊断 → LED 控制** 点亮驱动器槽位以便识别
4. 请联系 Verge 支持获取驱动器更换指导——一旦添加替换驱动器，vSAN 将自动重建冗余

### 驱动器重建时间

**了解预期：** 重建时间取决于该层上的数据量以及剩余驱动器的 I/O 容量。在重建期间：

* 系统仍将完全可用
* 写入性能可能会略有下降
* 通过 vSAN 仪表板中的层进度指示器监控进度（100% = 完成）

{% hint style="success" %}
**尽量减少重建影响**

避免在重建期间安排大量工作负载迁移或大规模数据导入。vSAN 会优先处理重建操作，但额外 I/O 会延长重建窗口。
{% endhint %}

### 容量阈值警告

**症状：** 仪表板告警会提示存储容量正在接近上限。

**解决方法：**

1. 在 **系统 → vSAN** 中检查层利用率——每层都会显示已用容量与总容量
2. 通过 **基础设施 → 节点 → \[节点] → 诊断 → S.M.A.R.T. 诊断测试** 检查磨损水平和驱动器健康指标
3. 如需立即缓解，请识别并删除不必要的快照或未使用的 VM 驱动器
4. 从长远来看，请添加驱动器或节点来扩展该层——请参阅 vSAN 扩容流程

以下临界点是 **培训指导** 用于规划，而非文档中定义的阈值。文档中列出的数值是 **80% 订阅高使用率默认值** （用于预置的 vSAN/存储层高使用率告警）以及 **90% `sync_max_usage`** vSAN 在该阈值处会限制写入并将该层标记为 `outofspace`.

| 利用率级别      | 所需操作              |
| ---------- | ----------------- |
| **< 70%**  | 正常运行——无需操作        |
| **70–85%** | 规划容量扩展；检查快照保留策略   |
| **85–90%** | 积极减少使用量或增加容量      |
| **> 90%**  | 严重——优先扩容；存在写入失败风险 |

***

## 故障排除决策树

当遇到不属于上述类别的问题时，请遵循以下通用流程：

### 1. 界定问题范围

问题影响的是一台 VM、一个网络、一个节点，还是整个系统？确定范围有助于决定从哪个诊断工具开始。

### 2. 使用组件诊断

从组件专用诊断工具开始（网络、节点、NAS 或 vSAN 诊断）——它们会自动在正确的上下文中运行。

### 3. 检查系统日志

查看仪表板日志和系统告警中的相关事件。寻找模式——是否有多个告警在同一时间触发？

### 4. 携带数据上报

如果问题仍未解决，请生成一个 **系统诊断** bundle（系统 → 系统诊断）并随支持请求一并提交。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/zh/mo-kuai-9-jian-kong-yu-gu-zhang-pai-chu/06-common-issues.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.