Trading_Studio/DEPLOY.md

# Trading Studio 部署指南 (DEPLOY.md)

本文档面向 **Ubuntu 物理服务器**（搭载 RTX 3060 Ti，已锁定 120W 功耗墙）的完整环境配置与 PM2 常驻部署流程。适用于首次安装或迁移重装场景。

**标准安装路径：** `/opt/Trading_Studio`（root 用户）  
**Git 仓库：** https://git.bz121.com/dekun/Trading_Studio.git

---

## 目录

0. [**一键部署（推荐）**](#0-一键部署推荐) — 含 [模型预下载](#08-ai-模型预下载内网服务器必做)、[服务器更新](#042-代码推送后的服务器更新推荐)、[手机麦克风](#09-手机找不到麦克风)
1. [硬件与系统前提](#1-硬件与系统前提)
2. [3060 Ti 120W 功耗墙配置](#2-3060-ti-120w-功耗墙配置)
3. [NVIDIA 驱动与 CUDA](#3-nvidia-驱动与-cuda)
4. [Python 虚拟环境](#4-python-虚拟环境)
5. [PyTorch CUDA 12.1 安装](#5-pytorch-cuda-121-安装)
6. [项目依赖安装](#6-项目依赖安装)
7. [远程 Ollama 节点配置](#7-远程-ollama-节点配置)
8. [首次运行与验证](#8-首次运行与验证)
9. [PM2 进程守护](#9-pm2-进程守护)
10. [迁移与故障排查](#10-迁移与故障排查)

---

## 0. 一键部署（推荐）

项目内置 `deploy.sh`，以 **root** 用户将 Trading Studio 部署到 `/opt/Trading_Studio`，并自动完成依赖安装、虚拟环境、PyTorch CUDA、PM2 常驻与开机自启。

### 0.1 前提条件

在运行脚本前，请确保服务器已满足：

| 项目 | 说明 |
|------|------|
| 系统 | Ubuntu 22.04 / 24.04 LTS |
| 用户 | **root**（`sudo -i` 切换） |
| GPU 驱动 | `nvidia-smi` 可正常输出 |
| 网络 | 可访问 `git.bz121.com` 拉取代码 |
| Ollama | 局域网 `192.168.8.64:11434` 可达（润色功能） |

> **Git 认证：** 若 `git clone` 需要登录，请先在 root 下配置 HTTPS 凭据或 SSH 密钥，再执行部署脚本。

> **服务器本地配置（Ollama IP 等）：** 不要直接改 `config.py`，请使用 `.env` 文件：
> ```bash
> cp .env.example .env
> nano .env   # 修改 OLLAMA_HOST=你的局域网IP
> pm2 restart trading_studio
> ```

> **git pull 报本地修改冲突？** 多半是 Windows CRLF 换行符幽灵改动（内容其实没变）。执行：
> ```bash
> bash server-update.sh
> ```
> 或手动：
> ```bash
> git fetch origin && git reset --hard origin/main
> pm2 restart trading_studio
> ```
> 切勿 `git stash pop`，Ollama 地址请写在 `.env` 里。

### 0.2 首次一键部署

```bash
# 切换 root
sudo -i

# 方式 A：从 Git 克隆后执行（推荐）
git clone https://git.bz121.com/dekun/Trading_Studio.git /opt/Trading_Studio
cd /opt/Trading_Studio
chmod +x deploy.sh
bash deploy.sh

# 方式 B：若已有本地代码目录，直接在该目录执行
cd /opt/Trading_Studio
chmod +x deploy.sh
bash deploy.sh
```

> **若报错 `$'\r': command not found`：** 说明脚本含 Windows 换行符，先执行 `sed -i 's/\r$//' deploy.sh` 再重试，或 `git pull` 拉取已修复版本。

脚本自动执行以下步骤：

1. 安装系统依赖（python3、ffmpeg、libsndfile 等）
2. 安装 Node.js 20 + PM2
3. 克隆/更新代码到 `/opt/Trading_Studio`
4. 创建 `venv/` 并安装 PyTorch cu121 + requirements.txt
5. 创建 `logs/`、`uploads/`、`outputs/` 目录
6. 设置 GPU 120W 功耗墙（若 nvidia-smi 可用）
7. 放行防火墙端口 5683（若 ufw 已启用）
8. `pm2 start ecosystem.config.js` 并配置开机自启

部署成功后访问：

```
http://<服务器局域网IP>:5683
```

> **重要：首次部署后必须预下载 AI 模型**（Whisper + ChatTTS）。内网服务器无法访问 HuggingFace / GitHub 时，不执行此步会在 Web UI 报 `Network is unreachable` 或 `Read timed out`。详见 [0.8 AI 模型预下载](#08-ai-模型预下载内网服务器必做)。

### 0.3 脚本命令速查

```bash
cd /opt/Trading_Studio

bash deploy.sh              # 首次完整部署 + PM2 启动
bash deploy.sh update       # git pull + 更新依赖 + PM2 重启
bash deploy.sh restart      # 仅重启 PM2
bash deploy.sh stop         # 停止 PM2
bash deploy.sh status       # 查看 PM2 / GPU / 端口状态
bash deploy.sh logs         # 查看 PM2 最近 80 行日志
bash deploy.sh help         # 显示帮助
```

### 0.4 日常更新流程

代码推送到 Git 后，在服务器上执行：

```bash
sudo -i
cd /opt/Trading_Studio
bash deploy.sh update
```

> **git pull 报本地修改冲突？** 新版 `deploy.sh` 会自动 `stash` 后同步；若仍失败可手动：
> `git fetch origin && git reset --hard origin/main`

### 0.4.2 代码推送后的服务器更新（推荐）

本地开发机 `git push` 到远端后，在 **Ubuntu 服务器**上同步并重启：

```bash
cd /opt/Trading_Studio
bash server-update.sh
```

`server-update.sh` 会执行：

1. `git fetch origin main`
2. `git reset --hard origin/main`（覆盖 CRLF 等幽灵改动；**Ollama 地址请写在 `.env`，勿改 `config.py`**）
3. `pm2 restart trading_studio`

若本次更新涉及 **Whisper / ChatTTS 离线加载**（首次部署或新增模型脚本），还需预下载模型：

```bash
cd /opt/Trading_Studio
bash server-update.sh
bash scripts/download_all_models.sh
pm2 restart trading_studio
```

| 脚本 | 作用 |
|------|------|
| `bash server-update.sh` | 强制与远端 `main` 同步 + PM2 重启 |
| `bash scripts/download_all_models.sh` | 一次性下载 Whisper (small) + ChatTTS |
| `bash scripts/download_whisper_models.sh small` | 仅下载 Whisper |
| `bash scripts/download_chattts_models.sh` | 仅下载 ChatTTS |

验证 Whisper 是否就绪：

```bash
ls -lh /opt/Trading_Studio/models/whisper/small/model.bin
```

应看到约 **500MB** 的 `model.bin` 文件。

### 0.4.1 pip / PyTorch 下载超时

PyTorch + triton 约 2-3GB，国内网络默认启用清华镜像，并延长超时到 600 秒：

```bash
# 默认已开启国内镜像，若仍慢可加大超时
USE_CN_MIRROR=1 PIP_TIMEOUT=900 bash deploy.sh deps

# 仅补装依赖（不拉代码、不启 PM2）
bash deploy.sh deps

# PyTorch 已手动装好时跳过
SKIP_PYTORCH=1 bash deploy.sh deps
```

下载过程中出现 `Retrying... Read timed out` 属于正常重试，**并非卡死**，请耐心等待 10-30 分钟。

### 0.7 PWA 安装 App（需 HTTPS）

| 访问方式 | 浏览器行为 |
|----------|------------|
| `http://内网IP:5683` | 只能「快捷方式 / 添加到主屏幕」 |
| `https://域名`（经云服务器反代） | Chrome/Edge 可 **「安装 Trading Studio」** |

内网 HTTP 直连无法一键安装 App，这是浏览器 PWA 安全策略，不是程序缺陷。

**反向代理不在本仓库代码中配置。** 若你使用 **云服务器 + NPS 内网穿透**（或其它反代方案），请阅读独立教程：

👉 **[PWA_NPS.md](./PWA_NPS.md)** — 云服务器 HTTPS 反代 + NPS 穿透到 `5683` 的完整步骤

要点摘要：

1. 内网物理机 PM2 监听 `5683` 即可  
2. NPS 将 `127.0.0.1:5683` 穿透到云服务器  
3. 云服务器用已有 Nginx/面板配置 **HTTPS 域名** 反代到 NPS 端口  
4. 反代须透传 **WebSocket**（Gradio 必需）  
5. 用户通过 `https://你的域名` 访问后再安装 App  

### 0.8 AI 模型预下载（内网服务器必做）

Trading Studio 的 **Whisper 语音识别** 与 **ChatTTS 音色合成** 均需在服务器本地存放模型文件。  
内网物理机通常无法访问 `huggingface.co` / `github.com`，若未预下载，Web UI 会出现：

| 模块 | 典型报错 |
|------|----------|
| Whisper | `Network is unreachable` / `ConnectError` |
| ChatTTS | `Read timed out` / `github.com` 连接失败 |

**推荐：一键下载全部模型**

```bash
cd /opt/Trading_Studio
bash scripts/download_all_models.sh
pm2 restart trading_studio
```

**分步下载（可选）**

```bash
# Whisper small（约 500MB，识别默认模型）
bash scripts/download_whisper_models.sh small

# ChatTTS（约 1–2GB，音色锁定与合成必需）
bash scripts/download_chattts_models.sh

pm2 restart trading_studio
```

**模型落盘路径**

| 模型 | 目录 | 关键文件 |
|------|------|----------|
| Whisper `small` | `/opt/Trading_Studio/models/whisper/small/` | `model.bin` |
| ChatTTS | `/opt/Trading_Studio/models/ChatTTS/` | `asset/` 等 |
| HF 缓存 | `/opt/Trading_Studio/models/hf_cache/` | 下载中间缓存 |

**`.env` 可选配置**（复制 `.env.example` → `.env`）：

```ini
HF_ENDPOINT=https://hf-mirror.com
WHISPER_MODEL_DIR=/opt/Trading_Studio/models/whisper
WHISPER_MODEL_SIZE=small
CHATTTS_MODEL_DIR=/opt/Trading_Studio/models/ChatTTS
```

国内服务器建议保留 `HF_ENDPOINT=https://hf-mirror.com`（脚本与 `whisper_service.py` 均会读取）。

### 0.9 手机「找不到麦克风」

通过 `http://192.168.x.x:5683` 内网 HTTP 访问时，手机浏览器会显示 **「找不到麦克风」** 或 **「检测不到麦克风」**。  
这是浏览器安全策略：`getUserMedia`（麦克风）**仅在 HTTPS 或 localhost 下可用**，不是程序 bug。

| 访问方式 | 电脑录音 | 手机录音 |
|----------|----------|----------|
| `http://内网IP:5683` | 可能可用 | ❌ 不可用 |
| `https://域名`（NPS + 云反代） | ✅ | ✅ |

**解决办法（任选其一）：**

1. 按 [PWA_NPS.md](./PWA_NPS.md) 配置 **NPS 穿透 + 云服务器 HTTPS 域名**，用手机访问 `https://你的域名`
2. 在 HTTP 内网环境下，使用音频区域的 **「上传」** 标签，上传手机「语音备忘录」导出的 `.m4a` / `.wav`（与现场录音效果相同）

Whisper 离线模型就绪后，**上传音频文件** 可正常识别；麦克风实时录音需 HTTPS。

---

### 0.5 PM2 运维（root 环境）

```bash
pm2 status                          # 进程状态
pm2 logs trading_studio             # 实时日志
pm2 restart trading_studio          # 手动重启
pm2 monit                           # 资源监控

# 应用日志
tail -f /opt/Trading_Studio/trading_studio.log
tail -f /opt/Trading_Studio/logs/pm2-out.log
```

### 0.6 目录布局（/opt 标准路径）

```
/opt/Trading_Studio/
├── deploy.sh              # 一键部署脚本
├── server-update.sh       # 强制同步远端 + PM2 重启
├── app.py                 # Gradio 主入口
├── venv/                  # Python 虚拟环境
├── scripts/
│   ├── download_all_models.sh      # Whisper + ChatTTS 一键下载
│   ├── download_whisper_models.sh  # Whisper 预下载（HF 镜像）
│   └── download_chattts_models.sh  # ChatTTS 预下载（HF 镜像）
├── models/                # AI 模型（预下载脚本写入，不入 Git）
│   ├── whisper/small/     # Faster-Whisper（含 model.bin）
│   ├── ChatTTS/           # ChatTTS 权重
│   └── hf_cache/          # HuggingFace 缓存
├── logs/                  # PM2 日志
├── uploads/               # 上传临时文件
├── outputs/               # 合成 wav 输出
├── .env                   # 服务器本地配置（Ollama IP 等，不入 Git）
├── speaker_emb.pt         # 音色文件（Web UI 生成，需手动备份）
└── trading_studio.log     # 应用日志
```

---

## 1. 硬件与系统前提

| 项目 | 要求 |
|------|------|
| GPU | NVIDIA RTX 3060 Ti 8GB |
| 功耗墙 | 120W（推荐锁定，见下文） |
| 系统 | Ubuntu 22.04 / 24.04 LTS |
| 内存 | ≥ 16GB |
| 磁盘 | ≥ 30GB 可用（含模型缓存） |
| 网络 | 局域网可访问 `192.168.8.64:11434` |

```bash
# 基础工具
sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl wget build-essential \
    python3 python3-venv python3-dev \
    ffmpeg libsndfile1 portaudio19-dev
```

> 若 `python3-venv` 包名报错，使用 `python3-venv`。

---

## 2. 3060 Ti 120W 功耗墙配置

锁定 GPU 功耗有助于稳定 7×24 运行、降低散热压力，避免 Whisper + ChatTTS 并发时触发功耗波动。

### 2.1 安装 nvidia-smi 功耗管理工具

驱动安装后自带 `nvidia-smi`。确认 GPU 可见：

```bash
nvidia-smi
```

### 2.2 临时设置 120W 功耗上限

```bash
# 查看支持的功耗范围
nvidia-smi -q -d POWER | grep -A3 "Power Limit"

# 设置最大功耗为 120W（需 root）
sudo nvidia-smi -pl 120
```

### 2.3 开机持久化（推荐）

创建 systemd 服务，每次启动自动应用：

```bash
sudo tee /etc/systemd/system/nvidia-powerlimit.service << 'EOF'
[Unit]
Description=Set NVIDIA GPU Power Limit to 120W
After=multi-user.target

[Service]
Type=oneshot
ExecStart=/usr/bin/nvidia-smi -pl 120
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable nvidia-powerlimit.service
sudo systemctl start nvidia-powerlimit.service

# 验证
nvidia-smi --query-gpu=power.limit --format=csv
```

---

## 3. NVIDIA 驱动与 CUDA

### 3.1 安装驱动（推荐 535+ 或 550+）

```bash
# Ubuntu 自动安装推荐驱动
sudo ubuntu-drivers devices
sudo ubuntu-drivers autoinstall
# 或指定版本: sudo apt install nvidia-driver-550

sudo reboot
```

重启后验证：

```bash
nvidia-smi
nvcc --version   # 若未安装 nvcc 不影响 PyTorch，可选
```

### 3.2 cuDNN（Faster-Whisper / PyTorch 需要）

PyTorch cu121 wheel 通常自带运行时库。若 Whisper 报 cuDNN 错误：

```bash
# 参考 NVIDIA 官方文档安装 cuDNN for CUDA 12.x
# https://developer.nvidia.com/cudnn
```

---

## 4. Python 虚拟环境

```bash
# 克隆项目
cd /opt
git clone https://git.bz121.com/dekun/Trading_Studio.git
cd Trading_Studio

# 创建虚拟环境（必须使用 venv，与 PM2 interpreter 路径一致）
python3 -m venv venv

# 激活
source venv/bin/activate

# 升级 pip
pip install --upgrade pip setuptools wheel
```

**重要：** PM2 配置中 `interpreter` 指向 `./venv/bin/python`，请确保在项目根目录创建 `venv/`。

---

## 5. PyTorch CUDA 12.1 安装

**必须先于其他 GPU 依赖安装**，避免 pip 拉取 CPU 版 torch。

```bash
source venv/bin/activate

pip install torch torchvision torchaudio \
    --index-url https://download.pytorch.org/whl/cu121
```

验证 CUDA 可用：

```bash
python -c "
import torch
print('PyTorch:', torch.__version__)
print('CUDA available:', torch.cuda.is_available())
print('GPU:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'N/A')
"
```

期望输出类似：

```
PyTorch: 2.x.x+cu121
CUDA available: True
GPU: NVIDIA GeForce RTX 3060 Ti
```

---

## 6. 项目依赖安装

```bash
source venv/bin/activate
cd /opt/Trading_Studio

# 安装其余依赖
pip install -r requirements.txt
```

### 6.1 Faster-Whisper（必须预下载）

随 `requirements.txt` 安装。`whisper_service.py` **优先从本地目录加载**，未预下载时会尝试在线拉取 HuggingFace 模型。

内网服务器无法访问外网时会报：

```
Whisper 模型加载失败: Network is unreachable
```

**处理：** 见 [0.8 AI 模型预下载](#08-ai-模型预下载内网服务器必做)，或执行：

```bash
bash scripts/download_whisper_models.sh small
pm2 restart trading_studio
```

本地路径：`/opt/Trading_Studio/models/whisper/small/model.bin`（约 500MB）。

可选环境变量（`.env`）：`WHISPER_MODEL_DIR`、`WHISPER_MODEL_SIZE`、`HF_ENDPOINT`。

### 6.2 ChatTTS（必须预下载，勿依赖 GitHub）

从 GitHub 源码安装 pip 包（已在 requirements.txt 中指定）：

```bash
pip install ChatTTS @ git+https://github.com/2noise/ChatTTS.git
```

**重要：** 默认 `chat.load()` 会访问 **github.com** 下载 asset，国内/内网服务器常报 `Read timed out`。  
`tts_service.py` 已支持从 `models/ChatTTS` 离线加载，部署后**必须**预下载：

```bash
bash scripts/download_chattts_models.sh
pm2 restart trading_studio
```

模型保存至 `/opt/Trading_Studio/models/ChatTTS`（约 1–2GB，不入 Git）。  
下载完成后再在 Web UI 点击「锁定音色」。

一键下载 Whisper + ChatTTS：`bash scripts/download_all_models.sh`

### 6.3 Gradio

```bash
pip install gradio>=4.44.0
```

---

## 7. 远程 Ollama 节点配置

Trading Studio 的 LLM 润色模块连接局域网 Ollama，**不在本机运行大模型**。

| 配置项 | 值 |
|--------|-----|
| 地址 | `http://192.168.8.64:11434` |
| API | `POST /api/chat` |
| 模型 | `huihui_ai/gemma-4-abliterated:e4b` |
| 流式 | `stream: false` |

### 7.1 在 Ollama 节点（192.168.8.64）上

```bash
# 安装 Ollama（若未安装）
curl -fsSL https://ollama.com/install.sh | sh

# 拉取模型
ollama pull huihui_ai/gemma-4-abliterated:e4b

# 允许局域网访问（编辑 systemd 或环境变量）
sudo systemctl edit ollama
```

添加：

```ini
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
```

```bash
sudo systemctl daemon-reload
sudo systemctl restart ollama
```

### 7.2 在本机（Trading Studio 服务器）验证

```bash
curl http://192.168.8.64:11434/api/tags

curl http://192.168.8.64:11434/api/chat -d '{
  "model": "huihui_ai/gemma-4-abliterated:e4b",
  "messages": [{"role": "user", "content": "ping"}],
  "stream": false
}'
```

---

## 8. 首次运行与验证

```bash
source venv/bin/activate
cd /opt/Trading_Studio

# 前台启动（调试）
python app.py
```

浏览器访问：

```
http://<本机局域网IP>:5683
```

### 8.1 验证清单

- [ ] `models/whisper/small/model.bin` 存在（`bash scripts/download_whisper_models.sh small`）
- [ ] `models/ChatTTS/` 已预下载（`bash scripts/download_chattts_models.sh`）
- [ ] 页面加载，Ollama 状态显示在线
- [ ] 上传 10-30s 参考人声 → 音色锁定成功，生成 `speaker_emb.pt`
- [ ] 上传复盘录音 → Whisper 识别出中文文本（无需外网）
- [ ] 点击润色 → 返回 Gemma4 处理后的文稿
- [ ] 点击合成 → `outputs/` 下生成 24kHz wav

### 8.2 日志位置

- 应用日志：`trading_studio.log`（项目根目录）
- PM2 日志：`logs/pm2-out.log`、`logs/pm2-error.log`

```bash
mkdir -p logs
```

---

## 9. PM2 进程守护

Trading Studio 原生支持 PM2 常驻管理，确保 Gradio 服务崩溃后自动重启、开机自启。

### 9.1 安装 Node.js 与 PM2

```bash
# 安装 Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 全局安装 PM2
sudo npm install -g pm2
```

### 9.2 方式 A：使用 ecosystem.config.js（推荐）

项目已内置 `ecosystem.config.js`：

```javascript
module.exports = {
  apps: [{
    name: "trading_studio",
    script: "app.py",
    interpreter: "./venv/bin/python",
    cwd: __dirname,
    instances: 1,
    autorestart: true,
    max_memory_restart: "6G",
    env: {
      PYTHONUNBUFFERED: "1",
      CUDA_VISIBLE_DEVICES: "0",
    },
  }],
};
```

启动：

```bash
cd /opt/Trading_Studio
mkdir -p logs

pm2 start ecosystem.config.js
pm2 status
pm2 logs trading_studio --lines 50
```

> **推荐：** 直接使用 `bash deploy.sh` 一键完成上述步骤，见 [第 0 节](#0-一键部署推荐)。

### 9.3 方式 B：直接命令行

```bash
cd /opt/Trading_Studio

pm2 start app.py \
    --name "trading_studio" \
    --interpreter ./venv/bin/python

pm2 save
```

### 9.4 开机自启

```bash
pm2 startup
# 按提示执行输出的 sudo 命令

pm2 save
```

### 9.5 常用运维命令

```bash
pm2 restart trading_studio    # 重启（改代码后）
pm2 stop trading_studio       # 停止
pm2 delete trading_studio     # 移除
pm2 monit                     # 实时监控 CPU/内存
```

### 9.6 更新代码后重新部署

```bash
cd /opt/Trading_Studio
bash deploy.sh update
```

或手动：

```bash
cd /opt/Trading_Studio
git pull
source venv/bin/activate
pip install -r requirements.txt   # 若有新依赖
pm2 restart trading_studio
```

---

## 10. 迁移与故障排查

### 10.1 迁移到新机器

1. 备份 `/opt/Trading_Studio/speaker_emb.pt`（音色文件，不入 Git）
2. 新机器执行 `bash deploy.sh` 一键部署
3. 将 `speaker_emb.pt` 复制回 `/opt/Trading_Studio/`
4. `bash deploy.sh restart`

### 10.2 CUDA / 显存问题

```bash
# 查看显存占用
nvidia-smi

# 若 OOM，确保无其他 GPU 进程
fuser -v /dev/nvidia*
```

Whisper 与 ChatTTS **不能同时常驻** 8GB 显存（会 CUDA OOM）。应用已自动互斥卸载：

- 识别前卸载 ChatTTS
- 合成 / 锁定音色前卸载 Whisper

若仍 OOM：

```bash
pm2 restart trading_studio
nvidia-smi   # 确认无其他占 GPU 进程
```

在 `.env` 调低合成峰值：

```ini
TTS_MAX_CHARS_PER_CHUNK=150
TTS_MAX_NEW_TOKEN=768
```

PM2 已配置 `PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True` 缓解碎片。建议锁定 120W 功耗墙。

### 10.3 Whisper 模型加载失败

#### A. `Network is unreachable` / `ConnectError`（内网无外网）

**原因：** 未预下载 Whisper 模型，程序尝试访问 HuggingFace Hub 失败。

**处理：**

```bash
cd /opt/Trading_Studio
bash scripts/download_whisper_models.sh small
ls -lh models/whisper/small/model.bin   # 确认约 500MB
pm2 restart trading_studio
```

若服务器可访问外网但 HuggingFace 慢，在 `.env` 中设置 `HF_ENDPOINT=https://hf-mirror.com` 后重试下载。

#### B. CUDA / 显存报错

```
错误: CUDA initialization failed / out of memory
```

处理：

1. 重启 PM2 进程释放显存
2. 确认 `compute_type="float16"`（已在 config.py 配置）
3. 在 `.env` 中降级模型：`WHISPER_MODEL_SIZE=base`，并执行 `bash scripts/download_whisper_models.sh base`

### 10.4 Ollama 超时

```
连接 Ollama 超时（>60s）
```

处理：

1. 确认 Ollama 节点模型已预加载：`ollama run huihui_ai/gemma-4-abliterated:e4b`
2. 增大 `config.py` 中 `OLLAMA_TIMEOUT`
3. 检查防火墙：`sudo ufw allow from 192.168.8.0/24 to any port 11434`（在 Ollama 节点）

### 10.5 ChatTTS 合成报 `Corrupt input data`

**原因：** 音色参数传错。`sample_audio_speaker()` 的结果应作为 **`spk_smp`**，不能同时误传给 **`spk_emb`**（LZMA 解压失败）。旧版 `speaker_emb.pt` 或未填参考转写时常见。

**处理：**

```bash
rm /opt/Trading_Studio/speaker_emb.pt
pm2 restart trading_studio
```

在 Web UI「音色锁定」：

1. 上传 10–30 秒干净参考人声  
2. **填写与录音完全一致的「参考音频精确转写」**（必填）  
3. 重新点击「锁定音色」后再合成  

### 10.6 ChatTTS 音色文件损坏

```bash
rm speaker_emb.pt
# 重新在 Web UI「音色锁定」上传参考人声并填写转写
```

### 10.7 端口 5683 被占用

```bash
sudo lsof -i :5683
# 或
ss -tlnp | grep 5683
```

### 10.8 手机「找不到麦克风」

内网 `http://192.168.x.x:5683` 下手机无法使用实时录音，属浏览器 HTTPS 安全限制。  
完整说明与 NPS 穿透方案见 [0.9 手机「找不到麦克风」](#09-手机找不到麦克风) 与 [PWA_NPS.md](./PWA_NPS.md) 第九节。

**临时方案：** Web UI 音频区域使用 **「上传」** 导入录音文件，Whisper 识别流程相同。

---

## 附录：防火墙（本机 Gradio）

若需局域网其他设备访问 Web UI：

```bash
sudo ufw allow 5683/tcp
sudo ufw reload
```

访问地址：`http://<服务器局域网IP>:5683`

---

## 附录：config.py / .env 关键配置速查

**服务器本地覆盖请用 `.env`**（`cp .env.example .env`），避免 `git pull` 冲突：

```ini
OLLAMA_HOST=192.168.8.64
OLLAMA_PORT=11434
HF_ENDPOINT=https://hf-mirror.com
WHISPER_MODEL_DIR=/opt/Trading_Studio/models/whisper
WHISPER_MODEL_SIZE=small
CHATTTS_MODEL_DIR=/opt/Trading_Studio/models/ChatTTS
```

`config.py` 默认值（可被 `.env` 覆盖）：

```python
HOST = "0.0.0.0"
PORT = 5683
WHISPER_MODEL_SIZE = "small"          # .env: WHISPER_MODEL_SIZE
WHISPER_MODEL_DIR = "models/whisper"  # .env: WHISPER_MODEL_DIR
WHISPER_DEVICE = "cuda"
WHISPER_COMPUTE_TYPE = "float16"
CHATTTS_MODEL_DIR = "models/ChatTTS"
HF_ENDPOINT = "https://hf-mirror.com"
SPEAKER_EMB_PATH = "speaker_emb.pt"
TTS_SAMPLE_RATE = 24000
```

---

**部署完成后，请先在「音色锁定」模块完成首次音色提取，再进行日常复盘配音生产。**