# 部署说明

本文说明如何把「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)。