16gagent/network-tool/README.md

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. 安装依赖

cd network-tool
npm install

2. 构建共享包

npm run build:shared

3. 启动 Control Server (终端 1)

npm run dev:server
# → http://localhost:3001
# → ws://localhost:3001/ws

4. 启动 Relay Node (终端 2)

npm run dev:relay
# → TCP: localhost:4101
# → 自动向服务器注册并发送心跳

5. 运行 E2E 测试 (终端 3)

node test-e2e.js

6. 启动 Client Desktop (终端 3)

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