FunMC - Minecraft 联机助手

让 Minecraft 联机变得简单

下载 • 功能特性 • 快速开始 • 部署指南 • 开发指南

---

✨ 功能特性

• 🎮 一键联机 - 无需公网 IP，无需端口映射，简单几步即可与好友联机
• 🌐 P2P 直连 - 支持 NAT 穿透，延迟更低的点对点连接
• 🔄 智能中继 - P2P 失败时自动切换到中继模式，保证连通性
• 👥 好友系统 - 添加好友，随时查看在线状态
• 🏠 房间系统 - 创建公开或私密房间，支持密码保护
• 💬 实时聊天 - 房间内文字聊天功能
• 💻 跨平台 - 支持 Windows、macOS、Linux、iOS、Android
• 🔒 安全可靠 - JWT 认证，QUIC 加密传输
• 🎛️ 管理面板 - Web 管理界面，用户管理、房间管理、服务器配置
• 📦 一键部署 - Docker 一键部署，自动配置服务器和客户端
• 🔗 自动配置 - 客户端自动连接服务器，无需手动填写 IP

📥 下载

客户端会自动连接到预配置的服务器，无需手动配置 IP 地址。

平台	下载链接	系统要求
Windows	FunMC-Setup.exe	Windows 10+
macOS (Apple Silicon)	FunMC-arm64.dmg	macOS 11+
macOS (Intel)	FunMC-x64.dmg	macOS 10.13+
Linux	FunMC.AppImage	Ubuntu 18.04+
Android	FunMC.apk	Android 7.0+
iOS	App Store (即将上线)	iOS 13.0+

私有部署用户: 请访问你的服务器管理面板下载页面获取客户端

🚀 快速开始

作为主机（开服）

1. 启动 Minecraft 服务器

   • 可以是独立服务器 (默认端口 25565)
   • 也可以在单人世界中按 Esc → 对局域网开放 开启局域网联机

2. 在 FunMC 中创建房间

   • 登录 FunMC 客户端
   • 在大厅页面点击「创建房间」
   • 填写房间名称、游戏版本、最大人数
   • 可选：设置房间密码

3. 开始托管

   • 进入房间后点击「开始托管」
   • FunMC 会自动检测并连接到你的 Minecraft 服务器
   • 默认连接 127.0.0.1:25565

4. 邀请好友

   • 将房间分享给好友
   • 或让好友在大厅搜索你的房间

作为玩家（联机）

1. 加入房间

   • 在 FunMC 大厅找到目标房间
   • 点击加入（如有密码需输入）

2. 连接游戏

   • 在房间页面点击「连接」
   • 等待连接建立（优先尝试 P2P 直连）
   • 复制显示的本地代理地址（如 127.0.0.1:25566）

3. 进入游戏

   • 在 Minecraft 中选择「多人游戏」
   • 添加服务器，粘贴刚才复制的地址
   • 连接服务器，开始游戏！

🏗 架构说明

┌─────────────────────────────────────────────────────────────────┐
│                        FunMC 系统架构                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────┐         ┌─────────────┐         ┌─────────┐      │
│   │ 玩家 A  │◄──────►│  API 服务器  │◄──────►│ 玩家 B  │      │
│   │(FunMC)  │         │  (认证/房间) │         │(FunMC)  │      │
│   └────┬────┘         └──────┬──────┘         └────┬────┘      │
│        │                     │                     │            │
│        │              ┌──────┴──────┐              │            │
│        │              │ WebSocket   │              │            │
│        │              │ 信令服务器   │              │            │
│        │              └─────────────┘              │            │
│        │                                           │            │
│        │  ┌─────────────────────────────────────┐ │            │
│        │  │         P2P 直连 (优先)              │ │            │
│        └──┤  NAT 穿透 / UDP 打洞 / QUIC         ├─┘            │
│           └─────────────────────────────────────┘              │
│                           │                                     │
│                     (如果失败)                                   │
│                           ▼                                     │
│           ┌─────────────────────────────────────┐              │
│           │         中继服务器 (备用)            │              │
│           │  QUIC 隧道转发 Minecraft 流量       │              │
│           └─────────────────────────────────────┘              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

📦 部署指南

🚀 一键部署（推荐）

Linux/macOS:

curl -fsSL https://gt.funmc.cn/xiaobai/FunConnect/raw/main/deploy.sh | bash

或者使用 Docker Compose:

# 克隆仓库
git clone https://gt.funmc.cn/xiaobai/FunConnect.git
cd funmc

# 配置环境变量
cp .env.example .env
nano .env  # 修改 SERVER_IP 为你的服务器公网 IP

# 启动服务
docker-compose up -d

部署完成后:

• 管理面板: http://你的IP:3000/admin
• 客户端下载: http://你的IP:3000/download
• API 地址: http://你的IP:3000

详细部署文档请参考 DEPLOYMENT.md

🎛️ 管理面板功能

部署完成后访问 http://你的IP:3000/admin 进入管理面板:

• 仪表盘 - 服务器状态概览、在线用户/房间统计
• 用户管理 - 查看用户列表、封禁/解封用户
• 房间管理 - 查看房间列表、删除违规房间
• 客户端下载 - 管理客户端构建、查看下载统计
• 服务器设置 - 配置服务器名称、IP、功能开关
• 系统日志 - 查看服务器运行日志

📲 客户端自动配置

客户端启动时会自动:

1. 读取内嵌的服务器配置（构建时写入）
2. 或显示服务器连接页面让用户输入地址
3. 从服务器获取完整配置（名称、中继地址等）
4. 保存配置，下次启动自动连接

手动部署

1. 环境准备

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 安装 PostgreSQL (Ubuntu/Debian)
sudo apt update
sudo apt install postgresql postgresql-contrib

# 创建数据库
sudo -u postgres createdb funmc
sudo -u postgres psql -c "CREATE USER funmc WITH PASSWORD 'your_password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE funmc TO funmc;"

2. 编译服务端

# 编译主服务器
cargo build --release -p funmc-server

# 编译中继服务器
cargo build --release -p funmc-relay-server

3. 配置服务

创建 /etc/funmc/server.env:

DATABASE_URL=postgres://funmc:your_password@localhost/funmc
JWT_SECRET=your-super-secret-jwt-key-at-least-32-chars
BIND_ADDR=0.0.0.0:3000
QUIC_PORT=3001
RUST_LOG=info

创建 /etc/funmc/relay.env:

RELAY_PORT=7900
JWT_SECRET=your-super-secret-jwt-key-at-least-32-chars
RUST_LOG=info

4. 创建 Systemd 服务

# 复制服务文件
sudo cp deploy/funmc-server.service /etc/systemd/system/
sudo cp deploy/funmc-relay.service /etc/systemd/system/

# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable funmc-server funmc-relay
sudo systemctl start funmc-server funmc-relay

# 检查状态
sudo systemctl status funmc-server funmc-relay

5. 配置 Nginx 反向代理

server {
    listen 443 ssl http2;
    server_name fc.funmc.cn;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api/v1/ws {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

🛠 开发指南

项目结构

funmc/
├── shared/               # 共享库（数据模型、协议定义）
│   └── src/
│       ├── lib.rs
│       ├── models.rs     # 数据模型
│       └── protocol.rs   # 信令协议
├── server/               # 主服务端
│   └── src/
│       ├── main.rs
│       ├── api/          # REST API + 管理 API
│       ├── signaling/    # WebSocket 信令
│       └── relay/        # 内置中继
├── relay-server/         # 独立中继服务端
│   └── src/
│       └── main.rs
├── admin-panel/          # 服务端管理面板 (React)
│   └── src/
│       ├── pages/        # 仪表盘、用户、房间、设置等
│       ├── stores/       # Zustand 状态管理
│       └── components/
├── client/               # 桌面/移动客户端 (Tauri 2.0)
│   ├── src/              # Rust 后端
│   │   ├── commands/     # Tauri 命令
│   │   └── network/      # 网络模块 (QUIC, P2P, 中继)
│   └── ui/               # React 前端
│       ├── src/
│       │   ├── pages/    # 登录、大厅、房间等
│       │   ├── components/
│       │   └── stores/   # 认证、配置、网络等状态
│       └── package.json
├── scripts/              # 构建脚本
│   ├── build-client.sh   # 客户端构建脚本
│   └── build-client.ps1
├── deploy.sh             # 一键部署脚本
├── docker-compose.yml    # Docker Compose 配置
├── Dockerfile.server     # 服务端 Docker 镜像
├── Dockerfile.relay      # 中继服务器 Docker 镜像
└── docs/                 # 文档

技术栈

组件	技术
后端框架	Axum
数据库	PostgreSQL + SQLx
传输协议	QUIC (quinn)
桌面框架	Tauri 2.0
前端	React + TypeScript + Tailwind CSS
状态管理	Zustand
NAT 穿透	STUN + UDP 打洞

本地开发

# 1. 克隆仓库
git clone https://gt.funmc.cn/xiaobai/FunConnect.git
cd funmc

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

# 3. 配置环境变量
cp server/.env.example server/.env
# 编辑 server/.env

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

# 5. 启动主服务器
cargo run

# 6. 新开终端，启动客户端
cd client/ui
npm install
cd ..
cargo tauri dev

构建发布版本

# Windows
cd client
cargo tauri build

# macOS (需要在 Mac 上)
cargo tauri build --target universal-apple-darwin

# Linux
cargo tauri build --target x86_64-unknown-linux-gnu

📋 API 文档

认证

方法	路径	描述
POST	/api/v1/auth/register	用户注册
POST	/api/v1/auth/login	用户登录
POST	/api/v1/auth/refresh	刷新令牌
POST	/api/v1/auth/logout	退出登录

房间

方法	路径	描述
GET	/api/v1/rooms	获取房间列表
POST	/api/v1/rooms	创建房间
GET	/api/v1/rooms/:id	获取房间详情
GET	/api/v1/rooms/:id/members	获取房间成员
POST	/api/v1/rooms/:id/join	加入房间
POST	/api/v1/rooms/:id/leave	离开房间
GET	/api/v1/rooms/:id/host-info	获取主机连接信息

好友

方法	路径	描述
GET	/api/v1/friends	获取好友列表
GET	/api/v1/friends/requests	获取好友请求
POST	/api/v1/friends/request	发送好友请求
PUT	/api/v1/friends/:id/accept	接受好友请求
DELETE	/api/v1/friends/:id	删除好友

中继

方法	路径	描述
GET	/api/v1/relay/nodes	获取中继节点列表
POST	/api/v1/relay/nodes/:id/ping	上报节点延迟

WebSocket 信令

连接地址: wss://fc.funmc.cn/api/v1/ws?token=<jwt>

消息类型:

• offer / answer / ice_candidate - P2P 连接协商
• chat_message / send_chat - 房间聊天
• member_joined / member_left - 成员变动通知
• room_invite - 房间邀请
• ping / pong - 心跳保活

🌐 官方服务器

服务	地址	端口
API 服务器	https://fc.funmc.cn	443
中继节点 - 主线路	fc.funmc.cn	7900 (UDP/QUIC)
中继节点 - 备用线路	fc.funmc.cn	7901 (UDP/QUIC)

🔧 故障排除

常见问题

Q: 无法连接到服务器

• 检查网络连接
• 确认防火墙允许 FunMC 通过
• 尝试使用中继模式

Q: P2P 连接失败

• 双方都是对称型 NAT 时无法打洞，会自动使用中继
• 检查路由器 UPnP 设置

Q: Minecraft 无法连接到代理地址

• 确认 FunMC 显示"已连接"状态
• 检查代理地址是否正确复制
• 尝试重新点击"连接"

Q: 延迟很高

• 尝试选择更近的中继节点
• 检查是否成功建立 P2P 连接（显示"P2P 直连"）

日志位置

• Windows: %APPDATA%\com.funmc.app\logs
• macOS: ~/Library/Logs/com.funmc.app
• Linux: ~/.local/share/com.funmc.app/logs

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 提交 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

---

魔幻方开发 ⭐

官网 • 文档 • 反馈