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

# Agent 扫描故障排查

> 当 Agent 已安装但矿机数据没有出现时，按顺序检查常见问题

当 Agent 已安装但矿机数据没有出现时，建议按下面的顺序排查。

## 1. 先确认 Agent 已安装且在线

在 Nonce 中确认：

* 当前矿场已经绑定 Agent
* Agent 状态为已安装
* Agent 当前在线

如果刚完成安装，先等待几秒并刷新一次页面。

## 2. 确认扫描任务是否真的执行了

打开矿场任务列表，找到对应的扫描任务。

* 如果任务还在 pending，继续等待其完成
* 如果任务失败，先看任务输出或错误信息
* 如果根本没有扫描任务，说明请求可能没有提交成功

## 3. 检查 IP 段是否配置正确

Agent 安装成功，不代表配置的扫描范围就一定覆盖了矿机所在网段。

常见问题包括：

* 子网写错
* 扫的是管理网而不是矿机网
* 扫描范围过大，导致定位困难
* 新移动的矿机已经切到新的 VLAN 或子网

## 4. 检查 Agent 主机上的矿机密码配置

如果矿机密码已从默认值修改，请先阅读 FAQ 中的说明并按其中步骤更新 Agent 配置：

* [如果我曾修改过矿机密码，Nonce Agent 需要作何变更？](/zh/user-guide/faq#custom-miner-password)

## 5. 直接在 Agent 主机上检查服务状态

常用命令：

```bash theme={null}
sudo systemctl status nonce-agent
nonce-agent summarize-ip-list
nonce-agent summarize-miner-scan-report -v
nonce-agent get-miner-meta <miner-ip> --validate --no-cache --raw --json
```

这些命令可以帮助回答以下问题：

* 服务是否正在运行
* 当前监控列表里有哪些 IP
* 最近几次扫描发生了什么
* Agent 在本机上是否能直接抓到某台矿机的数据

## 6. 查看 Agent 本地报告文件

Agent 会把扫描与抓取结果写到本地报告中。很多时候，这是定位问题最快的入口。

典型路径：

```bash theme={null}
~/.nonce-agent/reports/MINERS_SCAN_REPORT/
~/.nonce-agent/reports/MINERS_FETCH_REPORT/failed_ips.txt
~/.nonce-agent/reports/MINERS_FETCH_REPORT/succeed_ips.txt
```

这些文件通常能告诉你：

* 哪些 IP 被扫描过
* 哪些 IP 被跳过了
* 哪些矿机被成功发现
* 哪些 IP 在抓取元数据时失败

## 7. 如果矿机曾经出现过，后来又不更新了

这通常意味着发生了以下一种情况：

* 矿机当前不可达
* 矿机详情抓取持续失败
* 矿机已经不在预期的 IP 段里
* 后端因为长时间没收到新数据，已经把这台矿机标记为过期（stale）

这时建议对受影响子网重新做一次更聚焦的手动扫描，并直接测试单台矿机：

```bash theme={null}
nonce-agent get-miner-meta <miner-ip> --validate --no-cache --raw --json
```

## 8. 如果任务成功了，但 Miners 页面仍然像没刷新

这种情况在当前实现里是可能发生的。

原因通常是：

* 后端已经处理完上传
* 但当前页面还在显示缓存数据

正式进入更深层排查前，先做这几步：

* 刷新 Miners 页面
* 重新打开矿场页面
* 打开任务详情确认任务已完成
* 如果你依赖的是后台定时刷新而不是手动扫描，再等待到下一个常规刷新窗口

## 9. 如果矿机被手工删除了，为什么不会重新出现在列表内

如果矿机之前被手工从列表中删除，系统不会自动把它加回列表。

需要重新发起一次扫描，等 Agent 再次发现并上报这台矿机后，它才会重新出现在矿机列表中。

## 10. 为什么检查了上述所有问题，矿机仍然没有出现在列表内

请检查 [支持的矿机与固件](/zh/user-guide/supported-miners-and-firmware)。

如果当前矿机型号或固件版本不在支持列表内，Agent 可能无法完成识别或数据采集，因此不会正常出现在列表中。

## 什么时候应该升级排查

如果出现以下情况，建议收集日志并让团队进一步介入：

* Agent 在线，但所有扫描任务都失败
* 对明确可达的矿机执行 `get-miner-meta` 仍然失败
* 扫描任务成功，但矿机数据始终没有被系统接收
* 同一网段里其他矿机都正常，只有某一品牌或某一型号持续失败