# FunConnect 服务端部署教程

本教程详细介绍如何在 Ubuntu 服务器上部署 FunConnect 中继服务器，包括主节点和工作节点的完整部署流程。

---

## 目录

1. [环境要求](#1-环境要求)
2. [方式一：一键部署](#2-方式一一键部署)
3. [方式二：手动部署](#3-方式二手动部署)
4. [部署主节点](#4-部署主节点)
5. [部署工作节点](#5-部署工作节点)
6. [部署 Web 管理面板](#6-部署-web-管理面板)
7. [防火墙配置](#7-防火墙配置)
8. [Nginx 反向代理（可选）](#8-nginx-反向代理可选)
9. [SSL 证书配置（可选）](#9-ssl-证书配置可选)
10. [多节点集群配置](#10-多节点集群配置)
11. [运维管理](#11-运维管理)
12. [常见问题](#12-常见问题)

---

## 1. 环境要求

| 项目 | 要求 |
|------|------|
| 操作系统 | Ubuntu 20.04 / 22.04 / 24.04 LTS |
| CPU | 1核+ （推荐2核+） |
| 内存 | 512MB+ （推荐1GB+） |
| 网络 | 公网IP，开放 TCP 3000 和 25565 端口 |
| 软件 | Node.js 18+, npm |

> **带宽建议**：每个联机房间大约需要 0.5-2 Mbps 带宽，请根据预计房间数量选择合适的服务器。

---

## 2. 方式一：一键部署

适合快速部署单个主节点。

### 2.1 上传项目文件

将 `server/` 目录上传到服务器：

```bash
# 在本地执行（将server目录上传到服务器）
scp -r server/ root@your-server-ip:/root/funconnect-server/

# 或者使用 Git 克隆
ssh root@your-server-ip
git clone https://gt.funmc.cn/xiaobai/FunConnect.git
cd FunConnect/server
```

### 2.2 执行安装脚本

```bash
# 部署主节点
sudo bash deploy/install.sh master my-relay-server

# 部署工作节点
sudo bash deploy/install.sh worker relay-node-2
```

脚本会自动完成：
- 安装 Node.js 20.x（如未安装）
- 创建安装目录 `/opt/funmc`
- 安装依赖、编译 TypeScript
- 生成 `.env` 配置文件
- 创建 systemd 服务并自动启动

### 2.3 验证安装

```bash
# 查看服务状态
systemctl status funmc

# 测试 API
curl http://localhost:3000/api/health
# 应返回: {"status":"ok","nodeId":"...","isMaster":true,...}
```

---

## 3. 方式二：手动部署

适合需要自定义配置的场景。

### 3.1 安装 Node.js

```bash
# 方法一：使用 NodeSource 仓库（推荐）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 方法二：使用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

# 验证
node -v   # 应显示 v20.x.x
npm -v    # 应显示 10.x.x
```

### 3.2 创建项目目录

```bash
sudo mkdir -p /opt/funmc
sudo mkdir -p /opt/funmc/logs
cd /opt/funmc
```

### 3.3 上传并安装

```bash
# 将 server/ 内容复制到 /opt/funmc/
# 假设已上传到 /root/FunConnect/server/
sudo cp -r /root/FunConnect/server/* /opt/funmc/

# 安装依赖
cd /opt/funmc
sudo npm install --production

# 编译 TypeScript
sudo npx tsc
```

### 3.4 创建配置文件

```bash
sudo cp .env.example .env
sudo nano .env
```

---

## 4. 部署主节点

主节点是集群的核心，负责管理所有房间和工作节点。

### 4.1 配置文件

编辑 `/opt/funmc/.env`：

```ini
# ===== 网络配置 =====
# TCP 中继端口（Minecraft 流量转发）
RELAY_PORT=25565

# HTTP API 端口（管理面板和API）
API_PORT=3000

# ===== 节点配置 =====
# 节点名称（自定义，用于标识）
NODE_NAME=master-node

# 设为主节点
IS_MASTER=true

# 主节点URL（主节点自身留空）
MASTER_URL=

# ===== 安全配置 =====
# API 认证密钥（用于保护写操作，请修改为随机字符串）
SECRET=your-random-secret-key-here

# ===== 限制配置 =====
# 最大房间数
MAX_ROOMS=100

# 每房间最大玩家数
MAX_PLAYERS_PER_ROOM=20

# ===== 心跳配置 =====
# 心跳间隔（毫秒）
HEARTBEAT_INTERVAL=10000

# ===== 日志配置 =====
LOG_LEVEL=info
```

> **重要**：请将 `SECRET` 修改为一个强随机字符串，可以用 `openssl rand -hex 32` 生成。

### 4.2 创建 systemd 服务

```bash
sudo tee /etc/systemd/system/funmc.service > /dev/null << 'EOF'
[Unit]
Description=FunConnect Minecraft Relay Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/funmc
ExecStart=/usr/bin/node dist/index.js
Restart=always
RestartSec=5
Environment=NODE_ENV=production

# 日志输出到 journald
StandardOutput=journal
StandardError=journal

# 资源限制
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF
```

### 4.3 启动服务

```bash
sudo systemctl daemon-reload
sudo systemctl enable funmc
sudo systemctl start funmc

# 查看状态
sudo systemctl status funmc
```

### 4.4 验证主节点

```bash
# 健康检查
curl http://localhost:3000/api/health

# 查看统计
curl http://localhost:3000/api/stats

# 查看日志
sudo journalctl -u funmc -f
```

---

## 5. 部署工作节点

工作节点用于分担主节点的负载，可部署在不同地区的服务器上。

### 5.1 安装步骤

在新服务器上重复 [3.1] ~ [3.3] 的步骤。

### 5.2 配置文件

编辑 `/opt/funmc/.env`：

```ini
RELAY_PORT=25565
API_PORT=3000

# 工作节点名称（每个节点不同）
NODE_NAME=worker-node-guangzhou

# 不是主节点
IS_MASTER=false

# 主节点地址（替换为主节点的实际IP）
MASTER_URL=http://主节点IP:3000

# 与主节点相同的密钥
SECRET=same-secret-as-master

MAX_ROOMS=100
MAX_PLAYERS_PER_ROOM=20
HEARTBEAT_INTERVAL=10000
LOG_LEVEL=info

# 本机公网IP（用于向主节点注册）
PUBLIC_HOST=本机公网IP
```

### 5.3 启动并注册

```bash
# 启动工作节点
sudo systemctl start funmc

# 验证工作节点已连接到主节点
curl http://localhost:3000/api/health

# 在主节点上查看是否注册成功
curl http://主节点IP:3000/api/nodes
```

### 5.4 手动注册工作节点

如果工作节点没有自动注册，可以通过 API 手动注册：

```bash
curl -X POST http://主节点IP:3000/api/nodes/register \
  -H "Content-Type: application/json" \
  -H "x-auth-token: your-secret-key" \
  -d '{
    "name": "worker-node-guangzhou",
    "host": "工作节点公网IP",
    "apiPort": 3000,
    "relayPort": 25565,
    "maxRooms": 100,
    "region": "guangzhou"
  }'
```

---

## 6. 部署 Web 管理面板

Web 管理面板用于可视化管理服务器。

### 6.1 开发模式

```bash
cd /opt/funmc/web
npm install
npm run dev
# 访问 http://服务器IP:5173
```

### 6.2 生产模式（推荐）

```bash
cd /opt/funmc/web
npm install
npm run build

# 构建产物在 web/dist/ 目录
# 使用 Nginx 托管静态文件（见下方 Nginx 配置）
```

---

## 7. 防火墙配置

```bash
# 使用 ufw
sudo ufw allow 25565/tcp comment 'FunConnect Relay'
sudo ufw allow 3000/tcp comment 'FunConnect API'
sudo ufw allow 80/tcp comment 'HTTP'
sudo ufw allow 443/tcp comment 'HTTPS'
sudo ufw enable

# 查看规则
sudo ufw status
```

如果使用云服务器（阿里云、腾讯云等），还需要在**安全组**中开放对应端口：

| 端口 | 协议 | 用途 |
|------|------|------|
| 25565 | TCP | Minecraft 中继流量 |
| 3000 | TCP | HTTP API + WebSocket |
| 80 | TCP | Web 面板（HTTP） |
| 443 | TCP | Web 面板（HTTPS） |

---

## 8. Nginx 反向代理（可选）

推荐使用 Nginx 反向代理 API 和托管 Web 管理面板。

### 8.1 安装 Nginx

```bash
sudo apt update
sudo apt install -y nginx
```

### 8.2 配置文件

```bash
sudo tee /etc/nginx/sites-available/funconnect > /dev/null << 'EOF'
server {
    listen 80;
    server_name your-domain.com;  # 替换为你的域名或IP

    # Web 管理面板（静态文件）
    location / {
        root /opt/funmc/web/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # WebSocket 反向代理
    location /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";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
EOF

sudo ln -sf /etc/nginx/sites-available/funconnect /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
```

---

## 9. SSL 证书配置（可选）

使用 Let's Encrypt 免费证书：

```bash
# 安装 certbot
sudo apt install -y certbot python3-certbot-nginx

# 申请证书（替换为你的域名）
sudo certbot --nginx -d your-domain.com

# 自动续期（certbot 会自动添加定时任务）
sudo certbot renew --dry-run
```

---

## 10. 多节点集群配置

### 架构图

```
                    ┌──────────────────┐
                    │   主节点 (Master)  │
                    │   IP: 1.2.3.4    │
                    │   Port: 25565    │
                    │   API: 3000      │
                    └───────┬──────────┘
                            │
              ┌─────────────┼──────────────┐
              ▼             ▼              ▼
    ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
    │  工作节点-华北 │ │  工作节点-华南 │ │  工作节点-华东 │
    │  IP: 2.3.4.5 │ │  IP: 3.4.5.6 │ │  IP: 4.5.6.7 │
    │  Port: 25565 │ │  Port: 25565 │ │  Port: 25565 │
    └──────────────┘ └──────────────┘ └──────────────┘
```

### 工作流程

1. 所有工作节点向主节点发送心跳
2. 主节点汇总所有节点的房间和玩家信息
3. 客户端连接主节点获取房间列表
4. 客户端根据节点信息直接连接对应的工作节点

### 添加新节点步骤

1. 在新服务器上部署工作节点（见第5节）
2. 确保工作节点和主节点网络互通
3. 确保两端使用相同的 `SECRET`
4. 在 Web 管理面板 → 节点管理 → 添加节点
5. 或通过 API 注册（见 5.4）

---

## 11. 运维管理

### 常用命令

```bash
# 服务管理
sudo systemctl start funmc      # 启动
sudo systemctl stop funmc       # 停止
sudo systemctl restart funmc    # 重启
sudo systemctl status funmc     # 状态

# 查看日志
sudo journalctl -u funmc -f              # 实时日志
sudo journalctl -u funmc --since today   # 今日日志
sudo journalctl -u funmc -n 100          # 最近100行

# 更新服务
cd /opt/funmc
sudo systemctl stop funmc
sudo git pull  # 或重新上传文件
sudo npm install --production
sudo npx tsc
sudo systemctl start funmc
```

### 监控

```bash
# API 健康检查
curl -s http://localhost:3000/api/health | python3 -m json.tool

# 服务器统计
curl -s http://localhost:3000/api/stats | python3 -m json.tool

# 流量统计
curl -s http://localhost:3000/api/traffic | python3 -m json.tool

# 房间列表
curl -s http://localhost:3000/api/rooms | python3 -m json.tool

# 节点列表（主节点）
curl -s http://localhost:3000/api/nodes | python3 -m json.tool
```

### 备份

```bash
# 备份配置
sudo cp /opt/funmc/.env /opt/funmc/.env.backup

# 备份日志
sudo cp -r /opt/funmc/logs /opt/funmc/logs.backup
```

---

## 12. 常见问题

### Q: 服务启动失败？

```bash
# 查看详细错误
sudo journalctl -u funmc -n 50 --no-pager

# 常见原因：
# 1. 端口被占用
sudo lsof -i :25565
sudo lsof -i :3000

# 2. Node.js 版本过低
node -v  # 需要 18+

# 3. 依赖未安装
cd /opt/funmc && sudo npm install --production
```

### Q: 玩家无法连接？

1. 检查防火墙是否开放 25565 端口
2. 检查云服务器安全组是否放行
3. 检查服务是否正在运行：`systemctl status funmc`
4. 测试端口连通性：`telnet 服务器IP 25565`

### Q: 工作节点无法注册？

1. 确保主节点和工作节点网络互通
2. 确保 `.env` 中 `MASTER_URL` 正确
3. 确保两端 `SECRET` 一致
4. 检查主节点 API 是否可访问：`curl http://主节点IP:3000/api/health`

### Q: Web 面板打不开？

1. 如果是开发模式，确认访问 `http://IP:5173`
2. 如果是生产模式 + Nginx，确认 Nginx 配置正确
3. 检查 Nginx 状态：`sudo systemctl status nginx`

### Q: 如何修改端口？

编辑 `/opt/funmc/.env`，修改 `RELAY_PORT` 和 `API_PORT`，然后重启：

```bash
sudo systemctl restart funmc
```

---

## 快速部署清单

- [ ] 服务器 Ubuntu 20.04+，已开放 25565 和 3000 端口
- [ ] 安装 Node.js 18+
- [ ] 上传 server/ 目录到服务器
- [ ] 安装依赖：`npm install --production`
- [ ] 编译：`npx tsc`
- [ ] 创建 `.env` 配置文件
- [ ] 创建 systemd 服务
- [ ] 启动服务：`systemctl start funmc`
- [ ] 验证：`curl http://localhost:3000/api/health`
- [ ] （可选）配置 Nginx 反向代理
- [ ] （可选）配置 SSL 证书
- [ ] （可选）部署工作节点扩展集群