Chinese Chess Online

一个基于 Node.js、Express、Socket.IO、Electron 和原生 Canvas 的中国象棋在线对战项目。支持 Windows 桌面版、本地单人模式、联机房间、观战、悔棋、求和、每步计时，以及可选的本地 Ollama/Qwen AI 对战。

功能特性

• 9x10 中国象棋棋盘，Canvas 绘制棋盘、棋子、合法落点和最后一步高亮
• 完整基础走法：帅/将、仕/士、相/象、马、车、炮、兵/卒
• 高级规则：将军检测、将死、困毙、禁止送将、将帅照面
• Socket.IO 在线房间：创建房间、加入房间、实时同步走棋
• 观战模式：大厅可进入正在对局的房间观战
• 对局操作：悔棋请求、认输、求和、每步计时
• 单人模式：内置 Minimax + Alpha-Beta AI，支持多档难度
• Ollama AI：可连接本机 Ollama 模型进行 AI 对战
• Windows 桌面版：Electron 自动启动本地服务，支持 setup 安装包、便携版 exe 和 ngrok 公网联机链接
• 基础安全：连接 token、浏览器指纹、连接/事件限流、观战人数限制

技术栈

• 后端：Node.js、Express、Socket.IO
• 前端：HTML、CSS、原生 JavaScript、Canvas
• 桌面端：Electron、electron-builder
• AI：内置搜索 AI，可选 Ollama 本地模型
• 开发工具：nodemon

快速开始

Windows 桌面版

普通用户可以直接下载 GitHub Release 中的安装包：

• Chinese Chess Online Setup 1.0.2.exe：推荐，带安装向导、桌面快捷方式和开始菜单入口
• Chinese Chess Online 1.0.2.exe：便携版，下载后双击即用

桌面版会自动启动一个本机服务并打开棋盘窗口，不需要手动运行 npm start。

桌面版公网联机

桌面版大厅里有“联机分享”区域。第一次使用时：

1. 登录 ngrok 控制台复制你的 authtoken，或从 ngrok config add-authtoken ... 命令中复制授权码部分。
2. 在软件的“粘贴 ngrok authtoken”输入框中保存配置。
3. 点击“生成联机链接”。
4. 你创建房间后，把生成的链接和房间号一起发给朋友；朋友打开同一个链接，输入房间号加入。

ngrok authtoken 只保存在当前电脑的 Electron 用户配置目录，不会写入 GitHub 仓库或 Release 说明。

环境要求

• Node.js 18 或更高版本
• npm

安装依赖

npm install

启动服务

npm start

然后打开：

http://localhost:3000

开发模式

npm run dev

语法检查

npm test

构建 Windows 安装包

npm run dist

构建产物会输出到 dist/，包括 NSIS setup 安装包和便携版 exe。 如果要构建带公网分享能力的桌面包，请确保项目根目录存在 ngrok.exe；该二进制文件不会提交到 Git。

联机对战

1. 玩家 A 输入昵称并点击“创建房间”。
2. 玩家 B 输入房间号并点击“加入房间”。
3. 红方先行，双方走棋会通过 Socket.IO 实时同步。
4. 大厅中的“对战中”房间可点击进入观战。

Ollama AI 对战

如果要使用 Ollama AI，请先在本机安装并运行 Ollama，然后拉起对应模型：

ollama run qwen3.5:9b

应用会在 AI 弹窗中自动检测本机模型。默认 Ollama 地址为：

http://localhost:11434

服务端会通过 /api/ollama/tags 和 /api/ollama/chat 代理到本机 Ollama，避免浏览器跨域问题。如果 Ollama 不可用，前端会明确提示，并在 AI 走棋失败时回退为随机合法走法。

可选公网分享

仓库中不建议提交 ngrok.exe、cloudflared.exe 这类本地二进制工具，.gitignore 已经排除它们。需要公网分享时可以自行下载隧道工具，或直接部署到支持 WebSocket 的平台。

start.js 默认尝试使用本地 ngrok.exe 暴露 localhost:3000。如果你不需要公网分享，直接使用 npm start 即可。

项目结构

.
├── public/
│   ├── css/
│   │   └── style.css
│   ├── js/
│   │   ├── app.js
│   │   ├── board.js
│   │   ├── bot.js
│   │   ├── game.js
│   │   ├── network.js
│   │   ├── ollama-bot.js
│   │   └── pieces.js
│   └── index.html
├── desktop/
│   └── main.js
├── scripts/
│   ├── create-icon.js
│   └── smoke-server.js
├── assets/
│   └── icon.ico
├── server.js
├── start.js
├── start.bat
├── package.json
└── WORKFLOW.md

核心模块

• server.js：Express 静态服务、Socket.IO 房间/对局/观战/悔棋/计时事件
• desktop/main.js：Electron 桌面入口，自动启动本地服务并打开窗口
• public/js/game.js：中国象棋规则引擎，服务端和前端共用
• public/js/board.js：棋盘渲染、坐标转换、选子与落子交互
• public/js/app.js：页面状态、UI 事件、单机/联机流程
• public/js/network.js：客户端 Socket.IO 通信封装
• public/js/bot.js：内置 Minimax AI
• public/js/ollama-bot.js：Ollama AI 请求与走法解析

部署说明

生产部署时请确保：

• 平台支持 WebSocket
• 使用环境变量 PORT 指定端口，默认端口为 3000
• 使用环境变量 OLLAMA_BASE_URL 指定 Ollama 地址，默认 http://localhost:11434
• 反向代理需要支持 Upgrade / Connection 头
• 不要提交 .env、隧道工具 exe、node_modules

贡献

欢迎提交 issue 和 pull request。请先阅读 CONTRIBUTING.md。

安全

如果发现安全问题，请阅读 SECURITY.md 中的报告方式。

许可证

本项目基于 MIT License 开源。