MoShiro/README.md

MoShiro

MoShiro 旨在解决跨网络线路质量难以量化的问题：

• 家宽到海外 VPS 的延迟、丢包、抖动随时段波动，单点 ping 无法反映真实体验；
• 不同代理、游戏、流媒体服务对线路的敏感度各异，缺少统一的评价口径。

它通过 Probe 与 Agent 之间的主动测量采集原始数据，由 Backend 推算指标，并按服务模型（REALITY、Hysteria2、Minecraft 等）对线路评分与排序。

角色

角色	定位	部署位置
Probe	测量发起端，向 Agent 拨出测量会话	家宽等出口，可位于 NAT 后
Agent	测量接收端，响应 Probe 并汇总两端数据上报	具备公网地址的 VPS 等节点
Backend	控制面与数据服务：注册、任务编排、存储、分析、REST / SSE	自托管服务器
Web	display 展示端（可匿名只读）与 admin 管理端	与 Backend 同源部署

                 ┌───────────── Backend ─────────────┐
                 │ 注册 · 编排 · 存储 · 分析 · API   │──▶ Web
                 └───────▲───────────────────▲───────┘
                         │ wss（节点发起）   │
                 ┌───────┴────────┐   ┌──────┴───────┐
                 │ Agent × N      │◀──│ Probe × N    │
                 │ 公网可达       │   │ NAT 后       │
                 └────────────────┘   └──────────────┘
                        测量会话：Probe → Agent

Probe 与 Agent 只做测量与上报，没有终端、命令执行和自更新，更新由外部服务管理器完成。节点与 Backend 之间的身份、任务和更新均基于签名校验，详见安全文档。

快速开始

环境：.NET SDK 10（版本见 global.json）、Node.js 与 npm。

cd backend && dotnet run --project src/MoShiro.Backend -- --urls http://localhost:5000   # Backend
npm ci --prefix web && npm run dev --prefix web                                          # Web（另开终端，仓库根目录）

展示端 http://localhost:5173/，管理端 http://localhost:5173/admin/。首次访问管理端进入认领向导，认领码输出在后端日志。

构建与测试：

dotnet build MoShiro.slnx -c Release
dotnet test --solution MoShiro.slnx
npm run build --prefix web

文档

主题	文档
架构与设计决策	architecture
线协议与方法	protocol
采集引擎与任务	measurement
分析、存储、查询	analysis · storage · query
安全：威胁模型、访问控制、注册与身份	security · access · enrollment
REST / SSE 接口	api
构建、发布、CI、部署与更新	deployment
仓库结构与代码风格	project-layout · coding-style
路线图	roadmap
子项目	backend · fleet · agent · probe · web

贡献与自动化代理的工作约定见 AGENTS.md。

许可证

Apache License 2.0