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

9.9 KiB
Raw Blame History

游戏中心 · 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 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

改完刷新页面即可(中心优先读磁盘上的这份,读不到才用编译进二进制的内嵌版本),不用重编译。

{
  "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