# 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-一键部署推荐)
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 报本地修改冲突？** 执行：
> ```bash
> git stash push -m "backup" -- config.py llm_service.py
> git pull
> pm2 restart trading_studio
> ```

### 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
```

### 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.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.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              # 一键部署脚本
├── app.py                 # Gradio 主入口
├── venv/                  # Python 虚拟环境
├── logs/                  # PM2 日志
├── uploads/               # 上传临时文件
├── outputs/               # 合成 wav 输出
├── 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` 安装。首次运行会自动下载 `small` 模型（约 500MB）至 HuggingFace 缓存。

### 6.2 ChatTTS

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

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

首次 `save_fixed_speaker` 或 `generate_voice` 时会下载模型权重（数 GB），请确保网络畅通或提前配置 HuggingFace 镜像：

```bash
export HF_ENDPOINT=https://hf-mirror.com   # 可选，国内加速
```

### 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 验证清单

- [ ] 页面加载，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 不会同时常驻最大显存，但首次加载模型时峰值较高。建议：

- 锁定 120W 功耗墙
- `max_memory_restart: "6G"` 已在 PM2 配置中设置

### 10.3 Whisper CUDA 报错

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

处理：

1. 重启 PM2 进程释放显存
2. 确认 `compute_type="float16"`（已在 config.py 配置）
3. 降级模型为 `base`（修改 `config.py` 中 `WHISPER_MODEL_SIZE`）

### 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 音色文件损坏

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

### 10.6 端口 5683 被占用

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

---

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

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

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

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

---

## 附录：config.py 关键常量速查

```python
HOST = "0.0.0.0"
PORT = 5683
OLLAMA_URL = "http://192.168.8.64:11434/api/chat"
MODEL_NAME = "huihui_ai/gemma-4-abliterated:e4b"
WHISPER_MODEL_SIZE = "small"
WHISPER_DEVICE = "cuda"
WHISPER_COMPUTE_TYPE = "float16"
SPEAKER_EMB_PATH = "speaker_emb.pt"
TTS_SAMPLE_RATE = 24000
```

---

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