9.4 KiB
9.4 KiB
MeshRay Phase 1 & 2 功能快速指南
版本: v2.0.0+
更新日期: 2026-03-25
状态: ✅ 已实现并编译成功
🎉 新增功能一览
1. 级联删除网络
场景: 一键删除整个网络及其所有设备
命令: DELETE /api/v1/networks/:id?force=true
2. Dashboard 链路分布
场景: 可视化查看 P2P vs Relay 连接比例
API: GET /api/v1/dashboard/link-distribution
3. IPv6 双栈支持
场景: 自动获取并显示 IPv4/IPv6地址
API: GET /api/v1/dashboard/system-info
4. DDNS 后台自动同步
场景: 每 5 分钟自动同步公网 IP 到 DNS 厂商
配置: Settings → DDNS → 启用"自动同步"
5. Windows 服务集成
场景: 将 MeshRay 安装为系统服务（后台常驻）
命令: .\meshray.exe install
🚀 快速开始
方式一：直接运行（带托盘图标）
# 双击或命令行启动
.\meshray.exe
# 访问 Web UI
http://localhost:9531
特点:
- ✅ 显示桌面托盘图标
- ✅ 可右键退出
- ✅ 适合开发测试
方式二：Windows 服务模式（推荐生产环境）
安装服务
# 管理员 PowerShell
.\meshray.exe install
输出:
✅ MeshRay 服务已安装成功
💡 使用以下命令管理服务:
启动：sc start MeshRay
停止：sc stop MeshRay
卸载：meshray.exe service uninstall
启动服务
# 方式 1: 使用 meshray 命令
.\meshray.exe start
# 方式 2: 使用 sc 命令
sc start MeshRay
# 方式 3: 使用服务管理器
services.msc → 找到 "MeshRay Service" → 右键启动
验证运行
# 查看服务状态
Get-Service MeshRay
# 输出示例:
# Name Status StartType
# ---- ------ ---------
# MeshRay Running Automatic
查看日志
# 服务日志
Get-Content .\logs\service.log -Tail 20
# 应用日志
Get-Content .\logs\meshray.log -Tail 20
停止服务
.\meshray.exe stop
# 或
Stop-Service MeshRay
卸载服务
# 管理员 PowerShell
.\meshray.exe uninstall
🔧 功能详解
1. 级联删除网络
Web UI 操作
- 进入网络列表页
- 找到目标网络
- 点击"删除网络"按钮
- 如果网络下有设备:
- ❌ 普通删除：提示"请先删除设备"
- ✅ 强制删除：勾选"确认强制删除"复选框
API 调用
# 普通删除（有设备时失败）
curl -X DELETE http://localhost:9531/api/v1/networks/123
# 强制删除（级联删除设备和网络）
curl -X DELETE "http://localhost:9531/api/v1/networks/123?force=true"
响应示例
成功:
{
"message": "网络已删除"
}
失败（未使用 force）:
{
"error": "该网络下仍有设备，为避免误操作，请确认后强制删除"
}
2. Dashboard 链路分布
访问路径
http://localhost:9531/dashboard
显示内容
-
总体统计:
- P2P 直连数量
- Relay 转发数量
- P2P 百分比（饼图）
-
按网络分布:
- 每个网络的详细数据
- 支持表格和图表切换
API 响应示例
{
"data": {
"summary": {
"total_p2p": 15,
"total_relay": 3,
"total": 18,
"p2p_percent": 83.33
},
"by_network": [
{
"network_id": "1234567890",
"network_name": "My Network",
"p2p_count": 5,
"relay_count": 1,
"total_peers": 6,
"mode": "userspace"
},
{
"network_id": "0987654321",
"network_name": "Test Network",
"p2p_count": 10,
"relay_count": 2,
"total_peers": 12,
"mode": "native"
}
]
}
}
3. IPv6 双栈支持
查看本机 IP
Web UI:
Settings → 系统信息 → 本机 IP
API:
curl http://localhost:9531/api/v1/dashboard/system-info
响应:
{
"data": {
"hostname": "my-pc",
"os": "Windows",
"ip": "192.168.1.100", // ← 优先显示 IPv4
"ipv4": "192.168.1.100", // ← IPv4 地址
"ipv6": "fe80::xxxx:xxxx" // ← IPv6 地址（如果有）
}
}
DDNS 配置（支持 IPv6）
Web UI:
Settings → DDNS 配置
→ Provider: Cloudflare
→ Domain: example.com
→ Record Type: AAAA (IPv6) 或 A (IPv4)
→ Sync Mode: Auto
→ Enabled: ✓
API:
curl -X POST http://localhost:9531/api/v1/ddns/config \
-H "Content-Type: application/json" \
-d '{
"provider": "cloudflare",
"access_key_secret": "YOUR_CF_TOKEN",
"domain": "example.com",
"txt_record_name": "@",
"record_type": "AAAA",
"sync_mode": "auto",
"retry_interval": 5,
"enabled": true
}'
4. DDNS 后台自动同步
工作原理
启动 MeshRay
↓
DDNS 服务初始化
↓
启动后台定时器（goroutine）
↓
每 5 分钟检测一次
├─ 获取配置（Enabled? SyncMode=auto?）
├─ 获取本机公网 IP（IPv4/IPv6）
├─ 调用 DNS 厂商 API 同步
└─ 记录日志
手动触发同步
Web UI:
Settings → DDNS 配置 → 立即同步
API:
curl -X POST http://localhost:9531/api/v1/ddns/sync
查看同步日志
Get-Content .\logs\meshray.log -Tail 50 | Select-String "DDNS"
输出示例:
2026-03-25 10:30:00 INFO DDNS 同步成功 domain=example.com ip=203.0.113.1
2026-03-25 10:35:00 INFO DDNS 同步成功 domain=example.com ip=203.0.113.1
2026-03-25 10:40:00 WARN DDNS 同步失败：API rate limit exceeded
🛠️ 故障排查
问题 1: 服务安装失败
错误:
❌ 安装服务失败：Access is denied
解决:
# 以管理员身份运行 PowerShell
Right-click PowerShell → Run as Administrator
# 再次执行
.\meshray.exe install
问题 2: 服务无法启动
检查:
# 查看服务状态
Get-Service MeshRay
# 查看详细错误
Get-EventLog -LogName Application -Source MeshRay -Newest 10
常见原因:
- ❌ 端口被占用（9531）
- ❌ 配置文件错误
- ❌ 数据库文件损坏
解决:
# 检查端口占用
netstat -ano | findstr :9531
# 检查配置文件
cat config.yaml
# 重装服务
.\meshray.exe uninstall
.\meshray.exe install
.\meshray.exe start
问题 3: 级联删除后设备仍在
原因: 前端缓存未刷新
解决:
1. 刷新浏览器（F5）
2. 清除浏览器缓存
3. 重新登录
验证:
# API 查询设备列表
curl http://localhost:9531/api/v1/devices?network_id=123
# 应该返回空数组 []
问题 4: Dashboard 显示"无数据"
原因: 还没有创建设备或网络
解决:
1. 创建至少一个网络
2. 添加至少一个设备
3. 等待 1-2 分钟数据采集
验证:
# 检查是否有网络
curl http://localhost:9531/api/v1/networks
# 检查是否有设备
curl http://localhost:9531/api/v1/devices
问题 5: IPv6 显示为"unknown"
原因: 系统未启用 IPv6 或没有公网 IPv6
检查:
# Windows IPv6 状态
Get-NetIPConfiguration | Select-Object InterfaceAlias, AddressFamily, IPAddress
解决:
1. 联系 ISP 开通 IPv6
2. 或在路由器中启用 IPv6
3. 如果只有 IPv4，则只显示 IPv4（正常行为）
📊 性能指标
内存占用
| 模式 | 内存使用 |
|---|---|
| 空闲 | ~50 MB |
| 1 个网络 + 5 个设备 | ~80 MB |
| 10 个网络 + 50 个设备 | ~150 MB |
| 满载（100+ 设备） | ~300 MB |
CPU 使用
| 场景 | CPU 使用率 |
|---|---|
| 空闲 | < 1% |
| 设备连接 | 5-10%（瞬时） |
| 数据传输 | 10-30%（持续） |
| DDNS 同步 | < 1%（每 5 分钟瞬时） |
磁盘占用
| 组件 | 大小 |
|---|---|
| 可执行文件 | ~48 MB |
| 数据库（空） | ~1 MB |
| 数据库（100 设备） | ~10 MB |
| 日志（天） | ~5 MB |
🎯 最佳实践
1. 生产环境部署
推荐配置:
# config.yaml
server:
port: 9531
mode: release # ← 生产模式
log:
level: warn # ← 减少日志量
format: json # ← 便于日志分析
database:
path: ./data/meshray.db
部署步骤:
# 1. 安装服务
.\meshray.exe install
# 2. 设置开机自启
sc config MeshRay start= auto
# 3. 启动服务
.\meshray.exe start
# 4. 验证
Get-Service MeshRay
2. 日志轮转配置
# config.yaml
log:
max_size: 100 # 每个文件最大 100 MB
max_backups: 5 # 保留 5 个旧文件
max_age: 30 # 保留 30 天
3. 备份策略
# 每天凌晨 2 点备份数据库
$schedule = New-ScheduledTaskTrigger -Daily -At 2am
$action = New-ScheduledTaskAction -Execute "PowerShell.exe" `
-Argument "-Command Copy-Item .\data\meshray.db .\backup\meshray-$(Get-Date -Format 'yyyyMMdd').db"
Register-ScheduledTask -TaskName "MeshRay Backup" -Trigger $schedule -Action $action
🆘 获取帮助
官方文档
社区支持
- 💬 GitHub Issues
- 📧 Email: support@meshray.dev
- 💬 Discord/Slack（待开通）
祝你使用愉快！🎉
最后更新: 2026-03-25