Files
rong cb28bbb49e feat: 围棋在线对战(Rust 服务端 + 零构建前端)
- 规则引擎:提子、禁自杀、全局同形(超级劫)、中国规则数子(白贴 7.5 目)、停一手终局
- 服务端:axum + tokio,房间/观战/包干计时/断线重连/语音中继,前端资源内嵌单文件
- 前端:Canvas 木纹棋盘(9/13/19 路、星位、四边坐标、翻转视角)、WebAudio 合成落子声、
  本机双人模式、终局数子面板
- 测试:16 组规则断言 + 5 组 e2e(提子/劫/数子/观战/语音/静态资源)
- 构建缓存遵循 dev-cache-layout:target/ 留项目内并忽略,前端零构建不产生包缓存
2026-10-23 10:12:55 +08:00

9.8 KiB
Raw Permalink Blame History

围棋 · 在线对战

两个人用各自的电脑 / 平板打开网页就能下围棋。Rust 后端 + 纯静态 HTML 前端,服务端权威校验落子(提子、禁自杀、打劫、数子全在服务端算),不装 App、不注册账号、前端零构建。

浏览器 A ──┐                 ┌── 规则引擎(提子 / 禁自杀 / 全局同形 / 数子 / 计时)
           ├── WebSocket ────┤
浏览器 B ──┘                 └── 房间状态(棋盘 + 棋盘时钟 + 观战者 + 语音)
     └── 观战者

Rust(axum + tokio)         public/ 里的 html/css/js 由同一个进程托管

桌面版对局

建房 数子终局 手机竖屏

跑起来

需要 Rust 工具链(cargo 1.75+)。

cargo run --release          # 或 cargo run 走 debug,编译更快

然后打开 http://localhost:3100(默认端口 3100,避开象棋项目的 3000;要改就 PORT=3200 cargo run)。

首次编译约 2~4 分钟(拉依赖 + 编 axum/tokio),之后增量编译几秒。

两个人怎么玩

同一个 Wi-Fi(最简单)

  1. 你在电脑上打开 http://localhost:3100,选好棋盘大小(9 / 13 / 19 路)和每方时间,点「创建房间」,屏幕上会出现 4 位房号。
  2. 终端启动服务时会顺便打印局域网地址,比如 http://192.168.1.8:3100。
  3. 对方在平板 / 另一台电脑上打开这个地址,输入房号,点「加入」。
  4. 黑先白后,白方看到的棋盘会自动旋转 180°,1 路始终在自己这边。

看别人下棋

输入房号点「只看」,就进入观战;两个座位都有人时,点「加入」也会自动变成观战。观战者能看到实时棋局、手数和双方剩余时间,但动不了棋盘。

不在同一个 Wi-Fi

把编译出的单文件二进制丢到有公网 IP 的服务器上(见下一节),PORT=3100 ./cngo。用 Nginx/Caddy 反代时记得放行 WebSocket 的 Upgrade 头:

location / {
    proxy_pass http://127.0.0.1:3100;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

编译成单文件程序

cargo build --release

产物:target/release/cngo(自带 HTTP/WS 服务 + 内嵌前端资源,不依赖任何运行时)。

build.rs 会把 public/ 整个目录编译进二进制,所以拷到没装任何东西的电脑 / NAS / 树莓派上直接跑; /health 里能看到 "engine":"rust"、"game":"go"、"mode":"embedded"。

  • 默认只编「当前系统 + 当前架构」。要给 Linux x86_64 用,就在 Linux 上 cargo build --release, 或用 cargo zigbuild / 交叉工具链。
  • 前端资源已内嵌,但程序同目录若存在 public/,会优先用磁盘上的版本,方便临时改页面。

改前端不用编译

public/ 里的 index.html、style.css、js/**/*.js 就是最终产物,浏览器直接加载 ES module:

public/
  index.html            页面骨架
  style.css             样式(深色 + 木色棋盘)
  js/shared/rules.js    规则引擎的浏览器副本(本地双人模式、落点校验)
  js/client/board.js    Canvas 棋盘绘制:木板木纹、星位、坐标、棋子高光、落点预览
  js/client/main.js     界面状态、联机逻辑、计时、断线重连、终局数子展示、语音界面
  js/client/sound.js    WebAudio 现场合成的落子声(噪声脉冲,无音频文件)
  js/client/voice.js    按住说话的录音(MediaRecorder)、base64 编解码、播放

改完存盘刷新即可(服务端对静态资源发 Cache-Control: no-cache)。 注意 js/shared/rules.js 是 src/rules.rs 的 JS 镜像:改规则要两边一起改, 服务端才是权威,前端那份只负责「点下去之前先告诉你能不能下」。

代码结构

src/rules.rs      规则引擎:气与棋块、提子、禁自杀、全局同形(超级劫)、数子、坐标记法
src/protocol.rs   WebSocket 消息类型(serde 序列化,与 public/js 里的 JSON 契约一致)
src/server.rs     房间管理 + 权威校验 + 棋盘时钟 + 观战席 + 静态文件服务
src/main.rs       启动、端口/绑定地址、局域网地址打印
build.rs          把 public/ 压成资源表编进二进制
tests/e2e.rs      双客户端联机流程(含提子、观战、停一手数子、认输、再来一局、静态资源、语音)

测试

cargo test
  • rules::tests —— 15 组规则断言(提单子/整块、禁自杀、提子优先于自杀、角上提子、超级劫、 数子与贴目、坐标记法跳过 I、编码往返、气数计算)
  • tests/e2e.rs —— 5 组联机断言(建房→加入→落子→抢手被拒→重复落点被拒→观战禁下→停两手数子→再来一局; 角上提子与认输;未知房号;/health 与静态资源;语音收发/历史取回/观战禁发/超长拒绝)

单跑某一组:cargo test superko / cargo test --test e2e。

规则口径

按**中国规则(数子 / 面积计算)**实现,够两个人下棋用,不做裁判级抠细节:

事情 怎么判
提子 落子后对方某块棋气为 0,整块提掉,被提的子计入本方「提子数」
禁着点 落子后自己这块没气、又提不到对方子 → 不合法(自杀禁止)
打劫 全局同形禁止(超级劫):任何让局面与之前完全相同的着法都不合法,提示「先到别处应一手」
停一手 右侧「停一手」或按 P;双方各停一手即终局
终局 数子:本方活子数 + 只被本方围住的空点;白贴 7.5 目(3 又 3/4 子)
超时 时间归零判负;有一方掉线时计时自动暂停,不算他输
重开 双方都点「再来一局」才重开(对手已离开时直接重开)
认输 右侧「认输」
掉线 重新打开邀请链接,会回到原来坐的那一边

数子的简化:双活(seki)里的空点按「双方都能进」记为中性,不给任何一方; 死子不会自动识别为死子 —— 所以终局前请自己把死子提干净,或者干脆下到没有争议再双方停手。 真要精确判定死活,得接一个死活判定引擎,见「还没做的」。

玩法细节

做的事情 怎么操作
落子 点交叉点就落;鼠标悬停会先显示一颗半透明的子,点偏了也算最近的交叉点
提子 目标点周围对方棋块没气时自动提,落子声会变成连响,右侧「提 N」会加
停一手 右侧「停一手」或键盘 P
计时 建房时选 10 / 20 / 40 分钟或不限时;每方各自扣时,落子或停手后换对方
手数 棋谱按手数两列排,带 提N 标记;坐标用围棋习惯记法(跳过字母 I)
上一手 棋盘上用红点标出最后一手的位置
观战 右侧显示观战人数;观战者不能落子、不能发语音

语音互动

棋盘右侧面板下方就是语音区,不用切换页面:

  • 按住「按住说话」(鼠标 / 手指都行)开始录,松手自动发;最长 30 秒,到点自动停并发出。
  • 对方收到立刻播放,同时进「互动记录」列表;发的人自己不回放。
  • 点列表里任意一条就放那条,再点一次停。列表带发送方(黑/白)、时长和时刻。
  • 观战者能听、能点历史,但不能发(按钮会提示「观战中只能听」);本地双人模式没有语音。

实现上:浏览器 MediaRecorder 录成 webm/opus(Safari 落到 audio/mp4),base64 后走同一条 WebSocket。 服务端把每条语音的元信息放进房间状态,音频本体只在发的那一刻广播一次、点历史时用 voiceGet 单独取。 房间内保留最近 40 条、总量约 12MB(base64 后),超出丢最旧的;每局「再来一局」会清空语音记录。

跨内核播放:Chrome/Firefox 录的是 webm/opus,Safari 播不了 webm,Safari 录的 mp4 反过来 Chrome 能播。 所以跨平台对局可能遇到「对方发的听不见」——需要服务端转码才能彻底解决,目前没做。

还没做的

  • 死活判定与死子自动标记(现在的数子只做「子 + 空」的静态统计)
  • 让子局 / 贴目自定义(现在固定 7.5 目,黑先)
  • 悔棋、棋谱回放、SGF 导入导出
  • 读秒(现在只有一次性包干时间)
  • 语音转码(webm ↔ mp4)与语音落盘:目前只在内存里,重启即清
  • 棋局持久化:服务端所有棋局都在内存里,重启就清空(空房 10 分钟回收,有人的房 4 小时)
  • 多进程 / 多机部署(房间在进程内存里,要横向扩得先接 Redis 之类的外置状态)

依赖下载 / 编译加速(本机已配,遵循 dev-cache-layout)

  • 依赖走 USTC sparse 镜像,包缓存实体集中在 ~/.cache/cargo/registry(~/.cargo/registry 是软链指向它)。
  • 编译包了一层 sccache(rustc-wrapper,实体 ~/.cache/sccache),冷启动 / 清 target 重建能省三分之一时间。
  • jobs = 3:本机 2 核 4 线程 8G 内存的安全上限,别调 4。
  • 配置都在 ~/.cargo/config.toml,仓库里不需要再放 .cargo/config.toml。
  • target/ 留在项目目录(增量编译 + 复查用),已在 .gitignore;不要挪到 ~/Library/Caches 再软链回来 —— 软链不被 .gitignore 的目录型规则匹配,git status 会冒 ??,而且缓存脱离项目生命周期。
  • 前端零构建(原生 ES module),没有 npm / node_modules / 打包缓存,不需要给这个项目单独配包缓存。