470 lines
15 KiB
Markdown
470 lines
15 KiB
Markdown
# FunMC - Minecraft 联机助手
|
||
|
||
<div align="center">
|
||
|
||
**让 Minecraft 联机变得简单**
|
||
|
||
[](LICENSE)
|
||
[](https://www.rust-lang.org/)
|
||
[](https://tauri.app/)
|
||
|
||
[下载](#-下载) • [功能特性](#-功能特性) • [快速开始](#-快速开始) • [部署指南](#-部署指南) • [开发指南](#-开发指南)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## ✨ 功能特性
|
||
|
||
- 🎮 **一键联机** - 无需公网 IP，无需端口映射，简单几步即可与好友联机
|
||
- 🌐 **P2P 直连** - 支持 NAT 穿透，延迟更低的点对点连接
|
||
- 🔄 **智能中继** - P2P 失败时自动切换到中继模式，保证连通性
|
||
- 👥 **好友系统** - 添加好友，随时查看在线状态
|
||
- 🏠 **房间系统** - 创建公开或私密房间，支持密码保护
|
||
- 💬 **实时聊天** - 房间内文字聊天功能
|
||
- 💻 **跨平台** - 支持 Windows、macOS、Linux、iOS、Android
|
||
- 🔒 **安全可靠** - JWT 认证，QUIC 加密传输
|
||
- 🎛️ **管理面板** - Web 管理界面，用户管理、房间管理、服务器配置
|
||
- 📦 **一键部署** - Docker 一键部署，自动配置服务器和客户端
|
||
- 🔗 **自动配置** - 客户端自动连接服务器，无需手动填写 IP
|
||
|
||
## 📥 下载
|
||
|
||
客户端会自动连接到预配置的服务器，无需手动配置 IP 地址。
|
||
|
||
| 平台 | 下载链接 | 系统要求 |
|
||
|------|---------|---------|
|
||
| Windows | [FunMC-Setup.exe](https://fc.funmc.cn/download) | Windows 10+ |
|
||
| macOS (Apple Silicon) | [FunMC-arm64.dmg](https://fc.funmc.cn/download) | macOS 11+ |
|
||
| macOS (Intel) | [FunMC-x64.dmg](https://fc.funmc.cn/download) | macOS 10.13+ |
|
||
| Linux | [FunMC.AppImage](https://fc.funmc.cn/download) | Ubuntu 18.04+ |
|
||
| Android | [FunMC.apk](https://fc.funmc.cn/download) | 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:**
|
||
```bash
|
||
curl -fsSL https://gt.funmc.cn/xiaobai/FunConnect/raw/main/deploy.sh | bash
|
||
```
|
||
|
||
**或者使用 Docker Compose:**
|
||
```bash
|
||
# 克隆仓库
|
||
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](./docs/DEPLOYMENT.md)
|
||
|
||
### 🎛️ 管理面板功能
|
||
|
||
部署完成后访问 `http://你的IP:3000/admin` 进入管理面板:
|
||
|
||
- **仪表盘** - 服务器状态概览、在线用户/房间统计
|
||
- **用户管理** - 查看用户列表、封禁/解封用户
|
||
- **房间管理** - 查看房间列表、删除违规房间
|
||
- **客户端下载** - 管理客户端构建、查看下载统计
|
||
- **服务器设置** - 配置服务器名称、IP、功能开关
|
||
- **系统日志** - 查看服务器运行日志
|
||
|
||
### 📲 客户端自动配置
|
||
|
||
客户端启动时会自动:
|
||
1. 读取内嵌的服务器配置（构建时写入）
|
||
2. 或显示服务器连接页面让用户输入地址
|
||
3. 从服务器获取完整配置（名称、中继地址等）
|
||
4. 保存配置，下次启动自动连接
|
||
|
||
### 手动部署
|
||
|
||
#### 1. 环境准备
|
||
|
||
```bash
|
||
# 安装 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. 编译服务端
|
||
|
||
```bash
|
||
# 编译主服务器
|
||
cargo build --release -p funmc-server
|
||
|
||
# 编译中继服务器
|
||
cargo build --release -p funmc-relay-server
|
||
```
|
||
|
||
#### 3. 配置服务
|
||
|
||
创建 `/etc/funmc/server.env`:
|
||
|
||
```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`:
|
||
|
||
```env
|
||
RELAY_PORT=7900
|
||
JWT_SECRET=your-super-secret-jwt-key-at-least-32-chars
|
||
RUST_LOG=info
|
||
```
|
||
|
||
#### 4. 创建 Systemd 服务
|
||
|
||
```bash
|
||
# 复制服务文件
|
||
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 反向代理
|
||
|
||
```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 打洞 |
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
### 构建发布版本
|
||
|
||
```bash
|
||
# 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](LICENSE) 文件。
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**魔幻方开发** ⭐
|
||
|
||
[官网](https://fc.funmc.cn) • [文档](https://fc.funmc.cn/docs) • [反馈](https://gt.funmc.cn/xiaobai/FunConnect/issues)
|
||
|
||
</div>
|