NextTrace Deploy 模式验证指南:启动检查、认证冒烟测试与 CLI 回归覆盖
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)
验证文档要求启动时检查以下四项:
- stdout 打印 Web 控制台监听 URL:
onReady回调中输出 "启动 NextTrace Web 控制台,监听地址: http://..."(cmd.go); --mcp启用时 stdout 打印 MCP 端点:格式为<访问地址>/mcp(mcpEndpointURL,cmd.go);- 外部监听且未手动提供 token 时,打印自动生成的 token;
- 手动传入 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 个工具。验证文档要求依次调用四个:
nexttrace_capabilities:列出全部 MCP 工具与参数支持边界,是 Agent 工作流的第一步(见 SKILL.md 的 Workflow 第 1 步);nexttrace_traceroute,参数{"target":"example.com","protocol":"icmp"}:运行本地 ICMP traceroute 并返回结构化逐跳结果(mcp.go);nexttrace_globalping_limits:返回 Globalping 当前速率与配额限制(mcp.go);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 行为为证据。
七、验证边界:什么不能当作"通过"
文档最后给出三条重要的判读准则,直接关系回归结论的可靠性:
- 权限门控测试在普通
go test中会跳过,跳过不等于通过;必须核对对应 commit 的 CI 工作流日志与产物,确认原生环境下的验收记录。 - 交叉编译、模拟回调和成功的 socket 初始化,都不能证明报文内容正确或远端可达——例如 s390x 仅编译通过,不等于运行时行为被验证。
- Unix 下 MTR JSON 回归失败会保留完整 Python traceback 在
<case>.json.assert文件中,summary 中仅给简短失败摘要;排查时需打开 assert 文件定位真正失败点。
这三点把"本地绿"与"原生验收"明确区分开,是团队在 scripts/regression 脚本与 CI 工作流之外约定的验收纪律。
八、完整验证流程速查
综合 validation.md 与 SKILL.md,一次完整验证可按以下顺序执行:
- 启动 loopback 无令牌实例,确认 stdout 打印监听 URL 与 MCP 端点;
- 启动外部监听实例(
--listen 0.0.0.0:1080),确认自动生成 token 被打印、手动 token 不回显; - 用三条
curl对/api/options做认证冒烟,确认 Bearer 与X-NextTrace-Token均可鉴权、query token 被拒绝; - 用 MCP 客户端调用
nexttrace_capabilities→nexttrace_traceroute→nexttrace_globalping_limits→nexttrace_globalping_trace(小locations[]); - 运行
go build ./...、go test ./...、node --test server/web/assets/*.test.cjs; - 按第六节矩阵逐项核对特性回归,权限相关结论只认原生 CI 证据。
通过以上步骤,即可对一次 NextTrace Deploy 部署完成从进程启动、鉴权边界到 MCP 契约与 CLI 回归的端到端验证。