FunConnect/server/DEPLOY.md

FunConnect 服务端部署教程

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

---

目录

1. 环境要求
2. 方式一：一键部署
3. 方式二：手动部署
4. 部署主节点
5. 部署工作节点
6. 部署 Web 管理面板
7. 防火墙配置
8. Nginx 反向代理（可选）
9. SSL 证书配置（可选）
10. 多节点集群配置
11. 运维管理
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/ 目录上传到服务器：

# 在本地执行（将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 执行安装脚本

# 部署主节点
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 验证安装

# 查看服务状态
systemctl status funmc

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

---

3. 方式二：手动部署

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

3.1 安装 Node.js

# 方法一：使用 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 创建项目目录

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

3.3 上传并安装

# 将 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 创建配置文件

sudo cp .env.example .env
sudo nano .env

---

4. 部署主节点

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

4.1 配置文件

编辑 /opt/funmc/.env：

# ===== 网络配置 =====
# 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 服务

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 启动服务

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

# 查看状态
sudo systemctl status funmc

4.4 验证主节点

# 健康检查
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：

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 启动并注册

# 启动工作节点
sudo systemctl start funmc

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

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

5.4 手动注册工作节点

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

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 开发模式

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

6.2 生产模式（推荐）

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

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

---

7. 防火墙配置

# 使用 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

sudo apt update
sudo apt install -y nginx

8.2 配置文件

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 免费证书：

# 安装 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. 运维管理

常用命令

# 服务管理
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

监控

# 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

备份

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

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

---

12. 常见问题

Q: 服务启动失败？

# 查看详细错误
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，然后重启：

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 证书
• （可选）部署工作节点扩展集群