FunConnect/docs/DEPLOYMENT.md

# FunMC 部署指南

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

## 目录

- [系统要求](#系统要求)
- [快速部署 (Docker)](#快速部署-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

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

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

### 2. 获取配置文件

```bash
# 克隆仓库
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. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.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. 启动服务

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

# 查看运行状态
docker compose ps

# 查看日志
docker compose logs -f

# 停止服务
docker compose down
```

### 5. 配置 SSL 证书

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

```bash
# 安装 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

```bash
# 更新系统
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

```bash
# 更新系统
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. 配置数据库

```bash
# 切换到 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:

```bash
sudo systemctl restart postgresql
```

### 3. 编译服务

```bash
# 克隆仓库
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. 配置服务

创建配置目录:

```bash
sudo mkdir -p /etc/funmc
```

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

```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`:

```env
# 中继端口
RELAY_PORT=7900

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

# 日志级别
RUST_LOG=funmc_relay_server=info
```

### 5. 运行数据库迁移

```bash
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`:

```ini
[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`:

```ini
[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
```

创建服务用户并启动:

```bash
# 创建用户
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:

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

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

```nginx
# 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;
    }
}
```

启用配置:

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

### 防火墙配置

```bash
# 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
```

---

## 监控与维护

### 日志查看

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

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

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

### 数据库备份

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

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

### 更新服务

```bash
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`:

```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. **启动服务**:

```bash
# 直接运行
./funmc-server

# 或使用 systemd
sudo systemctl start funmc-server
```

### 客户端配置

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

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

```rust
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*