> 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-cha/06-common-issues.md).

# 常见问题与解决方案

最常见 VergeOS 问题的故障排除模式——虚拟机网络、来宾内存报告、SEL 噪声、NAS 共享、安装问题和存储退化。

## 故障排除快速参考

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

```mermaid
graph TD
    A["识别症状"] --> B{"哪个子系统？"}
    B -->|虚拟机| 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
```

***

## 虚拟机网络连接

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

### 缺少网卡配置

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

**解决方法：**

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

### 错误的网络分配

**症状：** 虚拟机有网卡，但无法连接其他虚拟机或互联网。

**解决方法：**

1. 导航至虚拟机仪表板 → **网卡**
2. 确认网卡状态为 **启用**
3. 确认 **网络** 列显示正确的网络——与同一环境中的正常虚拟机进行比较
4. 如果不正确，请编辑网卡并将其重新分配到正确的网络
5. 重启虚拟机

### 缺少 VirtIO 驱动程序

**症状：** Windows 虚拟机在设备管理器中未显示网络适配器，尽管 VergeOS 中已配置网卡。

**解决方法：**

1. 确认虚拟机的 **网卡** VergeOS 中的部分内存在网卡
2. 通过以下方式连接到虚拟机： **远程控制台**
3. 从客户机代理 ISO 安装 VirtIO 驱动程序——有关下载和安装步骤，请参阅 VergeOS 文档中的 [虚拟机客户机代理](https://docs.verge.io/run-the-platform/zh/xu-ni-ji/vm-guest-agent.md) 。
4. 安装驱动程序后，Windows 将自动检测网络适配器

### 客户机 IP 配置不当

**症状：** 网卡已存在且驱动程序已安装，但虚拟机仍无法访问网络。

**解决方法：**

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

***

## 客户机内存报告

从 VMware 或 Nutanix 迁移而来的管理员经常发现，VergeOS 报告的内存使用量高于预期。这是设计使然，并非问题。

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

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

**说明：** VergeOS 显示 **已分配的** 内存——即主机为该虚拟机预留的物理 RAM。当您为虚拟机分配 8 GB 时，无论客户机实际消耗多少，虚拟机监控程序都会立即预留 8 GB 物理内存。这才是主机上的实际资源承诺。

### 不使用内存气球技术

与依赖内存气球技术回收未使用客户机内存的平台不同， **VergeOS 有意不使用气球技术**。这一设计选择提供：

* **可预测的性能** ——没有气球驱动开销或意外的内存压力
* **简化的容量规划** ——已分配 = 已承诺；无需猜测超额分配比率
* **增强的可靠性** ——没有客户机内因气球技术引发 OOM 状况的风险
* **准确的迁移容量估算** ——您分配多少，目标主机就需要多少

### 容量规划最佳实践

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

{% hint style="success" %}
**虚拟机规格优化**

由于 VergeOS 会分配全部内存量，因此虚拟机内存规格优化比在使用气球技术的平台上更重要。应从保守的分配量开始，仅当客户机监控显示持续高使用率时才增加。
{% endhint %}

***

## SEL 噪声（误报 IPMI 日志）

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

### 了解 SEL

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

### 通过 API 过滤 SEL 噪声

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

1. 导航到 **系统 → API 文档**
2. 找到 **settings** 表并将其展开
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 共享，连接间歇性断开，或者性能无法使用。

**解决方法——通过以下方式强制使用 SMB3： `nsmb.conf`:**

1. 打开终端并创建或编辑 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 兼容性，请添加面向 macOS 的指令（包括 `vfs objects = fruit streams_xattr` 以及相关的 `fruit:*` 选项）到 **高级配置选项** 中的 NAS CIFS 设置（**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 虚拟机会成为吞吐量瓶颈

***

## 安装故障排除

### 启动问题

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

**解决方法：**

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

### 网络配置不匹配

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

**解决方法：**

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

### 存储控制器 JBOD 模式

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

**解决方法：**

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

### 辅助节点加入失败

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

**解决方法：**

1. 确认您选择了 **“否”** 当系统询问这是否为新安装时（对于辅助节点）
2. 确认您输入了 **主控制器的管理员凭据** 正确无误
3. 确保两个节点位于同一网络中且可以互相访问（检查交换机端口 VLAN 分配）
4. 与主控制器的加密设置完全匹配
5. 与主控制器的驱动器层分配匹配
6. 如果辅助节点已启动但在主 UI 中不可见，请检查核心网络配置并验证节点之间的交换机连接

***

## 存储问题

### 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. 通过以下位置查看驱动器 SMART 数据： **基础架构 → 节点 → \[节点] → 诊断 → S.M.A.R.T. 诊断测试** 以检查磨损级别和驱动器健康指标
3. 如需立即缓解，请识别并删除不必要的快照或未使用的虚拟机驱动器
4. 如需长期解决，请添加驱动器或节点以扩展该层——请参阅 vSAN 扩容流程

以下临界点是 **培训指导** ，用于规划，并非文档化阈值。文档化的值是 **80% 订阅高使用率默认值** （由预置的 vSAN/存储层高使用率警报使用）以及 **90% `sync_max_usage`** 阈值，达到该阈值时 vSAN 会限制写入并将该层标记为 `outofspace`.

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

***

## 故障排查决策树

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

### 1. 确定问题范围

该问题是影响一台虚拟机、一个网络、一个节点，还是整个系统？确定范围将决定从哪种诊断工具开始。

### 2. 使用组件诊断

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

### 3. 检查系统日志

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

### 4. 携带数据升级处理

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


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
