FunConnect/README.md

# FunMC - Minecraft 联机平台

一个支持多节点中继的 Minecraft 联机平台，让玩家无需公网IP即可轻松联机。

## 功能特性

- **TCP 中继代理** - 自动转发 Minecraft 网络流量，支持 Java 版和基岩版
- **多节点集群** - 支持添加多台 Ubuntu 中继服务器，自动负载均衡
- **房间系统** - 创建/加入房间，支持密码保护
- **Web 管理面板** - 现代化 UI，支持任意平台浏览器访问
- **实时状态** - WebSocket 实时推送服务器状态
- **一键部署** - 提供 Ubuntu 自动安装脚本和 systemd 服务

## 架构设计

```
┌─────────────────────────────────────────────┐
│                  Web 管理面板                  │
│            (React + TailwindCSS)             │
└──────────────────┬──────────────────────────┘
                   │ HTTP/WebSocket
┌──────────────────▼──────────────────────────┐
│              主节点 (Master)                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│  │ REST API │ │ 房间管理  │ │ 节点管理      │ │
│  └──────────┘ └──────────┘ └──────────────┘ │
│  ┌──────────────────────────────────────┐   │
│  │          TCP 中继引擎                  │   │
│  └──────────────────────────────────────┘   │
└──────────────────┬──────────────────────────┘
                   │ 心跳 + API
     ┌─────────────┼─────────────┐
     ▼             ▼             ▼
┌─────────┐  ┌─────────┐  ┌─────────┐
│ 工作节点1 │  │ 工作节点2 │  │ 工作节点N │
│ (Ubuntu) │  │ (Ubuntu) │  │ (Ubuntu) │
└─────────┘  └─────────┘  └─────────┘
```

## 快速开始

### 前置条件

- Node.js 18+ 
- Ubuntu 20.04+ (中继服务器)

### 本地开发

```bash
# 1. 安装服务端依赖
cd server
npm install

# 2. 创建配置文件
cp .env.example .env
# 编辑 .env 设置 IS_MASTER=true

# 3. 启动服务端
npm run dev

# 4. 安装 Web 客户端依赖
cd ../web
npm install

# 5. 启动 Web 客户端
npm run dev
```

访问 http://localhost:5173 打开管理面板。

### Ubuntu 服务器部署

#### 部署主节点

```bash
# 上传项目文件到服务器后
sudo bash deploy/install.sh master relay-master
```

#### 部署工作节点

```bash
sudo bash deploy/install.sh worker relay-node-2
# 按提示输入主节点 URL
```

### 添加新节点

1. 在新的 Ubuntu 服务器上部署工作节点
2. 在 Web 管理面板「节点管理」→「添加节点」中注册
3. 节点会自动加入集群并接收心跳检查

## 使用流程

### 房主（开服方）

1. 启动本地 Minecraft 服务器（或开启局域网模式）
2. 在 Web 面板创建房间，记录房间号
3. 运行 FunMC 客户端连接中继服务器，注册为房主
4. 将房间号分享给好友

### 玩家（加入方）

1. 获取房间号
2. 在 Minecraft 中添加服务器，地址填写 `中继服务器IP:25565`
3. 使用 FunMC 客户端连接中继服务器，输入房间号加入

## 桌面客户端

FunConnect 桌面客户端基于 Electron 构建，提供图形化界面连接中继服务器。

### 功能
- **连接服务器** - 输入中继服务器地址一键连接
- **浏览房间** - 查看所有在线联机房间
- **创建房间** - 将本地MC服务器共享给好友
- **加入房间** - 输入房间号，自动建立本地代理，MC中添加 `127.0.0.1:25566` 即可联机
- **自定义窗口** - 无边框设计，现代化MC风格UI

### 运行客户端

```bash
cd client
npm install
npm run dev
```

### 打包客户端

```bash
cd client
npm run dist
# 输出到 client/release/ 目录
```

## 项目结构

```
FunConnect/
├── server/                # 中继服务端
│   ├── src/
│   │   ├── index.ts       # 主入口
│   │   ├── config.ts      # 配置管理
│   │   ├── logger.ts      # 日志系统
│   │   ├── relay.ts       # TCP 中继引擎
│   │   ├── room.ts        # 房间管理
│   │   ├── node-manager.ts # 多节点管理
│   │   ├── api.ts         # REST API 路由
│   │   └── websocket.ts   # WebSocket 实时通信
│   ├── .env.example       # 配置示例
│   ├── package.json
│   └── tsconfig.json
├── web/                   # Web 管理面板
│   ├── src/
│   │   ├── main.tsx       # 入口
│   │   ├── App.tsx        # 路由和布局
│   │   ├── api.ts         # API 客户端
│   │   ├── index.css      # TailwindCSS 样式
│   │   └── pages/
│   │       ├── Dashboard.tsx  # 仪表盘
│   │       ├── Rooms.tsx      # 房间列表
│   │       ├── CreateRoom.tsx # 创建房间
│   │       ├── Nodes.tsx      # 节点管理
│   │       └── AddNode.tsx    # 添加节点
│   ├── package.json
│   └── vite.config.ts
├── client/                # Electron 桌面客户端
│   ├── src/main/
│   │   ├── index.ts       # Electron 主进程
│   │   ├── preload.ts     # 预加载脚本
│   │   ├── api-client.ts  # API 客户端
│   │   ├── relay-client.ts # TCP 中继连接
│   │   └── local-proxy.ts # 本地代理服务器
│   ├── renderer/
│   │   ├── index.html     # 客户端界面
│   │   ├── style.css      # 样式
│   │   └── app.js         # 交互逻辑
│   └── package.json
├── deploy/
│   └── install.sh         # Ubuntu 一键部署脚本
└── README.md
```

## API 文档

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/health` | 健康检查 |
| GET | `/api/stats` | 服务器统计 |
| GET | `/api/rooms` | 房间列表 |
| POST | `/api/rooms` | 创建房间 |
| DELETE | `/api/rooms/:id` | 删除房间 |
| GET | `/api/nodes` | 节点列表（主节点） |
| POST | `/api/nodes/register` | 注册节点（主节点） |
| DELETE | `/api/nodes/:id` | 移除节点（主节点） |
| GET | `/api/nodes/best` | 获取最佳节点（主节点） |
| GET | `/api/cluster/rooms` | 集群房间列表（主节点） |

## 技术栈

- **服务端**: Node.js, TypeScript, Express, WebSocket
- **Web 面板**: React 18, Vite, TailwindCSS, Lucide Icons
- **部署**: Ubuntu, systemd, Bash

## License

MIT