calx/DEPLOY.md

🚀 部署指南（迁移到新电脑）

本项目 = 一个前端单页 index.html + 一个零依赖 Node 后端 server.js + 本地离线识别模型。 没有构建、没有 npm install、没有云服务。下面按「最快路径」走。

---

一分钟看懂：需要带什么、装什么

类别	内容	说明
拷贝的文件	整个 calx/ 目录	见下方清单。models/（模型）建议一起拷，省下载
要装的软件	Node.js、ffmpeg、whisper-cpp	前者官网/brew，后两者 brew install
不用带	node_modules（没有）	真·零依赖

必须一起迁移的文件清单：

index.html  server.js  bootstrap.sh  start.sh  grammar/
models/ggml-small.bin   (465MB，必需)
models/ggml-base.bin    (141MB，可选，更快)
README.md  DEPLOY.md  CLAUDE.md

---

方式 A：一键部署（推荐，macOS）

前提：新电脑已装 Node.js 和 Homebrew。

cd calx
bash bootstrap.sh

脚本会自动：检查 Node → 装 ffmpeg/whisper-cpp → 补下模型（若缺）→ 启动服务。 可反复运行，已装的会跳过。

---

方式 B：手动部署（逐步）

# 1. 装依赖
brew install ffmpeg whisper-cpp        # Node 另装：brew install node

# 2. 补模型（若没随目录拷贝）
mkdir -p models && cd models
curl -L -o ggml-small.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin
cd ..

# 3. 启动
node server.js

---

怎么访问

💻 本机运行

Chrome / Edge / Safari 打开 http://localhost:8000 —— 麦克风直接可用（localhost 是浏览器认可的安全上下文），点「开始」授权即可。

🌐 对外部署（其它设备访问）

浏览器只在安全上下文（HTTPS 或 localhost）里放行麦克风。把服务挂在支持 HTTPS 的反向代理（nginx / Caddy / 云平台均可）后面，其余零改动：

浏览器 ──HTTPS──> 反向代理 ──HTTP──> node server.js (:8000)

---

配置与运维

# 换更快的模型（识别快一点、准一点点降低）
WHISPER_MODEL=models/ggml-base.bin node server.js

# 改端口
PORT=8000 node server.js

前端玩法参数（读题开关 / 限时秒数 / 口诀范围 / 随机题数 / 错题加权 / 抢答参数 / 静音检测灵敏度）在 index.html 顶部 CONFIG，或游戏首页「⚙️ 家长设置」里改常用项。

---

排障速查

现象	原因 / 处理
点「开始」不弹麦克风授权	不是安全上下文：本机用 http://localhost:8000；对外部署走 HTTPS 反向代理
识别没反应 / 不准	看服务端日志有无 [stt] … -> "xxx"；/health 里 modelExists 应为 true；环境别太吵、吐字清楚
whisper-cli: command not found	brew install whisper-cpp
ffmpeg: command not found	brew install ffmpeg
完全不想用语音	游戏内点「⌨️ 用手写」，或环境不支持时自动切数字键盘

验证部署是否成功

curl -s http://localhost:8000/health           # {"ok":true,...,"modelExists":true}

modelExists:true = 部署成功。