GlobalTrace

GlobalTrace 是一个 Globalping x NextTrace 的开源项目，借助 Globalping 遍布全球的 Probe 发起路由追踪，并结合 NextTrace 骨干网 IP 数据库增强地理位置与网络归属信息。

技术栈

• Frontend：React + Vite + TypeScript + MapLibre。
• UI：Radix UI、lucide-react、liquid-glass-react。
• Worker：Hono on Cloudflare Workers Static Assets。
• 测量来源：Globalping type: "mtr" measurement。
• 增强数据：Worker 按 Globalping measurement ID 拉取可信结果后调用 nxtrace API v4 batch GeoIP/ASN/whois；用户提供个人 NextTrace API Token 后，新建诊断可由浏览器直连 batch API。

架构

GlobalTrace 是一个 Cloudflare Worker 托管的 React SPA + API Worker。/api/* 先进入 Hono Worker，其他路径由 Cloudflare Workers Static Assets 返回 Vite 构建出的 SPA 静态资源。

flowchart LR
  Browser["Browser React SPA"] -->|static assets| Assets["Cloudflare Workers Static Assets"]
  Browser -->|GET /api/config /probes /trace| Worker["Hono Worker API"]
  Browser -->|POST /v1/measurements| Globalping["Globalping API"]
  Browser -->|poll measurement| Globalping
  Browser -->|optional personal token| BrowserNxtrace["api.nxtrace.org /v4/ipGeo/batch"]
  Worker -->|read measurement by ID| Globalping
  Worker -->|server token enrichment| Nxtrace["nxtrace API v4 batch"]
  Worker --> Cache["Cloudflare Cache API"]

Loading

诊断创建由浏览器直接调用 Globalping；Worker 不代理创建 measurement。Worker 负责可信读取 measurement、转换 MTR 结果、调用 nxtrace enrichment、返回分享结果缓存，以及服务 /api/config、/api/probes、背景图等站点 API。

用户提供的 Globalping / NextTrace Token 只保存在当前浏览器会话或用户明确记住的本机存储中。Worker secret 只用于服务端 NXTRACE_API_V4_TOKEN，项目不使用 KV、D1、R2、Durable Object 或服务端报告存储。

本地运行

npm install
npm run dev

npm run dev 会先构建 Vite assets，再启动 wrangler dev --local --assets dist。同一个 Worker 处理 /api/* 并服务 SPA 静态资源。

只调前端界面时可用：

npm run dev:frontend

核心 API

• GET /api/config：返回 map style URL。
• GET /api/probes：返回当前在线 Globalping probes。
• POST /api/trace/enrich：接收 Globalping measurement ID，Worker 拉取对应 MTR measurement 后返回 trace 结果与 enrichment。
• GET /api/trace/:measurementId：只读缓存查询；命中已完成结果时返回 JSON，否则返回 204。

nxtrace enrichment 合约

Worker 调用 nxtrace batch 接口：

{"ips":["1.1.1.1","8.8.8.8"]}

接口要求：

• 路径：POST /v4/ipGeo/batch。
• 输入：唯一公网 hop IP 列表。
• 批量大小：最多 64 个唯一 IP。
• 响应：按请求顺序返回 results。
• 失败处理：batch chunk 失败会写入 enrichment error；当前实现不回退到单 IP GET /v4/ipGeo。

个人 NextTrace API Token

高级参数里可以保存个人 NextTrace API Token。默认仅保存在当前浏览器会话；勾选“记住到本机”后才写入 localStorage。该 Token 不会发送给 Globalping 或 GlobalTrace Worker。

保存后，新建诊断会由浏览器直接请求 https://api.nxtrace.org/v4/ipGeo/batch，并通过 X-NextTrace-Token 传递该 Token。打开分享结果默认走 Worker enrichment，不会自动消耗浏览器里保存的个人 Token。

缓存和存储边界

• 完成态 enriched trace 使用 Worker Cache API 缓存 7 天；Cloudflare 仍可能提前驱逐缓存。
• 个人 NextTrace API Token 只保存在浏览器会话或用户明确记住的本机存储中，不进入 Worker Cache、日志或服务端配置。
• 项目不使用 KV、D1、R2、Durable Object 或服务端报告存储。
• 分享链接依赖 measurement ID 和缓存结果；不会把报告持久写入数据库。

Cloudflare 配置

wrangler.jsonc 是公开配置入口，适合本地开发和通用 Worker 配置：

• name: globaltrace
• main: src/worker/index.ts
• assets.directory: ./dist
• assets.binding: ASSETS
• assets.not_found_handling: single-page-application
• assets.run_worker_first: /api/*

公开配置不包含 Cloudflare account 或生产 hostname/routes。生产部署复制示例文件后填写私有值：

cp wrangler.private.example.jsonc wrangler.private.jsonc

wrangler.private.jsonc 被 Git ignore，用于保存部署标识和生产 Worker vars。

默认生产部署由 Cloudflare Workers Builds 执行；GitHub Actions 只做验证，不再部署。

Cloudflare Build 配置：

• Build command: npm run build
• Deploy command: node scripts/write-ci-wrangler-config.mjs && npx wrangler deploy --config .wrangler-ci.jsonc
• Build variables: NODE_VERSION=24、CLOUDFLARE_ACCOUNT_ID、GLOBALTRACE_HOSTNAME

生产必需 secret 仍只写入 Cloudflare Worker secrets：

npx wrangler secret put --config wrangler.private.jsonc NXTRACE_API_V4_TOKEN

不要把真实 secret 写入 Git、测试 fixture、文档示例或 frontend VITE_* 值。

迁移到 Cloudflare Builds 后，GitHub repository secrets 中可删除：CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID、GLOBALTRACE_HOSTNAME、NXTRACE_API_V4_TOKEN。

手动生产部署保留为 fallback：

npm run deploy:private

验证

npm run typecheck
npm test
npm run build
npm run smoke

npm run smoke 包含 browser smoke 和 Worker Static Assets smoke。必要时可拆开运行：

npm run smoke:browser
npm run smoke:worker

可选 live smoke：

NXTRACE_API_V4_TOKEN=... GLOBALTRACE_LIVE_SMOKE=1 npm run smoke:live

live smoke 会创建一个匿名 Globalping measurement，并校验 measurement ID、trace shape 和 enrichment status。

部署

完整提交和部署流程见 docs/deployment.md。

License

GlobalTrace is licensed under GPL-3.0-or-later. See LICENSE.