- 一个端口按路径分发:/cnchess /cngo /cs 进程型,/alonelyroad /myword 静态目录 - 进程型首次访问以动态端口拉起子进程,就绪探测后转发;空闲 600s 且无 WS 连接才回收 - WebSocket 走原始 TCP 隧道(握手转发 + 101 透传 + 双向对拷,任一方向 EOF 即拆连) - 文本响应就地重写根绝对路径(href/src/fetch/url(/ 与 location.host}/ws),游戏源码零改动 - 入口页只显示状态与进入入口,不提供管理按钮;网关/运维接口为 /api/* - 配置 games.json 磁盘优先、内嵌兜底,改完刷新即生效
188 lines
9.9 KiB
Markdown
188 lines
9.9 KiB
Markdown
# 游戏中心 · Game Center
|
||
|
||
把 `../` 下的所有游戏收进**一个端口(1818)**,按路径区分:
|
||
|
||
```
|
||
http://localhost:1818/ 入口页(只显示状态,点卡片即进入)
|
||
http://localhost:1818/cnchess/ 中国象棋 ← 进程型,冷启动 / 空闲释放
|
||
http://localhost:1818/cngo/ 围棋 ← 进程型
|
||
http://localhost:1818/cs/ 枪火对决 ← 进程型
|
||
http://localhost:1818/alonelyroad/ 沙漠狂飙 ← 静态目录
|
||
http://localhost:1818/myword/ 我的世界 ← 静态目录
|
||
```
|
||
|
||
没有「常驻服务」的概念:**没人用就释放,有访问再拉起**。中心自己只是一个很小的 Rust
|
||
反代进程(约 1.5MB),内存占用基本就是几个游戏的进程本身。
|
||
|
||
入口页只做两件事:**显示每个游戏的状态**(运行中 / 休眠 / 异常,运行多久、还剩多久回收)、
|
||
**点一下进入**。没有停止、刷新、管理按钮——拉起和释放全按访问行为自动发生,
|
||
运维要手动干预就走下面的 API(curl 即可)。
|
||
|
||
## 跑起来
|
||
|
||
```bash
|
||
bash scripts/build-games.sh # 第一次:把 cnchess / cngo / cs 编成 release 二进制
|
||
bash run.sh # 起中心,前台跑在 1818
|
||
```
|
||
|
||
打开 <http://localhost:1818>,点任意卡片即可。手机 / 平板同一 Wi-Fi 用终端打印的局域网地址。
|
||
|
||
- 首次点击某个进程型游戏,中心现场 spawn 它(约 1 秒内可服务),页面会短暂「启动中」。
|
||
- 关掉页面、10 分钟没人访问 → 进程被回收(默认 600s,`GC_IDLE_SECS` 可改)。
|
||
- 再看一次 → 重新拉起。棋局这类内存态会丢,这是「不用就释放」的必然代价。
|
||
|
||
## 生命周期
|
||
|
||
```
|
||
请求 /cnchess/*
|
||
│
|
||
▼
|
||
┌───────────────┐ 没有进程
|
||
│ ensure() ├──────────────► spawn(bin, PORT=随机空闲端口, HOST=127.0.0.1)
|
||
└───────┬───────┘ │
|
||
│ 已有进程 │ 轮询 TCP connect 直到可连(上限 12s)
|
||
▼ ▼
|
||
转发 / 隧道 ◄──────────────── 就绪(打 starts+1)
|
||
│
|
||
│ last_hit = now,inflight+1
|
||
▼
|
||
响应返回(inflight-1)
|
||
|
||
每 5s 一次 tick:
|
||
进程已退出? → 清状态(下次访问自动重拉)
|
||
inflight > 0 或 ws > 0 → 跳过(正在用 / 对局中,绝不回收)
|
||
now - last_hit ≥ idle → SIGKILL + wait,打 releases+1
|
||
```
|
||
|
||
几个刻意的选择:
|
||
|
||
- **动态端口**。每个进程绑 `127.0.0.1:随机`,不是写死 3000/3100。这样中心重启、旧进程残留、
|
||
同时开多个实例都不会撞端口,也不对外暴露第二个入口。
|
||
- **有 WebSocket 就永不回收**。象棋 / 围棋 / 枪火的对局、等待房间全靠 WS 保活;如果只看
|
||
「最后一次 HTTP 请求」,等人 10 分钟就把棋局杀了。所以回收条件是
|
||
`inflight == 0 && ws_conns == 0 && 空闲够久`。代价是「页面开着但人走了」会一直占着,
|
||
这是对局类游戏的正确取舍。
|
||
- **请求作用域计数**。`Lease` 在进入代理时 `inflight+1`、Drop 时 `-1`,慢请求不会被回收器
|
||
从中间掐断。
|
||
- **中心退出即清场**。Ctrl-C / SIGTERM / SIGHUP 都注册了退出处理,先把所有子进程 release 掉再走,
|
||
不留孤儿。万一被 `kill -9`:`pkill -f 'game/(cnchess|cngo|cs)/target/release'` 收一遍尾巴。
|
||
|
||
## 代理怎么做的
|
||
|
||
**HTTP**:hyper 1 的 client(`hyper::client::conn::http1`)连后端,转发方法/头/体,丢掉
|
||
hop-by-hop 头,`Host` 改写成 `127.0.0.1:<port>`,`Accept-Encoding: identity`(要拿到明文才能重写)。
|
||
响应整体收进内存(都是几十 KB 的页面/JS),按 content-type 决定要不要重写。
|
||
|
||
**WebSocket**:不解析帧,走**原始 TCP 隧道**。把客户端的握手请求按原样(除 Host)写给后端,
|
||
读到后端 101 后,把 101 的头原样回给浏览器,随后 `copy_bidirectional` 双向对拷字节流。
|
||
好处是帧格式、子协议、二进制/文本全都不用管;后端提前吐出的字节(`leftover`)也会先补发给客户端。
|
||
|
||
**路径前缀的补偿**。游戏前端里写死的是根绝对路径,挂到 `/cnchess/` 下会全部打偏,所以在文本
|
||
响应(html/css/js)里就地重写:
|
||
|
||
| 原文 | 重写为 | 出现在 |
|
||
| --- | --- | --- |
|
||
| `href="/` `src="/` `action="/` | `…="/cnchess/…` | 三个 Rust 游戏的 index.html |
|
||
| `fetch("/` | `fetch("/cnchess/…` | cs 取 `/level.json` |
|
||
| `location.host}/` | `location.host}/cnchess/` | 三个游戏的 `${proto}//${location.host}/ws` |
|
||
| `url(/` | `url(/cnchess/…` | CSS 里的绝对资源 |
|
||
|
||
另外 `/cnchess`(少个斜杠)会 301 到 `/cnchess/`,否则页面里的相对路径会解析到根。
|
||
要加新的重写规则,在 `games.json` 里给该游戏写 `rewrites: [["from", "to"]]`,`to` 里可用
|
||
`{prefix}`。
|
||
|
||
## 配置:games.json
|
||
|
||
改完刷新页面即可(中心优先读磁盘上的这份,读不到才用编译进二进制的内嵌版本),**不用重编译**。
|
||
|
||
```jsonc
|
||
{
|
||
"port": 1818,
|
||
"idle_secs": 600,
|
||
"games": [
|
||
{
|
||
"id": "cnchess", // 唯一 id,也是 /api 里的名字
|
||
"name": "中国象棋",
|
||
"tagline": "两台设备联机对弈,服务端权威判棋",
|
||
"icon": "象", // 卡片左上角的字
|
||
"accent": "#e2523f", // 卡片主色
|
||
"stack": "Rust · axum",
|
||
"meta": ["2 人 · 观战", "WebSocket"],
|
||
"kind": "process", // process | static
|
||
"route": "cnchess", // 路由前缀,缺省取 id
|
||
"cwd": "../cnchess", // 相对 center/ 的工作目录
|
||
"bin": "target/release/cnchess"
|
||
},
|
||
{
|
||
"id": "alonelyroad",
|
||
"name": "沙漠狂飙",
|
||
"kind": "static",
|
||
"dir": "../AlonelyRoad", // 静态资源目录
|
||
"entry": "AlonelyRoad.html" // 目录根请求的入口文件(缺省 index.html)
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
环境变量:`GC_PORT`(覆盖端口)、`GC_IDLE_SECS`(覆盖回收时间)、`GC_HOME`(配置与资源根目录)、
|
||
`GC_HOST`(监听地址,默认 `0.0.0.0`)。
|
||
|
||
## API
|
||
|
||
入口页只用 `GET /api/games`,其余几个是给运维手工/脚本用的(页面上没有按钮暴露它们):
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| GET | `/api/games` | 全部游戏快照:state / port / 运行时长 / 剩余回收时间 / WS 数 / 拉起与释放次数 |
|
||
| POST | `/api/games/{id}/wake` | 显式拉起(入口页点卡片时先调它,失败能给出原因) |
|
||
| POST | `/api/games/{id}/stop` | 立即释放(运维用) |
|
||
| POST | `/api/stop-all` | 一键释放全部(运维用) |
|
||
| GET | `/health` | `{"ok":true,"engine":"rust","mode":"lazy-proxy","running":N,...}` |
|
||
|
||
`state` 取值:`running`(进程在跑)、`asleep`(休眠,下次访问拉起)、`static`(静态托管,无进程)、
|
||
`error`(拉起失败,`error` 字段带原因)。
|
||
|
||
## 日志
|
||
|
||
每个进程型的 stdout/stderr 追加到 `run/logs/<id>.log`(已 gitignore)。启动失败时页面会提示路径。
|
||
|
||
## 构建缓存布局(遵循 dev-cache-layout)
|
||
|
||
- `target/`、`run/logs/` 都在项目目录里,**不**挪到 `~/Library/Caches` 再软链回来;
|
||
- 依赖走全局 cargo 缓存实体 `~/.cache/cargo/registry`(`~/.cargo/registry` 是软链),本中心不另建 store;
|
||
- 冷启动提速已经在 `~/.cargo/config.toml` 里配好(USTC 镜像 + sccache + `jobs = 3`),这里不重复配置;
|
||
- 想强制走 sccache:`cargo cold`(= `build --config profile.dev.incremental=false`)。
|
||
|
||
## 加一个游戏
|
||
|
||
1. 进程型:把项目放在 `../<dir>`,能 `cargo build --release` 出单文件、认 `PORT`/`HOST` 环境变量、
|
||
起在根路径 `/`(这三条都满足就直接能用);
|
||
2. 静态型:放一个目录 + 入口 html,用相对路径引资源;
|
||
3. 在 `games.json` 里加一条,刷新启动器。
|
||
|
||
如果新游戏的前端用的是别的根路径写法(比如 `import('/x.js')`、`new URL('/y')`),
|
||
在它的 `rewrites` 里补规则,别去改游戏源码。
|
||
|
||
## 排错
|
||
|
||
| 现象 | 原因 / 处理 |
|
||
| --- | --- |
|
||
| 卡片显示「未构建」 | 跑 `bash scripts/build-games.sh` |
|
||
| 点击后 502,页面说「启动即退出」 | 看 `run/logs/<id>.log`;多半是二进制缺动态库或端口被占 |
|
||
| 页面出来了但白屏 / 资源 404 | 该游戏前端有未被重写的根绝对路径,打开 DevTools 看缺哪个,补 `rewrites` |
|
||
| WS 连不上(状态一直「未连接」) | 浏览器 Network 里看 `/xxx/ws` 是否 101;若不是,看中心 stdout 的 `代理失败` 日志 |
|
||
| 对局 10 分钟后人还在却断了 | 不该发生(有 WS 就不回收);若真发生,检查是不是 WS 已经断开而页面没重连 |
|
||
| 改了游戏前端不生效 | 三个游戏对静态资源都发 `no-cache`,硬刷新即可;若改的是 `public/` 而二进制内嵌了旧版,需重新 build 游戏 |
|
||
|
||
## 已实测(2026-10-22)
|
||
|
||
| 项 | 结果 |
|
||
| --- | --- |
|
||
| 5 条路径 GET | `/` `/cnchess/` `/cngo/` `/cs/` `/alonelyroad/` `/myword/` 全 200,未知路径 404 |
|
||
| 路径重写 | `href/src` 补前缀、 cs 的 `fetch("/level.json")` → `/cs/level.json`、三个游戏的 `${location.host}/ws` → `/<game>/ws` |
|
||
| WebSocket | 象棋 / 围棋 / 枪火 三条 `/ws` 均 101 并完成真实业务消息(建房拿到房号、CS 拿到 welcome + 关卡) |
|
||
| 并发冷启动 | 10 个并发请求打 `/cs/` → `starts=1`、全部 200 |
|
||
| 空闲回收 | 门槛调成 6s:拉起到 `running`,空闲后变 `asleep` 且 `releases=1`,再访问 `starts=2` |
|
||
| WS 保活 | 持连 15s(远超 idle)始终 `running`;断开后 ~5s 内回收 |
|
||
| 拉起失败 | 指向不存在的二进制 → 502 页面写明缺失路径 + 构建命令,`state=error` |
|