Meshray-Manager/docs/快速指南_Phase1-2.md

# 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`

---

## 🚀 快速开始

### 方式一：直接运行（带托盘图标）

```powershell
# 双击或命令行启动
.\meshray.exe

# 访问 Web UI
http://localhost:9531
```

**特点**:
- ✅ 显示桌面托盘图标
- ✅ 可右键退出
- ✅ 适合开发测试

---

### 方式二：Windows 服务模式（推荐生产环境）

#### 安装服务

```powershell
# 管理员 PowerShell
.\meshray.exe install
```

**输出**:
```
✅ MeshRay 服务已安装成功
💡 使用以下命令管理服务:
   启动：sc start MeshRay
   停止：sc stop MeshRay
   卸载：meshray.exe service uninstall
```

#### 启动服务

```powershell
# 方式 1: 使用 meshray 命令
.\meshray.exe start

# 方式 2: 使用 sc 命令
sc start MeshRay

# 方式 3: 使用服务管理器
services.msc → 找到 "MeshRay Service" → 右键启动
```

#### 验证运行

```powershell
# 查看服务状态
Get-Service MeshRay

# 输出示例:
# Name   Status StartType
# ----   ------ ---------
# MeshRay Running Automatic
```

#### 查看日志

```powershell
# 服务日志
Get-Content .\logs\service.log -Tail 20

# 应用日志
Get-Content .\logs\meshray.log -Tail 20
```

#### 停止服务

```powershell
.\meshray.exe stop
# 或
Stop-Service MeshRay
```

#### 卸载服务

```powershell
# 管理员 PowerShell
.\meshray.exe uninstall
```

---

## 🔧 功能详解

### 1. 级联删除网络

#### Web UI 操作

1. 进入网络列表页
2. 找到目标网络
3. 点击"删除网络"按钮
4. **如果网络下有设备**:
   - ❌ 普通删除：提示"请先删除设备"
   - ✅ 强制删除：勾选"确认强制删除"复选框

#### API 调用

```bash
# 普通删除（有设备时失败）
curl -X DELETE http://localhost:9531/api/v1/networks/123

# 强制删除（级联删除设备和网络）
curl -X DELETE "http://localhost:9531/api/v1/networks/123?force=true"
```

#### 响应示例

**成功**:
```json
{
  "message": "网络已删除"
}
```

**失败（未使用 force）**:
```json
{
  "error": "该网络下仍有设备，为避免误操作，请确认后强制删除"
}
```

---

### 2. Dashboard 链路分布

#### 访问路径

```
http://localhost:9531/dashboard
```

#### 显示内容

- **总体统计**:
  - P2P 直连数量
  - Relay 转发数量
  - P2P 百分比（饼图）

- **按网络分布**:
  - 每个网络的详细数据
  - 支持表格和图表切换

#### API 响应示例

```json
{
  "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**:
```bash
curl http://localhost:9531/api/v1/dashboard/system-info
```

**响应**:
```json
{
  "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**:
```bash
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**:
```bash
curl -X POST http://localhost:9531/api/v1/ddns/sync
```

#### 查看同步日志

```powershell
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
# 以管理员身份运行 PowerShell
Right-click PowerShell → Run as Administrator

# 再次执行
.\meshray.exe install
```

---

### 问题 2: 服务无法启动

**检查**:
```powershell
# 查看服务状态
Get-Service MeshRay

# 查看详细错误
Get-EventLog -LogName Application -Source MeshRay -Newest 10
```

**常见原因**:
- ❌ 端口被占用（9531）
- ❌ 配置文件错误
- ❌ 数据库文件损坏

**解决**:
```powershell
# 检查端口占用
netstat -ano | findstr :9531

# 检查配置文件
cat config.yaml

# 重装服务
.\meshray.exe uninstall
.\meshray.exe install
.\meshray.exe start
```

---

### 问题 3: 级联删除后设备仍在

**原因**: 前端缓存未刷新

**解决**:
```
1. 刷新浏览器（F5）
2. 清除浏览器缓存
3. 重新登录
```

**验证**:
```bash
# API 查询设备列表
curl http://localhost:9531/api/v1/devices?network_id=123
# 应该返回空数组 []
```

---

### 问题 4: Dashboard 显示"无数据"

**原因**: 还没有创建设备或网络

**解决**:
```
1. 创建至少一个网络
2. 添加至少一个设备
3. 等待 1-2 分钟数据采集
```

**验证**:
```bash
# 检查是否有网络
curl http://localhost:9531/api/v1/networks

# 检查是否有设备
curl http://localhost:9531/api/v1/devices
```

---

### 问题 5: IPv6 显示为"unknown"

**原因**: 系统未启用 IPv6 或没有公网 IPv6

**检查**:
```powershell
# 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. 生产环境部署

**推荐配置**:
```yaml
# config.yaml
server:
  port: 9531
  mode: release  # ← 生产模式

log:
  level: warn    # ← 减少日志量
  format: json   # ← 便于日志分析

database:
  path: ./data/meshray.db
```

**部署步骤**:
```powershell
# 1. 安装服务
.\meshray.exe install

# 2. 设置开机自启
sc config MeshRay start= auto

# 3. 启动服务
.\meshray.exe start

# 4. 验证
Get-Service MeshRay
```

---

### 2. 日志轮转配置

```yaml
# config.yaml
log:
  max_size: 100      # 每个文件最大 100 MB
  max_backups: 5     # 保留 5 个旧文件
  max_age: 30        # 保留 30 天
```

---

### 3. 备份策略

```powershell
# 每天凌晨 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
```

---

## 🆘 获取帮助

### 官方文档

- 📖 [项目 README](README.md)
- 📖 [Phase 1&2 实施报告](Phase1_2_Implementation_Report.md)
- 📖 [Master Review Report](Master_Review_Report.md.resolved)

### 社区支持

- 💬 GitHub Issues
- 📧 Email: support@meshray.dev
- 💬 Discord/Slack（待开通）

---

**祝你使用愉快！🎉**

**最后更新**: 2026-03-25