- games.json 新增两条进程型配置:wordduel(../en,/wordduel/)与 numberplace(/numberplace/),启动器自动多出两张卡片 - build-games.sh 改为「二进制名:目录名」映射循环,wordduel 住在 ../en - 重写规则全部走代理层,未改游戏源码: - numberplace 的 api(`/api/…`) 反引号/单引号两种写法补 rewrites - wordduel 邀请链接 location.origin + '/#' + c 补前缀 - WS 地址与 index.html 的 href/src 走内置规则 - README 同步路由表、重写规则表、kill -9 兜底命令; 并更正 games.json 需重启中心才生效(config 启动时一次性加载)
游戏中心 · Game Center
把 ../ 下的所有游戏收进一个端口(1818),按路径区分:
http://localhost:1818/ 入口页(只显示状态,点卡片即进入)
http://localhost:1818/cnchess/ 中国象棋 ← 进程型,冷启动 / 空闲释放
http://localhost:1818/cngo/ 围棋 ← 进程型
http://localhost:1818/cs/ 枪火对决 ← 进程型
http://localhost:1818/wordduel/ 单词对战 ← 进程型(源码在 ../en)
http://localhost:1818/numberplace/ 数独 ← 进程型
http://localhost:1818/alonelyroad/ 沙漠狂飙 ← 静态目录
http://localhost:1818/myword/ 我的世界 ← 静态目录
没有「常驻服务」的概念:没人用就释放,有访问再拉起。中心自己只是一个很小的 Rust 反代进程(约 1.5MB),内存占用基本就是几个游戏的进程本身。
入口页只做两件事:显示每个游戏的状态(运行中 / 休眠 / 异常,运行多久、还剩多久回收)、 点一下进入。没有停止、刷新、管理按钮——拉起和释放全按访问行为自动发生, 运维要手动干预就走下面的 API(curl 即可)。
跑起来
bash scripts/build-games.sh # 第一次:把 cnchess / cngo / cs / wordduel / numberplace 编成 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|en|numberplace)/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 里的绝对资源 |
api(\/api/ api('/api/` |
api(\/numberplace/api/…` |
数独(反引号 / 单引号两种写法都要补) |
location.origin + '/#' + c |
location.origin + '/wordduel/#' + c |
单词对战的邀请链接({prefix} 自带斜杠,to 里别再写) |
另外 /cnchess(少个斜杠)会 301 到 /cnchess/,否则页面里的相对路径会解析到根。
要加新的重写规则,在 games.json 里给该游戏写 rewrites: [["from", "to"]],to 里可用
{prefix}。
配置:games.json
改完刷新页面即可(中心优先读磁盘上的这份,读不到才用编译进二进制的内嵌版本),不用重编译。
{
"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)。
加一个游戏
- 进程型:把项目放在
../<dir>,能cargo build --release出单文件、认PORT/HOST环境变量、 起在根路径/(这三条都满足就直接能用); - 静态型:放一个目录 + 入口 html,用相对路径引资源;
- 在
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 |