mc-gateway/README.md

# mc-gateway

一个简易的 Minecraft 网关，通过客户端握手里的 host 将流量转发到对应的后端 Minecraft 服务器。

## 启动

mc-gateway 默认不依赖配置文件。直接启动后会在 `25565` 端口同时提供 Minecraft TCP 转发入口和后台管理入口：

- Admin 页面：`/admin/`
- Admin API：`/admin/api`
- SQLite 数据库：`mc-gateway.sqlite3`

首次启动时，如果用户表为空，可以通过 Admin 页面初始化管理员账号。也可以用 `MC_GATEWAY_ADMIN_PASSWORD` 在启动时创建默认管理员用户 `admin`。

### 启动期环境变量

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `MC_GATEWAY_TCP_ADMIN_PORT` | `25565` | TCP/Admin 共享监听端口 |
| `MC_GATEWAY_ADMIN_PATH` | `/admin/` | Admin 页面路径 |
| `MC_GATEWAY_ADMIN_API_PREFIX` | `/admin/api` | Admin API 前缀 |
| `MC_GATEWAY_DB` | `mc-gateway.sqlite3` | SQLite 数据库路径 |
| `MC_GATEWAY_ADMIN_PASSWORD` | 空 | 首次启动时创建默认管理员密码 |

服务启停、KCP/QUIC/WebSocket 参数、用户、权限和路由都通过后台管理写入 SQLite，不再使用 `config.toml` 作为启动配置或路由来源。

## 权限

后台管理内置三类角色：

| 角色 | 能力 |
| --- | --- |
| 管理员 | 管理用户、服务、路由和审计日志 |
| 成员 | 查看状态，管理路由 |
| 游客 | 查看当前路由 |

## 路由

路由记录存储在 SQLite 中，后台修改后会刷新内存快照。默认 fallback 路由的 host 为 `default`。

### upstream

路由上游支持多种协议。TCP 上游直接填写地址，其他协议在地址前加协议前缀：

| 协议 | 前缀 | 说明 |
| --- | --- | --- |
| tcp | 无 | 原始 TCP 连接 |
| kcp | `kcp://` | 使用 KCP 协议连接到服务器 |
| quic | `quic://` | 使用 QUIC 协议连接到服务器 |
| haproxy | `haproxy://` | 使用 HAProxy 协议连接到服务器 |

HAProxy 协议头会保存客户端真实 IP，适合需要在后端服务端获取真实客户端 IP 的场景。

## 可选服务

TCP/Admin listener 是基础入口，默认启用。KCP、QUIC、WebSocket 默认禁用，可以在后台管理中启用并配置端口和参数；配置修改后第一版按重启后生效处理。

| 服务 | 默认端口 | 说明 |
| --- | --- | --- |
| TCP/Admin | `25565` | Minecraft TCP 转发和后台管理共享入口 |
| KCP | `25565` | 可选 KCP 入口 |
| QUIC | `25565` | 可选 QUIC 入口 |
| WebSocket | `25566` | 可选 WebSocket 入口 |

## 日志

默认日志级别为 `info`，输出到标准输出。日志文件重开逻辑支持 logrotate 场景：

```logrotate
/var/log/mc-gateway.log {
    copytruncate
    daily
    missingok
    rotate 14
    compress
    compresscmd /usr/bin/zstd
    compressext .zst
    compressoptions -T0 --long
    uncompresscmd /usr/bin/unzstd
    notifempty
    delaycompress
    dateext
    postrotate
        if [ -f /dev/shm/mc-gateway.pid ]; then
            kill -SIGHUP $(cat /dev/shm/mc-gateway.pid)
        fi
    endscript
}
```