uvscope:Web 调试界的瑞士军刀

uvscope:Web 调试界的瑞士军刀

摘要:uvscope 是 Web 调试界的瑞士军刀------HTTP、WebSocket、TCP、UDP、TLS、SOAP 全部收进一个 Vue 3 控制台,背后是 C++ 守护进程统一管理事件循环、SQLite 存储、认证和所有出站流量。自带反向代理、进程监护和证书管理,无云账号、无遥测。

调试一个横跨 HTTP → WebSocket → 裸 TCP 的请求,通常要在四五个工具之间来回切换:REST 客户端、Socket 客户端、nc、代理、终端。每切一次就丢一次上下文------header 在这边、frame 在那边、日志又在别处。

uvscope 就是想把这一摞工具收拢到一处------一句话,它是 Web 调试界的瑞士军刀。它把 HTTP、WebSocket、TCP、UDP、TLS、SOAP/WSDL 以及托管反向代理,统一放在一个 Vue 3 控制平面后面;底层是一个 C++ 守护进程,独占事件循环、SQLite 存储、认证和全部出站网络流量。浏览器只负责渲染状态、下发命令。

为什么还要再造一个调试工具?

大多数工具做到"请求/响应"就停了。uvscope 围绕的是整个握手过程:

• 一个工作台覆盖所有协议 ------ HTTP/1.1 与 HTTP/2、WebSocket、裸 TCP/UDP、X.509 与 WSDL 驱动的 SOAP,共用同一套历史记录、遥测和导出模型。
• 是真网关,不是 mock ------ 反向代理支持路由规则、加权上游、重试、健康检查、熔断和 WebSocket 透传,还能实时看到流量。
• 长驻服务不用另起一套栈 ------ TCP/UDP 监听器、SOCKS5 服务端、反向代理和终端 PTY 都能跑在子进程里,由同一个期望状态监护器统一管理。
• 本地优先 ------ SQLite、服务端会话、PBKDF2 口令哈希、RBAC 和首次启动管理员流程。没有遥测,没有云账号,不依赖外部数据库。
• 单一网络栈 ------ 每一条目标连接都由 libuvcpp 1.8.2 驱动,从 socket 一直到 UI。
• UI 不丢上下文 ------ 可折叠导航、多标签工作区缓存、实时遥测,以及基于 Vue 3 + Pinia + Vite 的离线命令库。

功能一览

HTTP 与 API

能力	状态
HTTP/1.1 + HTTPS 调试器,含 header、body、耗时和历史	稳定
Body 模式:raw、form-urlencoded、带文件的 multipart	稳定
cURL / HAR / OpenAPI / Postman 导入导出	稳定
环境变量 {``{variables}}、前置/后置脚本	稳定(浏览器侧)
TLS 上的 HTTP/2,含 ALPN、流 ID、GOAWAY 和帧摘要	稳定
gzip / deflate / brotli 解码,可切换查看原始 body	稳定
大响应流式下载,支持进度、取消和 Range 断点续传	稳定
响应预览:沙箱 HTML、图片、音频、视频、PDF	稳定(脚本需手动开启)
SOAP 1.1 + WSDL 操作发现	稳定
HTTP/3 与裸 QUIC 探测	QUIC 构建版支持

实时通信与传输层

能力	状态
WebSocket 控制台:守护进程侧会话 + 浏览器原生模式	稳定
后端 WebSocket 自定义 header、子协议、帧、ping/pong、关闭码	稳定
一次性 TCP / UDP 探测(文本 / hex)	稳定
持久 TCP 会话,支持重复发送和事件日志	稳定
TCP / UDP 服务监听器,含会话、数据报和回复	稳定
SOCKS5 客户端与服务端(CONNECT / BIND / UDP ASSOCIATE)	稳定
虚拟终端(Unix PTY / Windows ConPTY),含离线命令库	稳定 ------ 默认关闭

网关与长驻服务

能力	状态
反向代理:精确 / 前缀 / 正则规则,重定向与重写	稳定
Header / 方法 / Host 条件,加权上游,重试	稳定
主动上游健康检查、逐上游熔断、QPS/延迟指标	稳定
代理配置热重载,带运行时配置版本	稳定
反向代理中的 WebSocket 透传	稳定
代理、监听器、SOCKS5、终端的子进程隔离	稳定
统一期望状态监护器,含重启、退避和事件日志	稳定
托管 TLS 证书、本地 CA、CA 签发证书和原地续期	稳定

运维与安全

能力	状态
SQLite 持久化、首次启动设置、本地认证、RBAC(admin / operator / viewer)	稳定
服务端会话、活动会话吊销、审计日志	稳定
备份下载与分阶段恢复	稳定
模块开关、恢复出厂、更新检查、关于/帮助	稳定
中英文 UI,自动识别浏览器语言并可手动切换	稳定
深色 / 浅色 / 跟随系统主题	稳定
Linux tar/deb/rpm、Windows zip + 安装包、macOS tar.gz	稳定

快速开始

环境要求

• C++17 编译器、CMake ≥ 3.20、Ninja
• Node.js 20+ 与 npm
• libuv、zlib、SQLite、OpenSSL 开发头文件
• Linux、macOS,或带 MSYS2 MinGW-w64 的 Windows

Debian/Ubuntu 下:

sudo apt install build-essential cmake ninja-build libuv1-dev zlib1g-dev \
  libssl-dev libsqlite3-dev git curl

从源码构建

git clone https://github.com/Antruly/uvscope.git
cd uvscope
./scripts/build.sh
./build/uvscope --port 8787 --open

build.sh 会把 libuvcpp v1.8.2 拉到 .deps/,应用 patches/upstream/ 里唯一一个最小上游补丁(WebSocket 握手 header),构建前端,再构建 uvscope 并跑一遍 --self-check。

如果本地已有 libuvcpp 1.8.2 SDK:

npm --prefix web ci && npm --prefix web run build
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
  -DUVCPP_ROOT=/path/to/libuvcpp
cmake --build build -j
./build/uvscope --self-check

打开 http://127.0.0.1:8787。首次访问会引导创建管理员账号。所有运行时状态都在启动时打印的数据目录里(Linux 默认 ~/.local/share/uvscope,可用 --data-dir 覆盖)。

命令行参数

uvscope [options]

  --host <addr>       监听地址(默认 127.0.0.1)
  --port <port>       监听端口(默认 8787,0 表示自动选一个空闲端口)
  --data-dir <path>   SQLite 与运行时数据目录
  --web-root <path>   构建好的前端目录
  --tls-cert <pem>    UI 走 HTTPS 时使用
  --tls-key <pem>     与 --tls-cert 配对的私钥
  --open              用默认浏览器打开工作台
  --self-check        跑离线冒烟测试后退出
  --version           打印版本后退出

隐藏子进程模式(--proxy-child、--listener-child、--socks5-child、--terminal-child、--ipc-child)由守护进程自行拉起,不要手工调用。

架构

Vue 3 SPA(多标签、工作区缓存)
        │ 同源 HTTP + WebSocket + Cookie
        ▼
uvscope 守护进程(C++17 / libuvcpp)
  ├─ 认证 + RBAC + SQLite + 审计 + 备份
  ├─ HTTP API 与静态资源服务
  ├─ 探测、调试会话与终端会话
  ├─ 期望状态监护器
  └─ 可选子进程(隔离服务)
        ├─ 反向代理运行时
        ├─ TCP/UDP 监听器运行时
        ├─ SOCKS5 服务端运行时
        └─ 终端 PTY / ConPTY
              │
              └─ libuvcpp → libuv → socket

守护进程是唯一提供 UI 并持有 SQLite 的进程。默认的内进程模式下,它也持有所有出站 socket;开启隔离后,服务在自己的子进程里打开 socket。WebSocket 视图额外提供浏览器原生模式,因为 origin、混合内容和证书提示本身就是被调试对象的一部分。

隔离与监护

代理、TCP/UDP 监听器、SOCKS5 服务端和虚拟终端都接受 isolated: true。父进程保留 API 状态、滚动回显和归属元数据;服务跑在子进程里,通过长度前缀的 JSON IPC 通道与父进程通信。

四类服务统一注册到一个期望状态监护器:

• 子进程崩溃后按指数退避(2--60 秒)重启,分配新的 PID;
• 重启次数和事件在 /api/supervisor 和 /api/supervisor/events 可见;
• 停止服务会清掉它的期望状态,看门狗不会再把它拉起来;
• 删除服务会先注销再销毁;
• 终端正常 exit 不算崩溃 ------ 子进程保留,滚动回显和退出码仍可查看。崩溃的终端会用新 shell 重启,已连接的 WebSocket 客户端会先收到一个 reset 帧再收新输出。

安全模型

• 默认绑定 127.0.0.1。未经认证代理保护时,不要把 uvscope 暴露在不可信网络上。
• 口令用 PBKDF2-HMAC-SHA256(210,000 轮);会话在服务端存储为 SHA-256 token 哈希。Cookie 设置 HttpOnly + SameSite=Lax。
• 任何通过认证的用户都能访问主机网络、启动监听器/代理,并在终端模块开启时以守护进程用户身份拿到 shell。应把该访问权限视同于主机上的代码执行。
• 隔离服务以同一 OS 用户运行;隔离是故障边界,不是安全沙箱。
• TLS Inspector 和"允许不安全 TLS"只对你控制的环境使用。

平台与下载

预构建的 v1.0.1 发布在 Releases 页面,附带 SHA256SUMS、Sigstore 无密钥签名和生成的 SPDX SBOM。

平台	发布形式	说明
Linux x64	tar.gz、deb、rpm	主要 CI 与冒烟测试矩阵
Linux arm64	tar.gz、deb、rpm	发布构建与自检
Windows x64(MinGW)	zip、setup.exe	CI 构建、自检与 ConPTY 冒烟
macOS arm64	tar.gz	CI 构建、自检与 HTTP/2 运行时检查
HTTP/3 / QUIC	启用 QUIC 的构建	需要 OpenSSL 3.6+,默认发布包关闭 QUIC

校验下载:

sha256sum -c SHA256SUMS
cosign verify-blob --bundle SHA256SUMS.sigstore.json \
  --certificate-identity-regexp 'https://github.com/Antruly/uvscope/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS

写在最后

uvscope 使用 MIT 协议,文档站: https://antruly.github.io/uvscope/,里面还有 HTTP API、架构说明、事件 schema 和 路线图。

如果它帮你省下一次调试时间,GitHub 点个 star 能让更多和协议打交道的人发现它。

---

标签: 网络调试、HTTP、反向代理、C++、开源工具