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

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

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

类别	内容	说明
拷贝的文件	整个 `calx/` 目录	见下方清单。`models/`（模型）建议一起拷，省下载
要装的软件	Node.js、`ffmpeg`、`whisper-cpp`	前者官网/brew，后两者 `brew install`
不用带	`node_modules`（没有）、`certs/`（新机自动生成）	证书含本机 IP，换机必须重新生成

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

index.html  server.js  bootstrap.sh  start.sh  gen-cert.sh
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 → 补下模型（若缺）→ 生成自签证书 → 启动服务。可反复运行，已装的会跳过。

启动后终端打印：

HTTP : http://localhost:8000   http://<本机IP>:8000
HTTPS: https://<本机IP>:8443

方式 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. 生成证书 + 启动
bash gen-cert.sh
node server.js

各端怎么访问

💻 电脑本机

Chrome / Edge / Safari 打开 http://localhost:8000 —— 麦克风直接可用，点「开始」授权即可。

📱 iPhone / iPad（要用语音 → 必须 HTTPS + 信任证书，一次性）

iOS 只有在「HTTPS + 受信任证书」下才允许网页用麦克风，这是苹果硬限制。用 Safari 完成：

手机与电脑连同一 Wi-Fi（或你的远程方案能到 8443 端口）。
Safari 打开 https://<电脑IP>:8443/cert → 下载描述文件（提示不受信任，继续）。
设置 → 通用 → VPN 与设备管理 → 安装 calx-local。
设置 → 通用 → 关于本机 → 证书信任设置 → 打开对 calx-local 的完全信任。
Safari 打开 https://<电脑IP>:8443/ → 点「开始」→ 允许麦克风 → 全程免手。

🤖 安卓 / 其它

Chrome 打开 https://<电脑IP>:8443/，首次会警告证书不受信 → 「高级 → 继续前往」→ 允许麦克风。

配置与运维

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

# 改端口
PORT=8000 HTTPS_PORT=8443 node server.js

# 电脑 IP 变了（换网络） → 证书失效，重新生成，手机重做信任步骤
bash gen-cert.sh

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

排障速查

现象	原因 / 处理
点「开始」不弹麦克风授权	不是 HTTPS，或 iOS 证书没「完全信任」→ 重做 iOS 第 2~4 步
iOS 证书装了仍拦麦克风	证书 SAN 的 IP 与访问 IP 不一致 → `bash gen-cert.sh` 后重装证书
识别没反应 / 不准	看服务端日志有无 `[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}
curl -sk https://localhost:8443/health         # 同上（自签名用 -k）

modelExists:true + 两个端口都返回 = 部署成功。

4.2 KiB Raw Blame History Unescape Escape