144 lines
4.6 KiB
Markdown
144 lines
4.6 KiB
Markdown
# 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_ADMIN_STATIC_DIR` | `cmd/gateway/admin_static` | Admin 前端静态文件目录；Docker 镜像中为 `/usr/share/mc-gateway/admin_static` |
|
||
| `MC_GATEWAY_DB` | `mc-gateway.sqlite3` | SQLite 数据库路径 |
|
||
| `MC_GATEWAY_ADMIN_PASSWORD` | 空 | 首次启动时创建默认管理员密码 |
|
||
|
||
服务启停、KCP/QUIC/WebSocket 参数、用户、权限和路由都通过后台管理写入 SQLite，不再使用 `config.toml` 作为启动配置或路由来源。
|
||
|
||
### Docker Compose
|
||
|
||
生产部署只需要 `compose.yaml`，可以直接用 Docker Compose 拉取已发布镜像并启动：
|
||
|
||
```sh
|
||
docker compose up -d
|
||
```
|
||
|
||
源码目录中包含 `compose.override.yaml`，Docker Compose 会自动加载它，因此本地构建测试仍然可以直接运行：
|
||
|
||
```sh
|
||
docker compose build
|
||
```
|
||
|
||
默认使用 host network，在宿主机 `25565/tcp` 提供 Minecraft TCP 转发入口和后台管理入口，后台地址为：
|
||
|
||
```text
|
||
http://<host>:25565/admin/
|
||
```
|
||
|
||
Compose 使用本地 `./data` 目录持久化 SQLite 数据库和 WAL 文件，不挂载旧 `config.toml`。首次启动可以在后台页面初始化管理员，也可以通过 `.env` 预置默认管理员 `admin` 的密码：
|
||
|
||
```env
|
||
MC_GATEWAY_ADMIN_PASSWORD=change-me
|
||
```
|
||
|
||
常用可选项：
|
||
|
||
```env
|
||
MC_GATEWAY_TCP_ADMIN_PORT=25565
|
||
MC_GATEWAY_ADMIN_PATH=/admin/
|
||
MC_GATEWAY_ADMIN_API_PREFIX=/admin/api
|
||
MC_GATEWAY_ADMIN_STATIC_DIR=/usr/share/mc-gateway/admin_static
|
||
MC_GATEWAY_DB=/data/mc-gateway.sqlite3
|
||
```
|
||
|
||
### Admin 前端开发
|
||
|
||
Admin 前端源码位于 `cmd/gateway/admin_frontend/src`，使用 TypeScript 拆分为原生 ES modules。构建产物输出到 `cmd/gateway/admin_static/js`，Go 服务不会 embed 前端文件，而是从 `MC_GATEWAY_ADMIN_STATIC_DIR` 指向的目录透传静态响应。
|
||
|
||
修改前端后运行：
|
||
|
||
```sh
|
||
npm install
|
||
npm run build:admin
|
||
```
|
||
|
||
`master` 分支和 `v*` tag 会通过 GitHub Actions 构建并推送 Docker 镜像到 GitHub Container Registry：
|
||
|
||
```text
|
||
ghcr.io/tursom/mc-gateway:latest
|
||
```
|
||
|
||
## 权限
|
||
|
||
后台管理内置三类角色：
|
||
|
||
| 角色 | 能力 |
|
||
| --- | --- |
|
||
| 管理员 | 管理用户、服务、路由和审计日志 |
|
||
| 成员 | 查看状态，管理路由 |
|
||
| 游客 | 查看当前路由 |
|
||
|
||
## 路由
|
||
|
||
路由记录存储在 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
|
||
}
|
||
```
|