YANG JIANKUAN
5f7f68150e
麦克风安全上下文改由部署方案解决：本机用 localhost， 对外部署挂 HTTPS 反向代理。删除 certs/、gen-cert.sh、 /cert 路由与 HTTPS server 分支，文档同步更新。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# 🚀 部署指南（迁移到新电脑）
|
||
|
||
本项目 = 一个前端单页 `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](https://nodejs.org) 和 [Homebrew](https://brew.sh)。
|
||
|
||
```bash
|
||
cd calx
|
||
bash bootstrap.sh
|
||
```
|
||
|
||
脚本会自动：检查 Node → 装 `ffmpeg`/`whisper-cpp` → 补下模型（若缺）→ 启动服务。
|
||
可反复运行，已装的会跳过。
|
||
|
||
---
|
||
|
||
## 方式 B：手动部署（逐步）
|
||
|
||
```bash
|
||
# 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)
|
||
```
|
||
|
||
---
|
||
|
||
## 配置与运维
|
||
|
||
```bash
|
||
# 换更快的模型（识别快一点、准一点点降低）
|
||
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` |
|
||
| 完全不想用语音 | 游戏内点「⌨️ 用手写」，或环境不支持时自动切数字键盘 |
|
||
|
||
## 验证部署是否成功
|
||
|
||
```bash
|
||
curl -s http://localhost:8000/health # {"ok":true,...,"modelExists":true}
|
||
```
|
||
`modelExists:true` = 部署成功。
|