# Minecraft 基岩版 UDP 转发配置文档

## 架构

```
公网玩家 (UDP 19132)
    ↓
北京VPS (salmonstill.cn)
socat 监听 19132 → 转发到 10.0.0.2:19132
    ↓ WireGuard 隧道
旁路由 ImmortalWrt (192.168.1.199 / 10.0.0.2)
nftables 端口转发 + SNAT
    ↓
NAS (192.168.1.188:19132)
    ↓
Minecraft 基岩版 Docker 容器
```

---

## 设备信息

| 设备 | IP | 系统 |
|---|---|---|
| 北京VPS | `salmonstill.cn` / `49.232.242.90` | Ubuntu 22.04 |
| 旁路由 | `192.168.1.199` / WG隧道: `10.0.0.2` | ImmortalWrt 24.10 (GL-MT2500) |
| NAS | `192.168.1.188` | 绿联云 UGOS |

---

## 第一部分：北京VPS 配置

### WireGuard 配置 `/etc/wireguard/wg0.conf`

```ini
[Interface]
Address = 10.0.0.1/24
ListenPort = 51820
PrivateKey = <北京VPS私钥>
MTU = 1420

# 回包源地址转换（必须，否则公网玩家收不到回包）
PostUp = iptables -t nat -A POSTROUTING -s 10.0.0.0/24 -o eth0 -j MASQUERADE
PostDown = iptables -t nat -D POSTROUTING -s 10.0.0.0/24 -o eth0 -j MASQUERADE

[Peer]
# 旁路由
PublicKey = 9jPlaUhx2Dc+C5ZqJx6Iu8GtNMig3cFIoqfHg8PZbCA=
AllowedIPs = 10.0.0.2/32
PersistentKeepalive = 25
```

> ⚠️ 不使用 iptables DNAT 转发，改用 socat 处理 UDP 转发，避免 conntrack 连接跟踪问题导致回包丢失。

### 开启内核转发

```bash
echo "net.ipv4.ip_forward=1" >> /etc/sysctl.conf
sysctl -p
```

### 开放防火墙端口

```bash
ufw allow 51820/udp   # WireGuard
ufw allow 19132/udp   # Minecraft 基岩版
```

### 启动 WireGuard

```bash
systemctl enable wg-quick@wg0
systemctl start wg-quick@wg0
```

### socat UDP 转发

socat 监听公网 19132 端口，收到包后转发给旁路由隧道 IP，并维护连接状态确保回包正确返回。

创建 systemd service：

```bash
nano /etc/systemd/system/mc-forward.service
```

```ini
[Unit]
Description=Minecraft UDP Forward
After=network.target

[Service]
ExecStart=/usr/bin/socat UDP4-LISTEN:19132,fork,reuseaddr UDP4:10.0.0.2:19132
Restart=always

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

启动并设置开机自启：

```bash
systemctl daemon-reload
systemctl enable mc-forward
systemctl start mc-forward
```

---

## 第二部分：旁路由 ImmortalWrt 配置

### WireGuard 接口配置

路径：**网络 → 接口 → 添加新接口**

**常规设置：**

| 字段 | 值 |
|---|---|
| 接口名称 | `WireGuard` |
| 协议 | `WireGuard VPN` |
| 私钥 | `<旁路由私钥>` |
| IP 地址 | `10.0.0.2/24` |
| 监听端口 | 不填 |

**防火墙设置：** 加入 `wan` 区域

**Peers → 添加对端：**

| 字段 | 值 |
|---|---|
| 公钥 | `n159R7bNB+tW3Br0cok2zA27Pzg2WSPTI9uQ9odOFyU=` |
| 端点主机 | `salmonstill.cn` |
| 端点端口 | `51820` |
| 允许的 IP | `0.0.0.0/0` |
| 路由允许的 IP | ✅ 勾选 |
| 持续 Keep-Alive | `25` |

> ⚠️ 允许的 IP 必须设为 `0.0.0.0/0`，否则 WireGuard 会丢弃来自公网玩家 IP 的包。

### 端口转发配置

路径：**网络 → 防火墙 → 端口转发 → 添加**

| 字段 | 值 |
|---|---|
| 名称 | `Minecraft-udp` |
| 协议 | `UDP` |
| 源区域 | `wan` |
| 外部端口 | `19132` |
| 目标区域 | `lan` |
| 内部 IP 地址 | `192.168.1.188` |
| 内部端口 | `19132` |

### SNAT 配置

路径：**网络 → 防火墙 → NAT 规则 → 添加**

| 字段 | 值 |
|---|---|
| 名称 | `minecraft-snat` |
| 地址族限制 | `仅 IPv4` |
| 协议 | `UDP` |
| 出站区域 | `lan` |
| 目标地址 | `192.168.1.188` |
| 目标端口 | `19132` |
| 操作 | `SNAT - 重写为特定的源 IP 或端口` |
| 重写 IP 地址 | `192.168.1.199` |

> SNAT 的作用：将转发给 NAS 的包源 IP 改为旁路由 IP，确保 NAS 的回包发回给旁路由而不是直接走主路由，避免回包路径不对称。

---

## 第三部分：NAS Docker 配置

使用 `network_mode: host` 避免 Docker NAT 导致的 IP 映射问题。

```yaml
services:
  bedrock:
    image: itzg/minecraft-bedrock-server:2026.2.1
    container_name: mc-bedrock
    network_mode: host
    stdin_open: true
    tty: true
    environment:
      EULA: "TRUE"
      VERSION: "1.26.14.1"
      TZ: "Asia/Shanghai"
      OPS: "2535472561115036"
    volumes:
      - /volume2/ProgramsV2/minecraft:/data
    restart: unless-stopped
```

---

## 第四部分：验证

### 检查 WireGuard 隧道

```bash
# 旁路由
wg show
# 正常应有 latest handshake 和双向 transfer
```

### 检查 socat 运行状态

```bash
systemctl status mc-forward
```

### 抓包验证完整链路

```bash
# VPS 上抓 wg0，确认双向流量
tcpdump -i wg0 udp port 19132 -n

# 旁路由抓 br-lan，确认转发到 NAS
tcpdump -i br-lan udp port 19132 -n

# NAS 上抓包，确认收到并回包
sudo tcpdump -i bridge0 udp port 19132 -n
```

---

## 故障排查

| 现象 | 排查方法 |
|---|---|
| WireGuard 无握手 | 检查 VPS 防火墙 51820/udp 是否开放 |
| socat 收不到包 | 检查 ufw 19132/udp 是否开放 |
| 旁路由收不到包 | 检查 WireGuard AllowedIPs 是否为 `0.0.0.0/0` |
| NAS 收不到包 | 检查端口转发内部端口是否填写正确 |
| NAS 有回包但玩家连不上 | 检查 SNAT 规则是否生效，确认 NAS 用 host 网络模式 |
| 游戏内延迟不显示 | 检查 socat 是否正常运行，DNAT 规则是否已删除 |

---

## 扩展：新增其他 UDP 服务

1. VPS 新建一个 socat service，修改端口号
2. 旁路由 LuCI 端口转发新增一条规则
3. `ufw allow <新端口>/udp`