独立依赖

docs/deployment.md

@@ -0,0 +1,146 @@
+# 部署说明
+
+本文说明如何把「3D 数字人语音聊天」服务端部署到一台新机器（Linux / WSL / macOS 等类 Unix 环境）。**唯一需要能访问公网的依赖是 LLM API**；语音相关权重应放在项目内 `models/` 目录，不在运行时从公网拉取。
+
+## 1. 环境与依赖
+
+- **Python**：建议 3.12（与当前 `requirements.txt` 一致）。
+- **系统工具**：`openssl`（生成自签证书）；可选 `ffmpeg`（若你后续扩展音视频流程）。
+- **硬件**：CPU 可运行；有 NVIDIA GPU 时 ASR 等会优先用 CUDA（无卡则回退 CPU，可能较慢）。
+- **磁盘**：`models/` 中 ASR + TTS 权重合计约 **1.2GB+**，请预留空间。
+
+## 2. 获取代码与虚拟环境
+
+```bash
+git clone <你的仓库地址> product
+cd product
+
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+pip install -U pip
+pip install -r requirements.txt
+```
+
+说明：依赖里已包含 `huggingface_hub`（由其它包装带动）。若单独只为下载权重，也可 `pip install huggingface_hub`。
+
+## 3. 准备本地模型（`models/`）
+
+首次在一台**能访问 Hugging Face**的机器上执行（仅需一次，或把整份 `models/` 目录打包拷贝到离线机）：
+
+```bash
+source .venv/bin/activate
+python scripts/vendor_hf_models.py
+```
+
+该脚本会：
+
+- 从已安装的 `silero-vad` 包复制 **`models/vad/silero_vad.jit`**
+- 拉取 **ASR**：`models/asr/SenseVoiceSmall/`
+- 拉取 **TTS（Kokoro）**：`models/tts/Kokoro-82M/`（含 `voices/` 下各 `.pt` 音色）
+
+若目标机无外网，可在有网机器上跑完上述命令后，**整体复制 `models/`** 到部署机同一路径（相对于项目根）。
+
+仅补全 VAD、不拉 HF（需已 `pip install silero-vad`）：
+
+```bash
+python scripts/vendor_hf_models.py --skip-hf
+```
+
+## 4. 配置环境变量（`.env`）
+
+```bash
+cp .env.example .env
+```
+
+**必须非空**（见 `config.py` 校验）：
+
+| 变量 | 含义 |
+|------|------|
+| `LLM_API_KEY` | OpenAI 兼容接口的 API Key |
+| `LLM_BASE_URL` | 例如 `https://api.deepseek.com/v1` |
+| `LLM_MODEL` | 例如 `deepseek-chat` |
+
+**HTTP 服务**（不要使用已废弃的 `WEBRTC_*`）：
+
+| 变量 | 含义 |
+|------|------|
+| `HTTP_HOST` | 监听地址，一般 `0.0.0.0` |
+| `HTTP_PORT` | 端口，例如 `8080` 或 `8018` |
+
+**HTTPS（推荐用于跨设备访问页面与麦克风）**：
+
+- 证书路径建议写**相对项目根**，便于迁移，例如：
+  - `SSL_CERTFILE=certs/dev-cert.pem`
+  - `SSL_KEYFILE=certs/dev-key.pem`
+- 程序会把相对路径解析为项目根下的绝对路径。
+
+**TTS 音色**：`TTS_VOICE` 必须与 `models/tts/Kokoro-82M/voices/<名称>.pt` 一致（默认示例为 `zf_xiaoxiao`）。
+
+完整字段说明见仓库根目录 [`.env.example`](../.env.example)。
+
+## 5. 生成自签证书（可选但常需要）
+
+在**项目根目录**执行：
+
+```bash
+bash scripts/gen-self-signed-cert.sh
+```
+
+生成 `certs/dev-cert.pem` 与 `certs/dev-key.pem`，并在 `.env` 中配置上一节的 `SSL_CERTFILE`、`SSL_KEYFILE`。
+
+默认证书主题为 `CN=localhost`。用局域网 IP 访问时浏览器可能提示证书与地址不符，属自签名常见情况，可在浏览器中选择继续访问；生产环境请改用正规 CA 或内网 PKI 签发的证书。
+
+## 6. 启动服务
+
+**开发 / 前台运行：**
+
+```bash
+source .venv/bin/activate
+python main.py
+```
+
+或使用脚本（会读 `.env` 中的 `HTTP_HOST`、`HTTP_PORT`）：
+
+```bash
+bash scripts/start-public.sh
+```
+
+**HTTPS**：当 `.env` 中 `SSL_CERTFILE`、`SSL_KEYFILE` 均有效且文件存在时，`main.py` 会通过 uvicorn 加载证书（与 `config` 中解析后的路径一致）。
+
+启动后在本机浏览器访问：
+
+- `http(s)://127.0.0.1:<HTTP_PORT>/`
+- `http(s)://<服务器局域网IP>:<HTTP_PORT>/`（需防火墙放行该端口）
+
+## 7. 防火墙与端口
+
+确保部署机对客户端开放 **`HTTP_PORT`（TCP）**。若前面有云厂商安全组，需同步放行。
+
+## 8. 目录与可移植性约定
+
+- **项目根**：所有相对路径（SSL、`models/` 布局、`web/` 静态资源）均以**含有 `main.py` 与 `config.py` 的目录**为基准；启动时工作目录应为此目录。
+- **可选**：环境变量 `VISUAL_CHAT_PYTHON` 可指向指定 Python 解释器（部分 `scripts/*.sh` 会优先使用）。
+
+## 9. 验证
+
+```bash
+curl -s "http://127.0.0.1:${HTTP_PORT:-8080}/health" | head
+```
+
+或用仓库内脚本（需根据实际 URL 调整）：
+
+```bash
+python scripts/qa_check.py --base-url "https://127.0.0.1:8080" --rounds 3
+```
+
+（若仅 HTTP，把 `base-url` 改成 `http://...`。）
+
+## 10. 常见问题
+
+- **`.env` 里 `LLM_*` 为空**：应用在加载 `config` 时会校验失败，请务必填写有效值。
+- **ASR/TTS 不工作**：检查 `models/asr/SenseVoiceSmall/` 是否含 `configuration.json`；`models/tts/Kokoro-82M/` 是否含 `config.json`、权重 `.pth` 与 `voices/<TTS_VOICE>.pt`。
+- **麦克风在别的设备上不可用**：多数浏览器要求 **HTTPS** 与用户手势；请启用 HTTPS 并在页面内点击「连接语音通道」等操作。
+- **旧变量名**：`WEBRTC_HOST`、`WEBRTC_PORT`、`STUN_URL` 已废弃，请只使用 `HTTP_HOST`、`HTTP_PORT`。
+
+更细的语音/文本流水线时序见 [development-guide.md](development-guide.md)。