- 规则引擎:提子、禁自杀、全局同形(超级劫)、中国规则数子(白贴 7.5 目)、停一手终局 - 服务端:axum + tokio,房间/观战/包干计时/断线重连/语音中继,前端资源内嵌单文件 - 前端:Canvas 木纹棋盘(9/13/19 路、星位、四边坐标、翻转视角)、WebAudio 合成落子声、 本机双人模式、终局数子面板 - 测试:16 组规则断言 + 5 组 e2e(提子/劫/数子/观战/语音/静态资源) - 构建缓存遵循 dev-cache-layout:target/ 留项目内并忽略,前端零构建不产生包缓存
9.8 KiB
围棋 · 在线对战
两个人用各自的电脑 / 平板打开网页就能下围棋。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(最简单)
- 你在电脑上打开
http://localhost:3100,选好棋盘大小(9 / 13 / 19 路)和每方时间,点「创建房间」,屏幕上会出现 4 位房号。 - 终端启动服务时会顺便打印局域网地址,比如
http://192.168.1.8:3100。 - 对方在平板 / 另一台电脑上打开这个地址,输入房号,点「加入」。
- 黑先白后,白方看到的棋盘会自动旋转 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 / 打包缓存,不需要给这个项目单独配包缓存。



