> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plasma.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

> 常见问题、诊断与解决流程

本指南概述了影响非验证者节点的常见问题，并提供实用的诊断与解决步骤。快速排障对维持 RPC 可用性以及可靠访问稳定币交易数据至关重要。

<Note>
  大多数问题源于系统资源限制、与共识端点的网络连接或配置错误。请始终先做基本健康检查，再调查 Plasma 特有的边缘情况。
</Note>

## 同步问题

<AccordionGroup>
  <Accordion title="节点落后">
    如果你的节点落后于网络头部：

    * **检查系统负载**：CPU、内存和 I/O 必须足以支撑 Plasma 高频的区块生产。
    * **检查共识端点延迟**：高延迟会影响区块摄入速度。
    * **监控数据库性能**：缓慢的查询或锁争用会拖慢同步。

    **诊断：** 检查 `block_height` 与网络头部、单个区块的状态应用时间，以及到每个共识端点的延迟。
  </Accordion>

  <Accordion title="同步完全停滞">
    如果同步停止：

    * **检查磁盘空间**：磁盘满会阻止数据库写入。
    * **验证端点连通性**：确保 DNS 解析、防火墙规则和路由没有阻挡共识流量。
    * **检查容器资源限制**：内存或 CPU 不足会导致同步进程崩溃。

    **Plasma 专项检查：** 验证端点可达性、有效的 JWT 令牌/许可名单状态，以及非验证者节点版本兼容性。
  </Accordion>

  <Accordion title="对等连接性差">
    与共识端点的连接有限或不稳定，会降低 RPC 消费者的数据新鲜度。

    **检查：** IP 限制或路由策略、端点连接数与正常运行时间，以及跨多个端点的故障切换行为。

    **关键指标：** 活跃连接数、断线率以及区块到达延迟。
  </Accordion>
</AccordionGroup>

## 网络连接

### 端口与防火墙访问

确保以下两类所需端口均已开放：

* **共识通信**
* **面向应用的 RPC 服务**

常见阻塞来源包括企业防火墙、云安全组或错误配置的 iptables 规则。

**验证：**

* 容器内外的端口可达性
* 允许出站的共识同步流量

### DNS 故障

未解析的共识域名会破坏同步。

* 确认所有 Plasma 服务域名的 DNS 解析
* 监控解析器延迟与可靠性
* 根据需要添加备用解析器

### 代理与 NAT 问题

复杂的网络环境（VPN、代理、NAT）可能干扰：

* 共识同步
* RPC 入站访问

**核查：**

* 代理认证规则
* 入站 RPC 的 NAT 端口转发
* 通往 Plasma 基础设施的路由路径

## 配置错误

<AccordionGroup>
  <Accordion title="无效的非验证者配置">
    启动错误常由错误或缺失的共识端点、格式错误的 URL 或 JWT 令牌，或已废弃的标志引起。

    **检查日志中的：** 配置解析错误、chain ID 不匹配以及未知标志或选项。
  </Accordion>

  <Accordion title="Docker 问题">
    配置错误的容器可能会阻止正常运行。

    **校验：** 用于数据库持久化的卷挂载、容器内的网络访问、资源限制（CPU、内存）以及镜像版本兼容性。
  </Accordion>

  <Accordion title="环境变量冲突">
    冲突或顺序错误的环境变量可能覆盖你期望的设置。

    **核查：** 共识端点 URL 与令牌、网络与 chain ID，以及功能标志（例如自定义 gas 支持）。记录环境变量的使用，避免不同部署之间的漂移。
  </Accordion>
</AccordionGroup>

## 资源限制

### 磁盘空间

监控磁盘使用增长，来源包括：

* 区块链数据
* 日志和临时文件

**最佳实践：**

* 实施日志轮转
* 调度清理任务
* 监控使用告警

### 文件描述符

较低的 ulimit 可能影响：

* 共识连接
* RPC 会话

通过 `ulimit`、systemd 或容器运行时配置增加文件描述符限制。

## 诊断

### 日志分析

使用日志来追踪：

* 同步进度
* RPC 错误
* 共识连接情况
* 资源相关崩溃

**最佳实践：**

* **共识同步日志**：跟踪与 Plasma 的连接与同步进度。
* **交易处理日志**：监控交易处理与错误。
* **RPC 请求日志**：分析支付应用的请求模式与性能。
* **资源利用率日志**：识别影响支付处理的瓶颈。

### 性能分析

对非验证者工作负载进行性能分析，以识别以下瓶颈：

* RPC 性能
* 数据库查询延迟
* 共识状态应用

**重点关注：**

* 余额查询吞吐
* 转账确认延迟
* 负载下的资源使用

维护基线并跟踪升级或配置更改后的变化。

系统化的故障排查与可观测性对可靠的非验证者节点运营至关重要。完善的诊断、日志记录与配置卫生可确保稳定的性能和正常运行时间，以支持稳定币基础设施的 RPC 服务。