FunConnect/README.md

# FunMC - Minecraft 联机助手

<div align="center">

**让 Minecraft 联机变得简单**

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.75+-orange.svg)](https://www.rust-lang.org/)
[![Tauri](https://img.shields.io/badge/tauri-2.0-blue.svg)](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>