kahluna-systems/Pulsar

# KahLuna Pulsar **KahLuna Pulsar** 是一个分布式网络诊断套件——作为一个可部署的测试点，无论您将其部署在何处（云端、数据中心或网络边缘），它都能测量连接性、路径、延迟、丢包率和吞吐量。 它是 **KahLuna Nexus** 套件的一部分：Pulsar 可以作为专用探针**独立**运行，也可以作为内置诊断引擎**嵌入**到 KahLuna WARP Gateway 中。 ## 功能 ### 仪表板 - **概览仪表板** — 测试计数、成功率、节点正常运行时间、按类型划分的测试细分、近期活动 - 可折叠的侧边导航栏，经过身份验证的单页应用 ### 诊断工具 - **HTTP Speed Test** - Ookla 风格的测速工具，带有面向客户的门户 - **Traceroute** - 支持 ICMP/UDP/TCP 选项的路径分析 - **MTR** - 实时流式 traceroute + ping，带有丢包统计信息 - **DNS Lookup** - 查询任何记录类型，检查公共 DNS 间的传播情况 - **TCP Port Check** - 测试端口连接性及连接耗时 - **SSL Certificate Check** - 验证证书，检查过期时间 - **Continuous Ping** - 长时间运行的 ping 监控，带有抖动追踪 - **iPerf3** - 原始带宽测试，支持客户端或服务器模式，并内置**远程客户端指南**：提供针对各操作系统的安装指引、预填节点地址的直接复制命令，以及**一键粘贴的 Windows 设置**，可直接从节点 (`/downloads/iperf3-win64.zip`) 下载版本固定且经过校验和验证的 iperf3 客户端 - **Packet Capture** - 集成 tcpdump 用于流量分析 ### 身份验证与管理 - **首次运行设置** — 无默认凭证；首次访问时即创建管理员账户 - 基于 JWT 的登录；角色分为：`viewer`、`engineer`、`admin` - **管理面板** — 用户管理、密码修改、节点设置（名称、位置、功能开关、限制）均可在 UI 中编辑 ### 客户与归属 - **组织注册表**（客户和合作伙伴），包含承载已注册测试端点的 **circuits** - **"Run tests for:"** 归属功能 — 每个测试都可以标记上组织/circuit；选择 circuit 时会自动预填其端点作为目标 - 测试历史记录可按组织过滤；支持搜索的客户主从视图 ### 客户测试 - 生成有时限且可追踪的测试 token（可关联到组织） - 面向客户的测速门户（无需软件） - 结果自动与客户/circuit/组织关联 - 记录所有测试以用于历史分析 ### 架构 - **Standalone Mode**：使用本地 SQLite 的单节点部署 - **Hub Mode**：带有多个边缘节点的中心 PostgreSQL 数据库（计划中 — 同步字段已就绪） - Docker 优先部署，采用主机网络以提供真实的网络观测点 ## 快速开始 ### Docker（推荐） ``` git clone https://github.com/kahluna-systems/Pulsar.git pulsar cd pulsar docker compose up -d --build ``` 然后打开 `http://:8000` — 首次访问会提示您**创建管理员账户**。 注意事项： - compose 文件使用 `network_mode: host`，以便诊断工具能从主机的真实网络位置进行测量；应用直接绑定 `0.0.0.0:8000`。 - 数据（SQLite 数据库 + 生成的节点配置，包括 token 签名密钥）会在 `pulsar_node_data` 卷中持久化，跨重建保留。 - 特权工具（ping/traceroute/MTR/tcpdump）通过内置在镜像中的文件权限运行 — 应用以非 root 用户身份运行，无需 sudo。 ### Python（开发环境） ``` git clone https://github.com/kahluna-systems/Pulsar.git pulsar cd pulsar python -m venv venv source venv/bin/activate # or venv\Scripts\activate on Windows pip install -r requirements.txt # 运行 node（从 repo 根目录运行，以便 package 导入能够正确解析） export PYTHONPATH=$(pwd) # Windows PowerShell: $env:PYTHONPATH = $PWD python -m uvicorn node.main:app --reload --host 0.0.0.0 --port 8000 ``` 要求 **Python 3.12+**。 ## 访问 - **工程师仪表板**：`http://:8000`（启用身份验证后需要登录） - **客户测速**：`http://:8000/speedtest`（公开） - **API 文档**：`http://:8000/docs` ## 配置 配置层级，优先级从高到低依次为：**环境变量 → `node_config.json` → 默认值**。首次运行时，节点会生成并持久化其身份标识（`node_id`、`secret_key`）。 常见的环境变量（参见 `docker-compose.yml`）： | 变量 | 用途 | |----------|---------| | `NODE_ID` / `NODE_NAME` / `NODE_LOCATION` | UI 中显示的节点标识 | | `REQUIRE_AUTH` | 启用登录 + 首次运行管理员设置（推荐设为 `true`） | | `DATABASE_PATH` | SQLite 路径（指向持久化卷） | | `NODE_CONFIG` | 生成的配置文件存放位置 | | `HUB_URL` / `HUB_API_KEY` | 为 hub 模式预留 | 每次启动时，通过环境变量设置的字段都会覆盖配置文件；管理面板会将此类字段标记为环境变量固定。功能开关和限制可以在 **Admin** 标签页中编辑。 ## 端口 | 端口 | 用途 | |------|-----| | 8000/tcp | 仪表板、API、客户测速 | | 5201/tcp+udp | iPerf3 服务器模式（如果使用，请在您的云端/主机防火墙中开放） | ## 安全说明 - 身份验证在启用时**没有默认凭证** — 第一个访问者会创建管理员账户（在公开部署时请立即执行此操作） - 客户 token 具有时限和使用次数限制 - `node_config.json` 包含 token 签名密钥 — 它已被 gitignore 忽略，且必须对每次部署保持独立 - 在生产环境中使用 HTTPS（推荐使用反向代理） ## 许可证 KahLuna 生态系统的一部分。保留所有权利。

标签：Awesome, UDP扫描, 分布式测量, 后端开发, 情报分析, 测试用例, 系统管理, 网络诊断, 请求拦截, 运维监控, 逆向工具