Files
center/README.md
T
rong dd2935366e feat: 游戏中心——1818 单端口统一入口,进程按需拉起 + 空闲释放
- 一个端口按路径分发:/cnchess /cngo /cs 进程型,/alonelyroad /myword 静态目录
- 进程型首次访问以动态端口拉起子进程,就绪探测后转发;空闲 600s 且无 WS 连接才回收
- WebSocket 走原始 TCP 隧道(握手转发 + 101 透传 + 双向对拷,任一方向 EOF 即拆连)
- 文本响应就地重写根绝对路径(href/src/fetch/url(/ 与 location.host}/ws),游戏源码零改动
- 入口页只显示状态与进入入口,不提供管理按钮;网关/运维接口为 /api/*
- 配置 games.json 磁盘优先、内嵌兜底,改完刷新即生效
2026-10-23 10:09:06 +08:00

188 lines
9.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 游戏中心 · 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` |