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 服务器：

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

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

2. 编译并运行客户端：

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. 确认服务器正在运行：

   curl http://192.168.1.100:3000/api/v1/rooms
   

2. 检查防火墙：

   # Windows
   netsh advfirewall firewall add rule name="FunMC" dir=in action=allow protocol=TCP localport=3000
   
   # Linux
   sudo ufw allow 3000/tcp
   

3. 确认网络连通：

   ping 192.168.1.100
   

问题 2：P2P 连接失败

症状： 始终使用中继连接

排查步骤：

1. 检查 UDP 端口：

   # 确认端口 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