大海
141 lines
3.4 KiB
Markdown
141 lines
3.4 KiB
Markdown
# Network Tool - 异地组网工具 MVP
|
||
|
||
> PC Tool Factory 测试需求：异地组网工具最小可运行版本
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
network-tool/
|
||
├── apps/
|
||
│ ├── client-electron/ # Electron + React 桌面客户端
|
||
│ ├── control-server/ # Fastify + SQLite 控制服务器
|
||
│ └── relay-node/ # TCP 转发节点
|
||
├── packages/
|
||
│ ├── shared-types/ # 共享 TypeScript 类型定义
|
||
│ ├── shared-crypto/ # 加密工具 (JWT, bcrypt, SHA256)
|
||
│ └── shared-protocol/ # 网络协议 (帧编解码)
|
||
├── test-e2e.js # 端到端测试脚本
|
||
└── README.md
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
cd network-tool
|
||
npm install
|
||
```
|
||
|
||
### 2. 构建共享包
|
||
|
||
```bash
|
||
npm run build:shared
|
||
```
|
||
|
||
### 3. 启动 Control Server (终端 1)
|
||
|
||
```bash
|
||
npm run dev:server
|
||
# → http://localhost:3001
|
||
# → ws://localhost:3001/ws
|
||
```
|
||
|
||
### 4. 启动 Relay Node (终端 2)
|
||
|
||
```bash
|
||
npm run dev:relay
|
||
# → TCP: localhost:4101
|
||
# → 自动向服务器注册并发送心跳
|
||
```
|
||
|
||
### 5. 运行 E2E 测试 (终端 3)
|
||
|
||
```bash
|
||
node test-e2e.js
|
||
```
|
||
|
||
### 6. 启动 Client Desktop (终端 3)
|
||
|
||
```bash
|
||
cd apps/client-electron
|
||
npm run dev:main # 编译主进程 + 启动 Electron
|
||
npm run dev:renderer # 启动 Vite React dev server
|
||
```
|
||
|
||
## 验证结果
|
||
|
||
| 验收标准 | 状态 |
|
||
|----------|------|
|
||
| npm install 成功 | ✅ |
|
||
| 服务器启动成功 | ✅ |
|
||
| 节点启动成功 | ✅ |
|
||
| 客户端启动成功 | ⚠️ 源码完成，需 Electron 二进制 |
|
||
| 用户注册登录成功 | ✅ |
|
||
| 设备注册成功 | ✅ |
|
||
| 节点注册成功 | ✅ |
|
||
| Token 验证成功 | ✅ |
|
||
| 客户端消息转发成功 | ✅ (E2E Test A↔B PASS) |
|
||
| TypeScript 编译 | ✅ 5/5 包编译通过 |
|
||
|
||
## API 端点
|
||
|
||
### Auth
|
||
- `POST /api/auth/register` — 用户注册
|
||
- `POST /api/auth/login` — 用户登录
|
||
- `GET /api/auth/me` — 当前用户信息
|
||
|
||
### Devices
|
||
- `POST /api/devices/register` — 注册设备
|
||
- `GET /api/devices` — 设备列表
|
||
- `PATCH /api/devices/:id/status` — 更新状态
|
||
- `DELETE /api/devices/:id` — 删除设备
|
||
|
||
### Nodes
|
||
- `POST /api/nodes/register` — 节点注册
|
||
- `POST /api/nodes/heartbeat` — 心跳上报
|
||
- `GET /api/nodes` — 节点列表
|
||
- `GET /api/nodes/available` — 可用节点
|
||
|
||
### Connections
|
||
- `POST /api/connections/request` — 请求连接 Token
|
||
- `POST /api/connections/verify-token` — 节点验证 Token
|
||
- `POST /api/connections/disconnect` — 断开连接
|
||
- `GET /api/connections/logs` — 连接日志
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `PORT` | `3001` | 服务器端口 |
|
||
| `HOST` | `0.0.0.0` | 绑定地址 |
|
||
| `DB_PATH` | `./data/network.db` | 数据库路径 |
|
||
| `JWT_SECRET` | 开发密钥 | JWT 签名密钥 |
|
||
| `SERVER_URL` | `http://localhost:3001` | Relay Node 服务地址 |
|
||
| `NODE_NAME` | `relay-node-1` | 节点名称 |
|
||
| `TCP_PORT` | `4101` | 节点 TCP 端口 |
|
||
|
||
## 安全
|
||
|
||
- 密码 bcrypt 哈希存储
|
||
- JWT Token 鉴权（过期 24h）
|
||
- 连接 Token 5 分钟过期
|
||
- 节点必须向服务器验证客户端 Token
|
||
- 客户端不能伪造设备身份
|
||
- 日志不存储明文密码
|
||
|
||
## 技术栈
|
||
|
||
- **Server**: Fastify, sql.js (SQLite), JWT, WebSocket
|
||
- **Relay**: Node.js TCP, HTTP client, 帧协议
|
||
- **Client**: Electron, React, TypeScript, Vite
|
||
- **Shared**: TypeScript types, bcrypt, JWT, SHA256
|
||
|
||
## Build
|
||
|
||
```
|
||
TypeScript 文件: 22
|
||
总代码行数: ~2031
|
||
编译状态: 5/5 PASS
|
||
```
|