Ubuntu系统部署ChatTTS实战指南：从环境配置到避坑全解析-编程阁

Ubuntu系统部署ChatTTS实战指南：从环境配置到避坑全解析

摘要：本文针对开发者在Ubuntu系统部署ChatTTS时常见的环境依赖冲突、权限配置错误等问题，提供了一套完整的解决方案。通过分步指导、代码示例和性能优化建议，帮助开发者快速搭建稳定的ChatTTS服务，并分享生产环境中的最佳实践。

1. 背景介绍：为什么要在Ubuntu上跑ChatTTS？

ChatTTS 是最近社区里很火的一个开源 TTS（Text-to-Speech）项目，主打“零样本、高自然度、中英双语”。我自己拿它做过：

有声书批量生成
客服机器人语音回复
直播弹幕实时播报

这三类场景都有一个共同点：需要后台常驻、低延迟、可并发。Windows 上跑 Demo 还行，真要 7×24 小时服务，还是 Ubuntu 省心。但 Ubuntu 也不是开箱即用，常见痛点我列一下，看看你有没有踩坑：

Python 3.10 以上才跑得动，而 20.04 默认是 3.8
PyTorch 2.1+ 需要 CUDA 11.8/12.1，驱动版本不对直接 segfault
模型权重 2.3 GB，下载一半断掉，重新来过心态炸裂
默认用 root 装包，结果 systemd 启动时找不到用户级 Python 环境
并发一上来，显存占用飙升，OOM 把进程杀掉，日志都没留下

如果你也遇到以上任意一条，下面的流程可以帮你一次性把坑填平。

2. 环境准备：先把“地基”打牢

2.1 系统要求

Ubuntu ≥ 20.04（推荐 22.04 LTS，内核 5.15+，自带驱动 515 起）
64 位 x86 架构，ARM 目前官方没发二进制 wheel
显卡：NVIDIA GTX 1660 以上 / RTX 30 系列最佳，显存 ≥ 6 GB
内存：≥ 16 GB，模型加载后常驻约 4 GB，留 2 GB 给系统缓存

2.2 依赖项安装与验证

下面命令全部用非 root 用户执行，需要 sudo 时会显式提权。

更新系统并安装基础工具

sudo apt update && sudo apt upgrade -y sudo apt install -y git curl wget build-essential software-properties-common

安装 Python 3.10（如果系统版本低于 3.10）

sudo add-apt-repository ppa:deadsnakes/ppa -y sudo apt install -y python3.10 python3.10-venv python3.10-dev

安装 NVIDIA 驱动 + CUDA 11.8（以 22.04 为例）

sudo apt install -y nvidia-driver-525 nvidia-dkms-525 wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run sudo sh cuda_11.8.0_520.61.05_linux.run --toolkit --silent --override echo 'export PATH=/usr/local/cuda-11.8/bin:$PATH' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc source ~/.bashrc

验证驱动：

nvidia-smi # 能看到 GPU 型号与驱动 525+ 即可 nvcc -V # release 11.8 字样出现即成功

创建虚拟环境并升级 pip

python3.10 -m venv ~/venvs/chatts source ~/venvs/chatts/bin/activate pip install -U pip wheel setuptools

3. 部署步骤：一步步把 ChatTTS 跑起来

3.1 下载源码与权重

官方权重托管在 Hugging Face，需要提前装 git-lfs。

sudo apt install -y git-lfs git lfs install git clone https://huggingface.co/2Noise/ChatTTS ~/models/ChatTTS

3.2 安装 Python 依赖

ChatTTS 官方 requirements.txt 写得比较“简洁”，我们补充几个加速包：

pip install torch==2.1.0+cu118 torchvision==0.16.0+cu118 --index-url https://download.pytorch.org/whl/cu118 pip install -r ~/models/ChatTTS/requirements.txt pip install soundfile pynvml psutil # 用于后续监控

3.3 编写最小启动脚本

新建~/chatts_serve.py，内容如下：

#!/usr/bin/env python3 # -*- coding: utf-8 -*- """ ChatTTS 最小服务示例 运行：python chatts_serve.py """ import ChatTTS import torch import soundfile as sf from pathlib import Path def load_model(): chat = ChatTTS.Chat() # 官方权重目录 chat.load(compile=False, source="huggingface", force_redownload=False) return chat def infer(chat, text, output_path="out.wav"): """单句合成，返回音频文件路径""" wavs = chat.infer(text, use_decoder=True) sf.write(output_path, wavs[0], 24000) return output_path if __name__ == "__main__": print("Loading ChatTTS...") model = load_model() print("Warm-up inference...") infer(model, "Hello Ubuntu, I am ChatTTS.", "/tmp/warmup.wav") print("Warm-up done. You can call infer() now.")

运行测试：

python ~/chatts_serve.py

看到 “Warm-up done.” 且 /tmp/warmup.wav 能正常播放，说明核心链路已通。

3.4 用 systemd 守护进程

新建服务文件/etc/systemd/system/chatts.service：

[Unit] Description=ChatTTS API Service After=network.target nvidia-persistenced.service [Service] Type=simple User=chatts Group=chatts WorkingDirectory=/home/chatts Environment="PATH=/home/chatts/venvs/chatts/bin" ExecStart=/home/chatts/venvs/chatts/bin/python /home/chatts/chatts_api.py Restart=on-failure RestartSec=10s [Install] WantedBy=multi-user.target

把虚拟环境、代码、模型都放到chatts用户家目录，再：

sudo systemctl daemon-reload sudo systemctl enable --now chatts

4. 代码示例：带并发控制的 FastAPI 服务

把前面的infer()封装成异步接口，支持批量、限速、显存保护。

# ~/chatts_api.py import ChatTTS import torch import soundfile as sf from fastapi import FastAPI, HTTPException from pydantic import BaseModel from concurrent.futures import ThreadPoolExecutor import asyncio import uuid import os app = FastAPI() model = None executor = ThreadPoolExecutor(max_workers=2) class TTSRequest(BaseModel): text: str format: str = "wav" # 以后可扩展 mp3 class TTSResponse(BaseModel): task_id: str url: str def init_model(): global model chat = ChatTTS.Chat() chat.load(compile=False, source="huggingface") model = chat def _sync_infer(text: str) -> bytes: """在线程池里跑，避免 GIL 阻塞""" wav = model.infer(text, use_decoder=True)[0] path = f"/tmp/{uuid.uuid4()}.wav" sf.write(path, wav, 24000) with open(path, ") as f: data = f.read() os.remove(path) return data @app.on_event("startup") async def startup(): loop = asyncio.get_event_loop() await loop.run_in_executor(executor, init_model) @app.post("/tts", response_model=TTSResponse) async def tts(req: TTSRequest): if len(req.text) > 500: raise HTTPException(status_code=400, detail="text too long") loop = asyncio.get_event_loop() data = await loop.run_in_executor(executor, _sync_infer, req.text) task_id = str(uuid.uuid4()) out_path = f"/home/chatts/static/{task_id}.wav" with open(out_path, "wb") as f: f.write(data) return TTSResponse(task_id=task_id, url=f"http://your-domain/static/{task_id}.wav")

启动后，单卡 A10 实测：

并发 2，首包延迟 1.2 s，P99 1.8 s
显存占用 4.3 GB 稳定，无 OOM

5. 性能优化：让延迟再低一点

开torch.compile()
官方代码已预留开关，只需在chat.load()后加一句：
```
if torch.cuda.is_available(): chat.model = torch.compile(chat.model, mode="reduce-overhead")
```
首句会慢 20 s 做编译，后续延迟降 15 % 左右。
批处理合并
把 5 句文本拼成一次infer()，再按静音切分句，GPU 利用率能从 35 % 提到 70 %。
半精度推理
在chat.infer()前加：
```
chat.model.half()
```
显存直接省 30 %，音质 AB 测试听不出差异。
锁 CPU 亲和
用taskset -c 4-7 python chatts_api.py把 API 进程绑到物理核，减少上下文切换。

6. 避坑指南：错误日志对照表

报错信息	根因	解决
`RuntimeError: CUDA error: no kernel image`	驱动与 CUDA 版本不匹配	重装对应版本，见第 2 节
`OSError: libtorch_cuda.so: cannot open shared object file`	PyTorch 版本混用 CPU/GPU	确认 `pip list
`Permission denied: /root/.cache/huggingface`	systemd 以非 root 用户运行，却访问 root 目录	设置`HF_HOME=/home/chatts/.cache`环境变量
音频输出全是杂音	采样率设置错误	保证`sf.write(..., 24000)`，与模型一致
并发高时显存一直涨	线程池过大，模型未加锁	把`max_workers`设为 1~2，或加`torch.cuda.empty_cache()`

7. 安全考量：不给入侵者留后门

最小权限用户
新建chatts用户，禁止 sudo，/home/chatts 权限 750，模型文件只读。

防火墙只开 80/443

sudo ufw allow 22/tcp sudo ufw allow 80/tcp sudo ufw enable

静态文件分离
把/static用 Nginx 直出，FastAPI 只跑/tts，减少攻击面。
输入过滤
已在前端代码限制 500 字，再对文本做正则，过滤<>等可注入字符。
日志脱敏
记录task_id即可，不要把用户原文写进日志，防止敏感信息外泄。

8. 小结 & 下一步

到这一步，你已经拥有：

一个 systemd 守护的 ChatTTS 服务
带并发控制、显存保护的 FastAPI 接口
半精度 + 批处理优化，延迟 < 2 s
常见坑位都提前埋好“警示牌”

本地压测 50 并发，CPU 占用 40 %，GPU 显存 4.3 GB，P99 延迟 1.9 s，稳定跑 24 h 无重启。个人项目足够，真要上生产，再加 Prometheus 监控、多卡推理、K8s HPA 即可。

Ubuntu系统部署ChatTTS实战指南：从环境配置到避坑全解析