lenxy-ea/trex-webui
GitHub: lenxy-ea/trex-webui
为 Cisco TRex STL 实验室提供桌面级 Web 控制平面，集成流量构建、多端口运行、实时统计、数据包捕获和可审计的运行证据导出。
Stars: 0 | Forks: 0
# TRex WebUI
[](https://github.com/lenxy-ea/trex-webui/actions/workflows/ci.yml)
[](CHANGELOG.md)
[](LICENSE)
**一个用于真实 Cisco TRex STL 实验室的桌面级控制平面。**
构建流量，操作多端口运行，检查实时统计和捕获，
管理 TRex runtime，并从一个密集的
浏览器工作区中保留可审计的运行证据。
[](docs/images/hero-dashboard.png)
发现并控制端口，保持持久化的三对流量计划，并启动、更新、暂停、恢复或停止支持的会话。 | **查看整体运行情况**
通过实时的后端事件检查全局、端口、stream、延迟、利用率、丢包率和健康数据。 | | **构建 profile 和数据包**
浏览 profile，编辑 stream，导入/导出 PCAP，使用结构化协议编辑器，或直接使用原始数据包和 Field Engine 控制。 | **捕获与解码**
监控或录制选定端口，应用 BPF 和捕获预算，检查解码后的数据包，并下载 PCAP 证据。 | | **保留证据**
审查门控、诊断、趋势、存档对比和原始数据；导出 Markdown、PDF、CSV 或 JSON 报告。 | **安全地掌控 runtime**
预览 TRex YAML，管理配置版本，检查审计/日志输出，并使用带有受保护变更操作的持久化 supervisor。 | 硬件、RPC、权限、配置和链路故障仍然是可见的 阻碍。产品路径不会用模拟流量或虚假的健康状态来替代不可用的 TRex 环境。 ## 视觉导览 下方的截图使用了由真实生产 UI 渲染的脱敏说明性数据。它们展示的是工作流，而非硬件认证；发布证据由真实的硬件验收门控单独生成。 ### Profile 和 Stream 构建器 [](docs/images/profile-builder.png) 在结构化或专家视图中编排 stream，配置协议字段，并在 profile runtime 设置、PCAP 工作流和数据包检查之间切换。 ### 数据包捕获 [](docs/images/packet-capture.png) 在保留的数据包和解码字段旁边查看协议组合和会话，并在同一界面中使用监控、录制、过滤、预算和 PCAP 工作流。 ### 运行报告 [](docs/images/run-reports.png) 将一次运行转化为操作员可读的结论，包含门控、指标、诊断、历史、对比和可下载的证据。 使用以下命令从当前运行的 UI 重新生成所有四张图片： ``` scripts/npmw run screenshot:readme -- --url http://127.0.0.1:5176 ``` 捕获命令会阻塞其脱敏 fixture 契约之外的 API 调用，并 将每个输出标记为说明性文档数据。如果 Chromium 尚未在 Playwright 缓存中，请使用 `scripts/npmw --prefix apps/web exec -- playwright install chromium` 安装它。 ## 当前范围 最新标记的基线是 **v0.1.0-rc.1**，这也是当前的 package 版本；`main` 可能包含超出该标签的未发布更改。里程碑名称描述的是产品范围，而不是一揽子的发布认证。 | 领域 | 当前边界 | | --- | --- | | 操作员模型 | 单一可信操作员；无内置身份验证、多租户或 RBAC | | 浏览器 | 当前的桌面版 Chromium 系列浏览器 | | 验证过的主机 | AlmaLinux 9.8, x86_64 | | 验证过的 TRex | v3.08 stateless/STL 控制平面 | | 参考拓扑 | 六个排列为三个逻辑对的 Intel i350 端口 | | 部署 | 位于 Nginx 后方的同主机托管 daemon，或明确由操作员管理的外部 supervisor | | 产品状态 | M0 和六端口控制循环已实现；替代、兼容性和更广泛的证据里程碑仍部分处于验证阶段 | 六端口基线验证了配置、清单、控制、runtime 状态和清理路径。真实流量和捕获认证始终 绑定到选定的端口对、其当前链路状态、活动的 配置、确切的身份源以及由该运行生成的 证据存档。 公共互联网或不受信任的 LAN 暴露、共享的多用户操作、 移动/平板布局、ASTF 工作流以及处于托管本地模式下的容器/Kubernetes 均不受支持。其他操作系统、NIC 和 TRex 版本的支持范围较窄或处于未经验证状态。 请参阅[支持矩阵](docs/SUPPORT_MATRIX.md)和 [项目路线图](docs/PROJECT_ROADMAP.md)以了解确切的边界。 ## 架构 ``` Desktop browser │ │ HTTP + SSE ▼ Nginx management-network allowlist ├── serves the React/Vite application └── proxies /api to loopback │ ▼ FastAPI backend ├── project-owned API and runtime authority ├── reports, captures, and guarded config workflows └── TRex adapter layer │ ▼ STLClient / daemon / Scapy / JSON-RPC │ ▼ Real TRex hardware ``` TRex 传输保留在后端适配器之后。浏览器使用 项目自有的契约，从不直接与 STL、Scapy 或 daemon 端口通信。在受支持的同主机部署中，非特权 API 和 拥有 root 权限的持久化 TRex supervisor 是相互独立的服务。 ## 快速开始 ### 前置条件 - 受支持的 Linux/x86_64 主机；请参阅 [docs/SUPPORT_MATRIX.md](docs/SUPPORT_MATRIX.md)。 - Python 3.11。 - Node.js 24.16.0 和 npm 11.x。Bootstrap 可以在受支持的 Linux/x64 主机上安装固定的项目本地 runtime。 - 操作员安装的用于硬件工作流的上游 TRex 发行版。 - 当前的桌面版 Chromium 系列浏览器。 ### 安装开发依赖 ``` git clone https://github.com/lenxy-ea/trex-webui.git cd trex-webui scripts/bootstrap_node.sh scripts/npmw ci scripts/npmw --prefix apps/web ci python3.11 -m venv .venv .venv/bin/python -m pip install --require-hashes --only-binary=:all: \ -r apps/api/requirements-dev.lock cp .env.example .env ``` `scripts/npmw` 优先使用 `.tools/` 下固定的 runtime，并且也接受 已经在 `PATH` 中的兼容 Node 24/npm 11 安装。通过包装器使用 `npm ci`，以便签入的 lockfile 保持权威性。 复制的 `.env` 将开发服务和默认的 TRex 目标保留在 loopback 上。在连接真实硬件之前，请检查每一个路径和 endpoint。 ### 启动开发服务 后端： ``` .venv/bin/uvicorn app.main:app --app-dir apps/api --reload \ --host 127.0.0.1 --port 8080 ``` 前端，在另一个终端中： ``` scripts/npmw run dev:web -- --host 127.0.0.1 --port 5176 ``` 打开 [http://127.0.0.1:5176/](http://127.0.0.1:5176/)。 如果没有可访问的 TRex 环境，界面仍可用于 开发，但会报告明确的硬件阻碍，而不是生成 看似合理的流量数据。 ## 连接真实的 TRex 硬件 默认的 `.env.example` 以本地 TRex 安装为目标。仅当远程 daemon 的生命周期、持久化、防火墙、身份验证和日志由操作员掌控时，才支持该远程 daemon： ``` TREX_WEBUI_TREX_HOST=trex.example.test TREX_WEBUI_DAEMON_SUPERVISOR=external ``` 限制 daemon、STL 和 Scapy 端口，以便只有 WebUI 主机能够访问它们。 TRex WebUI 不会为上游 TRex 控制协议添加身份验证。 [examples/trex_cfg.yaml](examples/trex_cfg.yaml) 展示了一个 使用仅用于文档的值的虚构六端口 Intel i350 配置的 schema。 它未经硬件认证，绝不能原封不动地部署。请按照 [examples/README.md](examples/README.md) 替换并验证每一个 PCI 地址、MAC/IP 值、NUMA socket、端口对和核心分配。 ## 生产部署 经过验证的部署是位于受信任管理网络上的 Nginx 后方的同主机托管 TRex daemon： ``` sudo deploy/install.sh --install-nginx --install-python-deps --verify ``` 必须显式选择独立管理或远程的 daemon： ``` sudo deploy/install.sh --external-daemon \ --install-nginx --install-python-deps --verify ``` 仅当预期控制平面在线时才附加 `--verify-trex`。 安装后的 Nginx 策略会向非 loopback 客户端返回 HTTP 403，直到 操作员添加严格的管理网络白名单。这是预期的 安全默认设置。 在安装之前阅读 [docs/NGINX_DEPLOYMENT.md](docs/NGINX_DEPLOYMENT.md)。 它涵盖了试运行、确切的白名单、TLS 和外部身份验证、 systemd/nftables 边界、打包、验证、升级和回滚 限制。 ## 安全边界 受支持的拓扑保持 Nginx 默认拒绝，FastAPI 绑定到 `127.0.0.1`，托管本地 daemon RPC 位于 loopback 上，以及原生 TRex/Scapy 端口 位于安装程序拥有的 nftables 边界之后。在需要时独立添加 TLS 或反向代理 身份验证；这些边界控制不会 将应用程序转变为多用户授权系统。 在操作真实硬件之前，请阅读 [SECURITY.md](SECURITY.md) 和 [部署指南](docs/NGINX_DEPLOYMENT.md)。 ## 验证 安全的本地检查不会主动发送流量： ``` scripts/npmw test scripts/npmw run typecheck:web scripts/npmw run lint:web scripts/npmw run build:web scripts/tests/public_source_test.sh .venv/bin/python -m pip_audit -r apps/api/requirements-dev.lock scripts/npmw --prefix apps/web audit --audit-level=high ``` 硬件集成测试始终是显式的： ``` TREX_WEBUI_RUN_HARDWARE_TESTS=1 \ .venv/bin/python -m pytest apps/api/tests/integration ``` 流量和捕获冒烟测试有单独的启用选项，因为它们会改变真实的 端口。有关这些命令及其 清理契约，请参阅 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。 TRex WebUI 的重大更改需要在主机验证配置下进行真实的硬件 Standard E2E 测试： ``` scripts/npmw run verify:major -- --base-url http://127.0.0.1 \ --config-file /path/to/validated/trex_cfg.yaml ``` 可选的浏览器写入验收执行真实的控制平面写入操作，并且 必须单独申请： ``` scripts/npmw run verify:major -- --base-url http://127.0.0.1 \ --config-file /path/to/validated/trex_cfg.yaml \ --browser-write-acceptance ``` 切勿将任一命令指向未经编辑的公共示例。通过的 gate 将 当前源码、前端资产、API 身份、活动配置、 观察到的硬件和干净的后置条件绑定到一对 新的本地/服务器报告中。硬件、链路、RPC、权限或 配置失败仍然是阻碍；说明性 fixture 无法放弃 此 gate。 ## 仓库结构图 ``` apps/api FastAPI backend and TRex control-plane adapters apps/web React/Vite desktop operator console deploy Nginx, systemd, packaging, upgrade, and verification tooling docs Architecture, development, deployment, support, and roadmap notes examples Fictional, non-production configuration examples profiles Project traffic-profile catalog scripts Toolchain wrappers and real-hardware acceptance workflows ``` ## 许可证 TRex WebUI 基于 [Apache License 2.0](LICENSE) 提供。署名 和第三方条款记录在 [NOTICE](NOTICE)、 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 和 [docs/PROVENANCE.md](docs/PROVENANCE.md) 中。
带有实时吞吐量、健康状况、延迟和各端口趋势的六端口仪表板。
## 从 profile 到证据的统一工作流 | | | | --- | --- | | **操作真实流量**发现并控制端口，保持持久化的三对流量计划，并启动、更新、暂停、恢复或停止支持的会话。 | **查看整体运行情况**
通过实时的后端事件检查全局、端口、stream、延迟、利用率、丢包率和健康数据。 | | **构建 profile 和数据包**
浏览 profile，编辑 stream，导入/导出 PCAP，使用结构化协议编辑器，或直接使用原始数据包和 Field Engine 控制。 | **捕获与解码**
监控或录制选定端口，应用 BPF 和捕获预算，检查解码后的数据包，并下载 PCAP 证据。 | | **保留证据**
审查门控、诊断、趋势、存档对比和原始数据；导出 Markdown、PDF、CSV 或 JSON 报告。 | **安全地掌控 runtime**
预览 TRex YAML，管理配置版本，检查审计/日志输出，并使用带有受保护变更操作的持久化 supervisor。 | 硬件、RPC、权限、配置和链路故障仍然是可见的 阻碍。产品路径不会用模拟流量或虚假的健康状态来替代不可用的 TRex 环境。 ## 视觉导览 下方的截图使用了由真实生产 UI 渲染的脱敏说明性数据。它们展示的是工作流，而非硬件认证；发布证据由真实的硬件验收门控单独生成。 ### Profile 和 Stream 构建器 [](docs/images/profile-builder.png) 在结构化或专家视图中编排 stream，配置协议字段，并在 profile runtime 设置、PCAP 工作流和数据包检查之间切换。 ### 数据包捕获 [](docs/images/packet-capture.png) 在保留的数据包和解码字段旁边查看协议组合和会话，并在同一界面中使用监控、录制、过滤、预算和 PCAP 工作流。 ### 运行报告 [](docs/images/run-reports.png) 将一次运行转化为操作员可读的结论，包含门控、指标、诊断、历史、对比和可下载的证据。 使用以下命令从当前运行的 UI 重新生成所有四张图片： ``` scripts/npmw run screenshot:readme -- --url http://127.0.0.1:5176 ``` 捕获命令会阻塞其脱敏 fixture 契约之外的 API 调用，并 将每个输出标记为说明性文档数据。如果 Chromium 尚未在 Playwright 缓存中，请使用 `scripts/npmw --prefix apps/web exec -- playwright install chromium` 安装它。 ## 当前范围 最新标记的基线是 **v0.1.0-rc.1**，这也是当前的 package 版本；`main` 可能包含超出该标签的未发布更改。里程碑名称描述的是产品范围，而不是一揽子的发布认证。 | 领域 | 当前边界 | | --- | --- | | 操作员模型 | 单一可信操作员；无内置身份验证、多租户或 RBAC | | 浏览器 | 当前的桌面版 Chromium 系列浏览器 | | 验证过的主机 | AlmaLinux 9.8, x86_64 | | 验证过的 TRex | v3.08 stateless/STL 控制平面 | | 参考拓扑 | 六个排列为三个逻辑对的 Intel i350 端口 | | 部署 | 位于 Nginx 后方的同主机托管 daemon，或明确由操作员管理的外部 supervisor | | 产品状态 | M0 和六端口控制循环已实现；替代、兼容性和更广泛的证据里程碑仍部分处于验证阶段 | 六端口基线验证了配置、清单、控制、runtime 状态和清理路径。真实流量和捕获认证始终 绑定到选定的端口对、其当前链路状态、活动的 配置、确切的身份源以及由该运行生成的 证据存档。 公共互联网或不受信任的 LAN 暴露、共享的多用户操作、 移动/平板布局、ASTF 工作流以及处于托管本地模式下的容器/Kubernetes 均不受支持。其他操作系统、NIC 和 TRex 版本的支持范围较窄或处于未经验证状态。 请参阅[支持矩阵](docs/SUPPORT_MATRIX.md)和 [项目路线图](docs/PROJECT_ROADMAP.md)以了解确切的边界。 ## 架构 ``` Desktop browser │ │ HTTP + SSE ▼ Nginx management-network allowlist ├── serves the React/Vite application └── proxies /api to loopback │ ▼ FastAPI backend ├── project-owned API and runtime authority ├── reports, captures, and guarded config workflows └── TRex adapter layer │ ▼ STLClient / daemon / Scapy / JSON-RPC │ ▼ Real TRex hardware ``` TRex 传输保留在后端适配器之后。浏览器使用 项目自有的契约，从不直接与 STL、Scapy 或 daemon 端口通信。在受支持的同主机部署中，非特权 API 和 拥有 root 权限的持久化 TRex supervisor 是相互独立的服务。 ## 快速开始 ### 前置条件 - 受支持的 Linux/x86_64 主机；请参阅 [docs/SUPPORT_MATRIX.md](docs/SUPPORT_MATRIX.md)。 - Python 3.11。 - Node.js 24.16.0 和 npm 11.x。Bootstrap 可以在受支持的 Linux/x64 主机上安装固定的项目本地 runtime。 - 操作员安装的用于硬件工作流的上游 TRex 发行版。 - 当前的桌面版 Chromium 系列浏览器。 ### 安装开发依赖 ``` git clone https://github.com/lenxy-ea/trex-webui.git cd trex-webui scripts/bootstrap_node.sh scripts/npmw ci scripts/npmw --prefix apps/web ci python3.11 -m venv .venv .venv/bin/python -m pip install --require-hashes --only-binary=:all: \ -r apps/api/requirements-dev.lock cp .env.example .env ``` `scripts/npmw` 优先使用 `.tools/` 下固定的 runtime，并且也接受 已经在 `PATH` 中的兼容 Node 24/npm 11 安装。通过包装器使用 `npm ci`，以便签入的 lockfile 保持权威性。 复制的 `.env` 将开发服务和默认的 TRex 目标保留在 loopback 上。在连接真实硬件之前，请检查每一个路径和 endpoint。 ### 启动开发服务 后端： ``` .venv/bin/uvicorn app.main:app --app-dir apps/api --reload \ --host 127.0.0.1 --port 8080 ``` 前端，在另一个终端中： ``` scripts/npmw run dev:web -- --host 127.0.0.1 --port 5176 ``` 打开 [http://127.0.0.1:5176/](http://127.0.0.1:5176/)。 如果没有可访问的 TRex 环境，界面仍可用于 开发，但会报告明确的硬件阻碍，而不是生成 看似合理的流量数据。 ## 连接真实的 TRex 硬件 默认的 `.env.example` 以本地 TRex 安装为目标。仅当远程 daemon 的生命周期、持久化、防火墙、身份验证和日志由操作员掌控时，才支持该远程 daemon： ``` TREX_WEBUI_TREX_HOST=trex.example.test TREX_WEBUI_DAEMON_SUPERVISOR=external ``` 限制 daemon、STL 和 Scapy 端口，以便只有 WebUI 主机能够访问它们。 TRex WebUI 不会为上游 TRex 控制协议添加身份验证。 [examples/trex_cfg.yaml](examples/trex_cfg.yaml) 展示了一个 使用仅用于文档的值的虚构六端口 Intel i350 配置的 schema。 它未经硬件认证，绝不能原封不动地部署。请按照 [examples/README.md](examples/README.md) 替换并验证每一个 PCI 地址、MAC/IP 值、NUMA socket、端口对和核心分配。 ## 生产部署 经过验证的部署是位于受信任管理网络上的 Nginx 后方的同主机托管 TRex daemon： ``` sudo deploy/install.sh --install-nginx --install-python-deps --verify ``` 必须显式选择独立管理或远程的 daemon： ``` sudo deploy/install.sh --external-daemon \ --install-nginx --install-python-deps --verify ``` 仅当预期控制平面在线时才附加 `--verify-trex`。 安装后的 Nginx 策略会向非 loopback 客户端返回 HTTP 403，直到 操作员添加严格的管理网络白名单。这是预期的 安全默认设置。 在安装之前阅读 [docs/NGINX_DEPLOYMENT.md](docs/NGINX_DEPLOYMENT.md)。 它涵盖了试运行、确切的白名单、TLS 和外部身份验证、 systemd/nftables 边界、打包、验证、升级和回滚 限制。 ## 安全边界 受支持的拓扑保持 Nginx 默认拒绝，FastAPI 绑定到 `127.0.0.1`，托管本地 daemon RPC 位于 loopback 上，以及原生 TRex/Scapy 端口 位于安装程序拥有的 nftables 边界之后。在需要时独立添加 TLS 或反向代理 身份验证；这些边界控制不会 将应用程序转变为多用户授权系统。 在操作真实硬件之前，请阅读 [SECURITY.md](SECURITY.md) 和 [部署指南](docs/NGINX_DEPLOYMENT.md)。 ## 验证 安全的本地检查不会主动发送流量： ``` scripts/npmw test scripts/npmw run typecheck:web scripts/npmw run lint:web scripts/npmw run build:web scripts/tests/public_source_test.sh .venv/bin/python -m pip_audit -r apps/api/requirements-dev.lock scripts/npmw --prefix apps/web audit --audit-level=high ``` 硬件集成测试始终是显式的： ``` TREX_WEBUI_RUN_HARDWARE_TESTS=1 \ .venv/bin/python -m pytest apps/api/tests/integration ``` 流量和捕获冒烟测试有单独的启用选项，因为它们会改变真实的 端口。有关这些命令及其 清理契约，请参阅 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。 TRex WebUI 的重大更改需要在主机验证配置下进行真实的硬件 Standard E2E 测试： ``` scripts/npmw run verify:major -- --base-url http://127.0.0.1 \ --config-file /path/to/validated/trex_cfg.yaml ``` 可选的浏览器写入验收执行真实的控制平面写入操作，并且 必须单独申请： ``` scripts/npmw run verify:major -- --base-url http://127.0.0.1 \ --config-file /path/to/validated/trex_cfg.yaml \ --browser-write-acceptance ``` 切勿将任一命令指向未经编辑的公共示例。通过的 gate 将 当前源码、前端资产、API 身份、活动配置、 观察到的硬件和干净的后置条件绑定到一对 新的本地/服务器报告中。硬件、链路、RPC、权限或 配置失败仍然是阻碍；说明性 fixture 无法放弃 此 gate。 ## 仓库结构图 ``` apps/api FastAPI backend and TRex control-plane adapters apps/web React/Vite desktop operator console deploy Nginx, systemd, packaging, upgrade, and verification tooling docs Architecture, development, deployment, support, and roadmap notes examples Fictional, non-production configuration examples profiles Project traffic-profile catalog scripts Toolchain wrappers and real-hardware acceptance workflows ``` ## 许可证 TRex WebUI 基于 [Apache License 2.0](LICENSE) 提供。署名 和第三方条款记录在 [NOTICE](NOTICE)、 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 和 [docs/PROVENANCE.md](docs/PROVENANCE.md) 中。
标签：Cisco TRex, Web控制台, 安全审计, 数据包抓取, 流量生成, 特征检测, 网络测试, 自动化攻击, 逆向工具