Nexthop 详细部署教程

Nexthop 是专为 Omarchy 桌面环境设计的一款互联网质量监控插件。它能实时、清晰地分辨网络延迟或故障是出在你的 Wi-Fi 还是 宽带运营商 (ISP) 上，并通过直观的界面和评分给出答案。

本教程将指导您在 Omarchy 中完成 Nexthop 的安装、配置与使用。

1. 准备工作

1.1 核心要求

Omarchy 桌面环境：Nexthop 是 Omarchy 的插件，无法独立运行。您需要先安装 Omarchy。
系统依赖：确保系统中已安装以下命令行工具（在标准 Omarchy 系统中通常已具备）：
- python3
- ping
- curl
- ss
可选依赖（用于增强功能）：
- iw：用于显示详细的 Wi-Fi 信息。
- speedtest (Ookla)：用于执行按需的峰值网速测试（若无，则自动回退到 Cloudflare 或 fast.com 的测试）。

1.2 了解工作原理

Nexthop 由两部分组成：

QML 插件：负责在 Omarchy 的面板和设置界面中呈现可视化内容。
后台守护进程 (nexthopd)：一个 Python 3 守护进程，负责实际测量网络质量、记录数据并生成状态文件。它运行在用户空间，无需 root 权限。

2. 安装 Nexthop 插件

安装过程通过 Omarchy 内置的插件管理器完成，非常简单。

2.1 添加并启用插件

打开终端，执行以下命令：

1	omarchy plugin add https://github.com/x3me/omarchy-nexthop.git --enable

此命令会自动下载、安装并立即启用 Nexthop 插件。

2.2 验证安装

安装成功后，您应该会在 Omarchy 的顶栏（Bar）中看到 Nexthop 的指示器（一个数字或小图表）。如果未立即显示，可以尝试重启 Omarchy 或执行 omarchy plugin list 确认插件状态。

3. 初始配置与使用

3.1 设置监控锚点 (Anchor)

Nexthop 需要一个稳定的互联网目标（“锚点”）来测量网络延迟。默认使用 1.1.1.1 (Cloudflare DNS)。您可以在插件设置中更改：

右键点击顶栏的 Nexthop 指示器，或通过 Omarchy 的插件管理界面进入 Setup > Plugins > Nexthop。
在 Anchor 字段中，您可以输入任何可靠的 IP 地址或域名。

3.2 理解界面

点击顶栏的 Nexthop 指示器，打开主面板。面板包含多个标签页，您可以使用键盘的 方向键 或数字键 1-6 快速切换：

Overview (概览)：最核心的视图。用图形化方式展示“本机 → 路由器”和“路由器 → 互联网”两条链路的实时延迟，直观指出哪条链路是当前问题的根源。
Latency (延迟)：显示两条链路延迟的详细历史图表和统计数据（最佳/典型/最差）。
Speed (速度)：显示通过小型内容检查（每小时约14MB）得出的速度评分。点击“Run peak test”按钮可执行一次完整的网速测试。
Wi-Fi：详细显示 Wi-Fi 信号强度、信道、速率以及关键的链路事件（如漫游、被踢出、掉线等）。
Apps (应用)：显示当前占用网络连接的应用程序列表及其流量情况。
Events (事件)：记录所有网络中断事件，包括开始时间、持续时长和故障所在链路。点击 Copy report 可生成一份适合提交给运营商客服的纯文本报告。

3.3 核心指标：体验指数 (0-100)

顶栏显示的核心数字是一个综合了 响应性、可靠性 和速度的体验指数。颜色编码让状态一目了然：

绿色：一切正常。
黄色/橙色：体验下降，可能存在问题。
红色：正在发生中断或严重性能问题。

4. 高级配置与维护

4.1 可选：安装系统级守护进程 (Systemd Service)

为了让网络监控在 Omarchy 未运行时（例如仅启动图形界面前）也能持续进行，可以安装可选的 systemd 服务。

查看项目提供的 nexthopd.service 文件内容。
将其复制到用户的 systemd 目录：~/.config/systemd/user/nexthopd.service。
启用并启动服务：
1
systemctl --user enable --now nexthopd

4.2 使用命令行接口 (CLI)

Nexthop 的后台守护进程提供了命令行接口，方便脚本化操作或查看原始数据。在项目目录的 bin/ 下：

bin/nexthop live              # 查看当前实时数据 (JSON格式)
bin/nexthop query --window 24h # 查询过去24小时的历史数据
bin/nexthop events            # 查看事件日志
bin/nexthop report            # 生成文本报告

4.3 更新插件

Nexthop 会每天检查一次是否有新版本，并在顶栏有提示。更新通过 Omarchy 的命令完成：

1	omarchy plugin update

更新前会显示变更内容，由您确认是否应用。

5. 卸载与清理

如果您需要移除 Nexthop，执行以下命令：

1	omarchy plugin remove io.github.x3me.nexthop

可选清理：删除插件遗留的测量历史数据和状态文件：

1	rm -rf ~/.local/state/nexthop/

如果您安装了可选的 systemd 服务，还需执行：

1 2	systemctl --user disable --now nexthopd rm ~/.config/systemd/user/nexthopd.service

6. 故障排查

面板不显示数据：
- 检查后台守护进程是否运行：ps aux | grep nexthopd。
- 查看日志：journalctl --user -u nexthopd（如果使用了 systemd）或直接运行 python3 -m nexthopd 观察前台输出。
“Anchor” 无法访问：您设置的锚点可能暂时不可达。尝试在设置中更换为 1.1.1.1 或 8.8.8.8 等公认的稳定地址。
速度测试失败：确认网络连接正常，并且 curl 命令可用。如果使用 Ookla 的 speedtest，请确保其已正确安装并在 PATH 中。
资源占用过高：在设置中调整探测间隔（默认500ms）或禁用每小时的内容检查。