FunConnect/docs/LAN_TEST.md

# FunMC 局域网联机测试指南

本文档介绍如何测试 FunMC 的局域网联机功能。

## 测试环境准备

### 硬件要求

- 至少 2 台电脑（或使用虚拟机）
- 所有设备在同一局域网内
- 每台设备需安装 Minecraft Java Edition

### 软件要求

- PostgreSQL 14+
- Rust 1.75+
- Node.js 18+
- Minecraft Java Edition 1.16+

---

## 测试步骤

### 第一步：部署本地服务器

在其中一台电脑上部署 FunMC 服务器：

```bash
# 1. 克隆项目
git clone https://gt.funmc.cn/xiaobai/FunConnect.git
cd FunConnect

# 2. 启动数据库
docker run -d --name funmc-db \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=funmc \
  postgres:14

# 3. 配置环境变量
cat > server/.env << EOF
DATABASE_URL=postgres://postgres:password@localhost/funmc
JWT_SECRET=test-jwt-secret-for-local-development
BIND_ADDR=0.0.0.0:3000
QUIC_PORT=3001
RUST_LOG=info
EOF

# 4. 运行数据库迁移
cd server
cargo sqlx database create
cargo sqlx migrate run

# 5. 启动主服务器
cargo run
```

记录服务器的局域网 IP 地址（如 `192.168.1.100`）。

### 第二步：配置客户端

在所有参与测试的电脑上：

1. 修改客户端配置文件 `client/src/config.rs`:

```rust
pub const DEFAULT_SERVER_URL: &str = "http://192.168.1.100:3000";
```

2. 编译并运行客户端：

```bash
cd client/ui
npm install
cd ..
cargo tauri dev
```

### 第三步：测试场景

#### 场景 1：基本局域网联机

**主机操作：**
1. 启动 Minecraft，创建单人世界
2. 按 `Esc` → `对局域网开放`
3. 选择游戏模式，点击「开始局域网世界」
4. 记下显示的端口号（如 25565）
5. 打开 FunMC 客户端
6. 注册/登录账号
7. 创建房间（填写房间名、游戏版本）
8. 点击「开始托管」

**预期结果：**
- FunMC 显示"托管中"状态
- 显示 QUIC 端口号

**玩家操作：**
1. 打开 FunMC 客户端
2. 登录账号
3. 在大厅找到主机创建的房间
4. 点击加入房间
5. 在房间页面点击「连接」
6. 等待连接建立
7. 复制显示的地址（如 `127.0.0.1:25566`）
8. 打开 Minecraft → 多人游戏 → 添加服务器
9. 粘贴地址并连接

**预期结果：**
- FunMC 显示连接类型（P2P 直连 或 中继）
- 能够成功进入 Minecraft 服务器

#### 场景 2：P2P 直连测试

在局域网环境下，两台电脑应该能够建立 P2P 直连。

**验证方法：**
1. 连接成功后，检查 FunMC 显示的连接类型
2. 应显示「P2P 直连」
3. 延迟应该很低（通常 < 10ms）

**如果显示「中继」：**
- 检查防火墙设置
- 确认 UDP 端口 34000-34100 未被阻止
- 检查路由器是否启用了 UPnP

#### 场景 3：房间聊天测试

1. 主机和玩家都进入同一房间
2. 在房间页面的聊天框中发送消息
3. 验证双方都能收到消息

**预期结果：**
- 消息实时显示
- 显示发送者用户名和时间

#### 场景 4：多玩家测试

1. 让 3 人以上加入同一房间
2. 所有人都点击「连接」
3. 所有人都进入 Minecraft 服务器

**预期结果：**
- 所有玩家都能成功连接
- 游戏内能看到所有玩家

#### 场景 5：断线重连测试

1. 建立连接并进入游戏
2. 在 FunMC 中点击「断开连接」
3. 重新点击「连接」
4. 在 Minecraft 中重新连接服务器

**预期结果：**
- 能够重新建立连接
- 游戏继续正常进行

---

## 测试检查清单

### 服务端检查

| 检查项 | 预期结果 | 实际结果 |
|--------|---------|---------|
| 服务器启动 | 无错误日志 | |
| 数据库连接 | 连接成功 | |
| API 响应 | 返回 200 OK | |
| WebSocket | 能够建立连接 | |

### 客户端检查

| 检查项 | 预期结果 | 实际结果 |
|--------|---------|---------|
| 注册功能 | 成功创建账号 | |
| 登录功能 | 成功登录 | |
| 创建房间 | 房间出现在大厅 | |
| 加入房间 | 成功进入房间 | |
| 开始托管 | 状态显示"托管中" | |
| 连接功能 | 显示代理地址 | |
| 聊天功能 | 消息实时同步 | |

### 网络检查

| 检查项 | 预期结果 | 实际结果 |
|--------|---------|---------|
| P2P 连接 | 局域网内成功 | |
| 中继连接 | 作为备用可用 | |
| 延迟 | P2P < 10ms | |
| 数据传输 | Minecraft 流量正常 | |

---

## 常见问题排查

### 问题 1：无法连接到服务器

**症状：** 客户端显示"连接失败"

**排查步骤：**
1. 确认服务器正在运行：
   ```bash
   curl http://192.168.1.100:3000/api/v1/rooms
   ```
2. 检查防火墙：
   ```bash
   # Windows
   netsh advfirewall firewall add rule name="FunMC" dir=in action=allow protocol=TCP localport=3000
   
   # Linux
   sudo ufw allow 3000/tcp
   ```
3. 确认网络连通：
   ```bash
   ping 192.168.1.100
   ```

### 问题 2：P2P 连接失败

**症状：** 始终使用中继连接

**排查步骤：**
1. 检查 UDP 端口：
   ```bash
   # 确认端口 34000-34100 未被占用
   netstat -an | grep 34000
   ```
2. 检查 NAT 类型（对称型 NAT 无法打洞）
3. 暂时禁用防火墙测试

### 问题 3：Minecraft 无法连接

**症状：** 在 Minecraft 中添加服务器后连接失败

**排查步骤：**
1. 确认 FunMC 显示"已连接"
2. 检查代理地址是否正确复制
3. 确认 Minecraft 服务器正在运行
4. 检查 Minecraft 版本兼容性

### 问题 4：延迟过高

**症状：** 游戏卡顿，延迟 > 100ms

**排查步骤：**
1. 检查是否使用 P2P 直连
2. 检查网络带宽
3. 关闭其他占用带宽的程序
4. 尝试使用有线网络代替 WiFi

---

## 性能测试

### 延迟测试

使用 FunMC 内置的延迟显示功能：

| 连接类型 | 预期延迟 |
|---------|---------|
| P2P (局域网) | < 5ms |
| P2P (公网) | 10-50ms |
| 中继 | 50-150ms |

### 带宽测试

Minecraft 典型带宽需求：
- 单人连接：约 50-100 KB/s
- 多人服务器：每人约 100-200 KB/s

---

## 测试报告模板

```
测试日期: ____________
测试人员: ____________
FunMC 版本: ____________

测试环境:
- 服务器 IP: ____________
- 参与电脑数量: ____________
- Minecraft 版本: ____________

测试结果:
- 基本联机: [ ] 通过 [ ] 失败
- P2P 直连: [ ] 通过 [ ] 失败
- 房间聊天: [ ] 通过 [ ] 失败
- 多玩家: [ ] 通过 [ ] 失败
- 断线重连: [ ] 通过 [ ] 失败

问题记录:
____________________________________________

建议改进:
____________________________________________
```

---

## 联系支持

如测试中遇到问题，请通过以下方式反馈：

- 项目 Issues: https://gt.funmc.cn/xiaobai/FunConnect/issues
- 邮箱: support@fc.funmc.cn

---

*魔幻方开发 © 2024*