NextTrace Deploy 模式验证指南:启动检查、认证冒烟测试与 CLI 回归覆盖

原创2026-09-25 19:01:391,623 阅读
文章标签:网络CLIMCP 服务后端可观测性

NextTrace Deploy 模式验证指南:启动检查、认证冒烟测试与 CLI 回归覆盖

导读

本文围绕 NextTrace 开源可视化路由追踪工具(CLI)的 --deploy Web 控制台部署模式的验证体系展开,完整覆盖启动检查、鉴权冒烟测试、MCP 端点冒烟测试、仓库级自动化测试命令,以及 MTR 记录/回放、Doctor、fwmark、TOS 等 CLI 特性的回归覆盖矩阵。读完本文,你将掌握如何在本机与外网两种场景下启动并校验 NextTrace Deploy 服务,知道哪些测试必须看原生 CI 证据而非本地跳过结果,并能依据 validation.md 的检查清单对一次部署做端到端验证。

一、验证对象:Deploy 模式是什么

--deploy 是 NextTrace 启动 Gin 驱动的 Web 控制台的部署子模式,只在 full flavor(无 flavor_tiny/flavor_ntr 构建标签)下可用,参见 flavor_full.go 中 enableWebUI = true 的定义;nexttrace-tiny 与 ntr 二进制会直接返回 "WebUI (--deploy) is not available" 错误,见 deploy_disabled.go。

部署模式的核心能力由 server/server.go 承载:

  • 默认监听地址 :1080(defaultListenAddr);
  • 当 EnableMCP 为真时注册 /mcp 的 GET/POST/DELETE 路由(server.go);
  • 鉴权由 deployAuthMiddleware 统一施加到除 /auth/login 与 OPTIONS 之外的所有路径(auth.go);
  • HTTP 服务器设置了 ReadHeaderTimeout: 5s、ReadTimeout: 30s、IdleTimeout: 60s,而 WriteTimeout: 0,以支持 MTR/MCP 长任务流式输出(server.go)。

验证文档(即 validation.md)的目标,就是围绕这一模式给出可重复执行的启动检查、鉴权冒烟与回归覆盖清单。

二、启动验证:两种监听场景的预期行为

场景 1:loopback 无令牌(默认)

nexttrace --deploy --mcp

该命令等效于监听 127.0.0.1:1080(或仅 IPv6 环境下的 <a href="https://link.gitcode.com/i/1251d19da1d3f1db020cc20e05e00d14" target="_blank">::1]:1080,逻辑见 [cmd/cmd.go 的 defaultLocalListenAddr)。loopback 监听默认免令牌,因此不会打印 token。

场景 2:外部监听 + 手动令牌

nexttrace --deploy --mcp --listen 0.0.0.0:1080 --deploy-token "$TOKEN"

当监听地址既不是 loopback 也不是 localhost 时,resolveDeployAuthPlan 与 deployListenRequiresToken 会强制启用鉴权:若未提供 --deploy-token,则由 generateDeployToken 用 crypto/rand 生成 32 字节随机数并做 base64.RawURLEncoding 编码,打印到 stdout。手动传入的 token 则不会被回显(见下节)。

预期输出(Expected)

验证文档要求启动时检查以下四项:

  1. stdout 打印 Web 控制台监听 URL:onReady 回调中输出 "启动 NextTrace Web 控制台,监听地址: http://..."(cmd.go);
  2. --mcp 启用时 stdout 打印 MCP 端点:格式为 <访问地址>/mcp(mcpEndpointURL,cmd.go);
  3. 外部监听且未手动提供 token 时,打印自动生成的 token;
  4. 手动传入 token 时不回显 token:authPlan.AutoGenerated 为假时只打印 "Deploy token 鉴权已启用"。

另外注意两条约束(源码与文档一致):--mcp 必须与 --deploy 同时使用(validateDeployMCPMode,cmd.go);非本机监听时文档建议显式设置 --listen,因为默认 loopback 地址外部不可达。启动模式还可用环境变量 NEXTTRACE_DEPLOY_ADDR / NEXTTRACE_DEPLOY_TOKEN 覆盖参数(cmd.go)。

三、认证冒烟检查:三种合法携带令牌的方式

curl -i http://127.0.0.1:1080/api/options
curl -i -H "Authorization: Bearer $TOKEN" http://127.0.0.1:1080/api/options
curl -i -H "X-NextTrace-Token: $TOKEN" http://127.0.0.1:1080/api/options

无令牌请求

第一条命令在鉴权未启用(loopback 默认)时返回 200;在鉴权启用时返回 401 {"error":"deploy token required"}(auth.go)。

两种认证头

deployRequestAuthorized 依次接受:

  • Authorization: Bearer <token>(bearerToken 解析,auth.go);
  • X-NextTrace-Token: <token>;
  • 浏览器 WebUI 登录后写入的 HttpOnly Cookie nexttrace_deploy_auth(值为 token 的 SHA-256 派生,auth.go)。

token 比较使用 subtle.ConstantTimeCompare 做常数时间比对,避免时序侧信道(auth.go);认证测试同时覆盖了这两种头的等价性,见 auth_test.go。

禁止在 URL 查询串携带 token

文档明确要求 "Do not use query token URLs"。这与 auth_test.go 中的 TestDeployAuthDoesNotAcceptQueryToken 完全对应——即使 URL 带 ?token=secret,鉴权中间件也只会检查 Header 与 Cookie,查询参数不会被认可为有效凭证,避免 token 泄漏进访问日志与代理转发记录。

四、MCP 冒烟检查:四步工具调用

将 MCP 客户端指向:

http://127.0.0.1:1080/mcp

NextTrace 的 MCP 端点由 server/mcp.go 实现:基于 modelcontextprotocol/go-sdk 构建 Streamable HTTP 处理器(Stateless: true、JSONResponse: true、会话超时 5 分钟),并注册了 11 个工具。验证文档要求依次调用四个:

  1. nexttrace_capabilities:列出全部 MCP 工具与参数支持边界,是 Agent 工作流的第一步(见 SKILL.md 的 Workflow 第 1 步);
  2. nexttrace_traceroute,参数 {"target":"example.com","protocol":"icmp"}:运行本地 ICMP traceroute 并返回结构化逐跳结果(mcp.go);
  3. nexttrace_globalping_limits:返回 Globalping 当前速率与配额限制(mcp.go);
  4. nexttrace_globalping_trace,使用一个较小的 locations[] 集合:发起多地点 Globalping 测量,控制探测点数量以避免超出配额。

其余工具(nexttrace_mtr_report、nexttrace_mtr_raw、nexttrace_mtu_trace、nexttrace_speed_test、nexttrace_annotate_ips、nexttrace_geo_lookup、nexttrace_globalping_get_measurement)虽不在冒烟清单内,但注册逻辑与上述一致(mcp.go)。

server/mcp_test.go 中的 recordingMCPService 通过记录每次调用的名称与输入来验证工具注册与参数透传(mcp_test.go),是本地无网络环境下验证 MCP 契约的正确方式。冒烟检查还建议优先消费工具的 structuredContent 字段,仅把文本内容作为回退。

五、仓库级测试命令

go build ./...
go test ./...
node --test server/web/assets/*.test.cjs
  • go build ./... 验证全仓库可编译(含各 flavor 构建标签分支);
  • go test ./... 跑单元测试;
  • node --test server/web/assets/*.test.cjs 运行前端资产(app.js、mtr_agg.js、trace_form.js、trace_reason.js)的 Node 测试(对应 server/web/assets 下的 *.test.cjs 文件)。

注意:本地 go test ./... 会自动跳过权限门控(privilege-gated)测试,它们需要 root/管理员权限(raw socket、fwmark 等),详见下一节。

六、CLI 特性回归覆盖矩阵

验证文档以表格形式给出各 CLI 特性的本地检查命令与原生 CI 证据,是文章最核心的覆盖清单:

特性 本地检查 原生 CI 证据
MTR JSON 排序、错误阶段与端口 go test ./cmd 测试 full/tiny/ntr 三种 flavor;Runtime Regression CI 校验有限流(finite streams)与报告
记录、reducer 校验与恢复 go test ./internal/mtrsession ./trace ./cmd 测试工作流;录制的会话在 PTY / Windows ConPTY 上离线回放
回放消毒、seek 与文本列 go test ./cmd ./printer scripts/test_mtr_session_pty.py 与 scripts/test_mtr_columns_pty.py
Doctor 路由/后端检查 go test ./internal/doctor ./trace/internal ./cmd 测试工作流的 loopback 路由与特权后端冒烟;Windows NO_INSTALL 检查
Linux fwmark 与源约束 go test ./internal/routeprobe ./trace ./trace/internal ./cmd Linux fwmark 工作流:原生 mark、权限失败、双栈双出口抓包
TOS、零恢复与引擎替换 go test ./trace ./trace/internal TOS 报文验收:Linux/macOS/Windows amd64 全字节双栈抓包;Linux/macOS 还要求 ICMP/TCP/UDP 双协议族的真实 closed-socket 发送循环失败
Linux 旧版 socketcall 指针生命周期 交叉编译并 vet internal/routeprobe 的 386/s390x Linux fwmark 工作流在 amd64 与 386 上执行路由测试;s390x 仅编译

矩阵背后的源码支撑

  • MTR 记录与 reducer 校验:internal/mtrsession/validate.go 实现了严格的记录状态机——seq 必须严格递增、起始记录必须匹配头部时间戳、有效参数范围(MaxHops 1-255、TOS 0-255 等)、响应必须对应成功探测且 IP 合法、max_hops 结束前必须满足每跳完成数(validate.go)。这正是 "recording, reducer validation and recovery" 本地测试的验证主体。
  • Doctor 检查:internal/doctor/ 按平台拆分路由实现(route_linux.go、route_darwin.go、route_windows.go),验证文档中的 loopback 路由检查即针对这些实现。
  • fwmark 与 TOS:internal/routeprobe/ 与 trace/internal/tos_*、fwmark_* 分别承载 Linux 网络约束与 8 位 TOS 字节设置,原生 CI 以抓包与真实 socket 行为为证据。

七、验证边界:什么不能当作"通过"

文档最后给出三条重要的判读准则,直接关系回归结论的可靠性:

  1. 权限门控测试在普通 go test 中会跳过,跳过不等于通过;必须核对对应 commit 的 CI 工作流日志与产物,确认原生环境下的验收记录。
  2. 交叉编译、模拟回调和成功的 socket 初始化,都不能证明报文内容正确或远端可达——例如 s390x 仅编译通过,不等于运行时行为被验证。
  3. Unix 下 MTR JSON 回归失败会保留完整 Python traceback 在 <case>.json.assert 文件中,summary 中仅给简短失败摘要;排查时需打开 assert 文件定位真正失败点。

这三点把"本地绿"与"原生验收"明确区分开,是团队在 scripts/regression 脚本与 CI 工作流之外约定的验收纪律。

八、完整验证流程速查

综合 validation.md 与 SKILL.md,一次完整验证可按以下顺序执行:

  1. 启动 loopback 无令牌实例,确认 stdout 打印监听 URL 与 MCP 端点;
  2. 启动外部监听实例(--listen 0.0.0.0:1080),确认自动生成 token 被打印、手动 token 不回显;
  3. 用三条 curl 对 /api/options 做认证冒烟,确认 Bearer 与 X-NextTrace-Token 均可鉴权、query token 被拒绝;
  4. 用 MCP 客户端调用 nexttrace_capabilities → nexttrace_traceroute → nexttrace_globalping_limits → nexttrace_globalping_trace(小 locations[]);
  5. 运行 go build ./...、go test ./...、node --test server/web/assets/*.test.cjs;
  6. 按第六节矩阵逐项核对特性回归,权限相关结论只认原生 CI 证据。

通过以上步骤,即可对一次 NextTrace Deploy 部署完成从进程启动、鉴权边界到 MCP 契约与 CLI 回归的端到端验证。

登录后查看全文
NTrace-core