e73c8e536e
Client: - 支持 Windows (NSIS安装包+免安装版), macOS (DMG x64/arm64), Linux (AppImage+deb) - 添加 dist:win / dist:mac / dist:linux / dist:all 打包脚本 - 生成应用图标 (icon.png + icon.ico) - Windows x64 安装包已编译: release/FunConnect-1.1.0-Win-x64.exe - 更新 README 包含完整的跨平台构建指南和国内镜像加速说明 Server: - 新增 DEPLOY.md 详细部署教程 (400+行) - Ubuntu主节点完整部署流程 - 工作节点部署和注册 - Web管理面板生产部署 - 防火墙配置 - Nginx反向代理配置 - SSL证书(Let's Encrypt)配置 - 多节点集群架构说明 - 运维管理命令和监控 - 常见问题排查 - 快速部署清单
592 lines
13 KiB
Markdown
592 lines
13 KiB
Markdown
# 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 证书
|
||
- [ ] （可选）部署工作节点扩展集群
|