# 游戏中心 · 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 bash scripts/build-games.sh # 第一次:把 cnchess / cngo / cs / wordduel / numberplace 编成 release 二进制 bash run.sh # 起中心,前台跑在 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:`,`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 改完刷新页面即可(中心优先读磁盘上的这份,读不到才用编译进二进制的内嵌版本),**不用重编译**。 ```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/.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. 进程型:把项目放在 `../`,能 `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/.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` → `//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` |