FunConnect/docs/DEPLOYMENT.md

FunMC 部署指南

本文档详细介绍如何部署 FunMC 服务端和客户端。

目录

• 系统要求
• 快速部署 (Docker)
• 手动部署
• 生产环境配置
• 监控与维护
• 局域网部署

---

系统要求

服务器

组件	最低要求	推荐配置
CPU	1 核	2 核+
内存	512 MB	1 GB+
存储	1 GB	10 GB+
系统	Ubuntu 20.04 / Debian 11 / CentOS 8	Ubuntu 22.04 LTS
网络	1 Mbps	10 Mbps+

开放端口

端口	协议	用途
80	TCP	HTTP (重定向到 HTTPS)
443	TCP	HTTPS (API + WebSocket)
7900	UDP	QUIC 中继服务 (主线路)
7901	UDP	QUIC 中继服务 (备用)

---

快速部署 (Docker)

1. 安装 Docker

# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# 安装 Docker Compose
sudo apt install docker-compose-plugin

2. 获取配置文件

# 克隆仓库
git clone https://github.com/mofangfang/funmc.git
cd funmc

# 或者只下载 Docker 配置
mkdir funmc && cd funmc
curl -O https://raw.githubusercontent.com/mofangfang/funmc/main/docker/docker-compose.yml
curl -O https://raw.githubusercontent.com/mofangfang/funmc/main/.env.example

3. 配置环境变量

cp .env.example .env

编辑 .env 文件:

# 数据库配置
POSTGRES_USER=funmc
POSTGRES_PASSWORD=your_secure_password_here
POSTGRES_DB=funmc

# JWT 密钥 (至少 32 字符)
JWT_SECRET=change-this-to-a-very-long-random-string-at-least-32-chars

# 服务器地址
SERVER_DOMAIN=funmc.example.com

# 中继服务器配置
RELAY_PORT=7900
RELAY_BACKUP_PORT=7901

4. 启动服务

# 启动所有服务
docker compose up -d

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f

# 停止服务
docker compose down

5. 配置 SSL 证书

推荐使用 Certbot 获取免费 SSL 证书:

# 安装 Certbot
sudo apt install certbot

# 获取证书
sudo certbot certonly --standalone -d funmc.example.com

# 证书位置
# /etc/letsencrypt/live/funmc.example.com/fullchain.pem
# /etc/letsencrypt/live/funmc.example.com/privkey.pem

---

手动部署

1. 安装依赖

Ubuntu/Debian

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装基础工具
sudo apt install -y build-essential pkg-config libssl-dev curl git

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 安装 PostgreSQL
sudo apt install -y postgresql postgresql-contrib

# 启动 PostgreSQL
sudo systemctl enable postgresql
sudo systemctl start postgresql

CentOS/RHEL

# 更新系统
sudo dnf update -y

# 安装基础工具
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y openssl-devel curl git

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 安装 PostgreSQL
sudo dnf install -y postgresql-server postgresql-contrib
sudo postgresql-setup --initdb
sudo systemctl enable postgresql
sudo systemctl start postgresql

2. 配置数据库

# 切换到 postgres 用户
sudo -u postgres psql

# 在 psql 中执行:
CREATE DATABASE funmc;
CREATE USER funmc WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE funmc TO funmc;
\q

编辑 /etc/postgresql/14/main/pg_hba.conf (版本号可能不同):

# 添加以下行允许本地密码认证
local   funmc           funmc                           md5
host    funmc           funmc           127.0.0.1/32    md5

重启 PostgreSQL:

sudo systemctl restart postgresql

3. 编译服务

# 克隆仓库
git clone https://github.com/mofangfang/funmc.git
cd funmc

# 编译主服务器
cargo build --release -p funmc-server

# 编译中继服务器
cargo build --release -p funmc-relay-server

# 复制二进制文件
sudo mkdir -p /opt/funmc/bin
sudo cp target/release/funmc-server /opt/funmc/bin/
sudo cp target/release/funmc-relay-server /opt/funmc/bin/

4. 配置服务

创建配置目录:

sudo mkdir -p /etc/funmc

创建主服务器配置 /etc/funmc/server.env:

# 数据库连接
DATABASE_URL=postgres://funmc:your_password@localhost/funmc

# JWT 密钥
JWT_SECRET=your-super-secret-jwt-key-at-least-32-characters

# 服务绑定地址
BIND_ADDR=127.0.0.1:3000

# 内置 QUIC 中继端口
QUIC_PORT=3001

# 日志级别
RUST_LOG=funmc_server=info,tower_http=info

创建中继服务器配置 /etc/funmc/relay.env:

# 中继端口
RELAY_PORT=7900

# JWT 密钥 (必须与主服务器一致)
JWT_SECRET=your-super-secret-jwt-key-at-least-32-characters

# 日志级别
RUST_LOG=funmc_relay_server=info

5. 运行数据库迁移

cd /path/to/funmc/server

# 安装 sqlx-cli
cargo install sqlx-cli --no-default-features --features postgres

# 运行迁移
DATABASE_URL=postgres://funmc:your_password@localhost/funmc sqlx migrate run

6. 创建 Systemd 服务

主服务器 /etc/systemd/system/funmc-server.service:

[Unit]
Description=FunMC API Server
After=network.target postgresql.service

[Service]
Type=simple
User=funmc
Group=funmc
WorkingDirectory=/opt/funmc
EnvironmentFile=/etc/funmc/server.env
ExecStart=/opt/funmc/bin/funmc-server
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

中继服务器 /etc/systemd/system/funmc-relay.service:

[Unit]
Description=FunMC Relay Server
After=network.target

[Service]
Type=simple
User=funmc
Group=funmc
WorkingDirectory=/opt/funmc
EnvironmentFile=/etc/funmc/relay.env
ExecStart=/opt/funmc/bin/funmc-relay-server
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

创建服务用户并启动:

# 创建用户
sudo useradd -r -s /bin/false funmc

# 设置权限
sudo chown -R funmc:funmc /opt/funmc

# 重载 systemd
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

---

生产环境配置

Nginx 反向代理

安装 Nginx:

sudo apt install -y nginx

创建配置 /etc/nginx/sites-available/funmc:

# HTTP 重定向到 HTTPS
server {
    listen 80;
    server_name funmc.example.com;
    return 301 https://$server_name$request_uri;
}

# HTTPS 配置
server {
    listen 443 ssl http2;
    server_name funmc.example.com;

    # SSL 证书
    ssl_certificate /etc/letsencrypt/live/funmc.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/funmc.example.com/privkey.pem;

    # SSL 安全配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    # 日志
    access_log /var/log/nginx/funmc_access.log;
    error_log /var/log/nginx/funmc_error.log;

    # API 代理
    location / {
        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;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket 代理
    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";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 86400;
    }
}

启用配置:

sudo ln -s /etc/nginx/sites-available/funmc /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

防火墙配置

# UFW (Ubuntu)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 7900/udp
sudo ufw allow 7901/udp
sudo ufw enable

# firewalld (CentOS)
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --add-port=7900/udp
sudo firewall-cmd --permanent --add-port=7901/udp
sudo firewall-cmd --reload

---

监控与维护

日志查看

# 主服务器日志
sudo journalctl -u funmc-server -f

# 中继服务器日志
sudo journalctl -u funmc-relay -f

# Nginx 访问日志
sudo tail -f /var/log/nginx/funmc_access.log

数据库备份

# 备份
pg_dump -U funmc -d funmc > backup_$(date +%Y%m%d).sql

# 恢复
psql -U funmc -d funmc < backup_20240101.sql

更新服务

cd /path/to/funmc
git pull

# 重新编译
cargo build --release -p funmc-server -p funmc-relay-server

# 更新二进制
sudo systemctl stop funmc-server funmc-relay
sudo cp target/release/funmc-server /opt/funmc/bin/
sudo cp target/release/funmc-relay-server /opt/funmc/bin/
sudo systemctl start funmc-server funmc-relay

---

局域网部署

如果只需要在局域网内使用 FunMC，可以使用简化配置。

局域网服务器配置

1. 安装依赖（同上）

2. 简化配置 /etc/funmc/server.env:

DATABASE_URL=postgres://funmc:password@localhost/funmc
JWT_SECRET=local-development-secret-key-32chars
BIND_ADDR=0.0.0.0:3000
QUIC_PORT=3001
RUST_LOG=info

3. 启动服务:

# 直接运行
./funmc-server

# 或使用 systemd
sudo systemctl start funmc-server

客户端配置

编辑客户端配置文件，将服务器地址改为局域网 IP:

文件位置: client/src/config.rs

pub const DEFAULT_SERVER_URL: &str = "http://192.168.1.100:3000";
pub const DEFAULT_RELAY_URL: &str = "192.168.1.100:7900";

或者在客户端设置页面修改服务器地址。

局域网联机测试

1. 启动 Minecraft 服务器

   • 在一台电脑上启动 Minecraft 服务器
   • 或在单人世界中开启局域网联机

2. 主机操作

   • 打开 FunMC 客户端
   • 登录账号（首次需要注册）
   • 创建房间
   • 点击"开始托管"

3. 玩家操作

   • 打开 FunMC 客户端
   • 登录账号
   • 在大厅找到房间并加入
   • 点击"连接"
   • 复制显示的地址（如 127.0.0.1:25566）
   • 在 Minecraft 中添加服务器并连接

4. 验证连接

   • 检查 FunMC 显示的连接类型
   • 局域网内通常会显示"P2P 直连"
   • 如果是"中继"，检查防火墙设置

---

常见问题

数据库连接失败

Error: connection refused

解决方案:

1. 检查 PostgreSQL 服务是否运行: sudo systemctl status postgresql
2. 检查 pg_hba.conf 配置
3. 确认用户名密码正确

QUIC 端口无法连接

Error: connection timed out

解决方案:

1. 检查防火墙是否开放 UDP 端口
2. 确认端口没有被其他程序占用: sudo netstat -ulnp | grep 7900

WebSocket 连接断开

解决方案:

1. 检查 Nginx 配置中的 proxy_read_timeout
2. 确认客户端心跳正常发送

---

支持

如有问题，请通过以下方式获取帮助:

• GitHub Issues: https://github.com/mofangfang/funmc/issues
• 官方文档: https://docs.funmc.com
• 邮箱: support@funmc.com

---

魔幻方开发 © 2024