第3章：Docker 部署

## 概述 使用 Docker 将 Voicebox 作为无头服务器运行，并附带 Web 界面

## 概述 Voicebox 可以作为一个带有完整 Web 界面的 Docker 容器运行——无需桌面应用。这非常适合无头服务器、共享 GPU 机器或自托管部署。

### 快速开始 git clone https://github.com/jamiepine/voicebox.git cd voicebox docker compose up 在浏览器中打开 http://localhost:17493。完整的 Voicebox 界面直接由后端提供服务。

首次构建需要几分钟（编译前端、安装 Python 依赖）。得益于 Docker 层缓存，后续启动速度很快。

### 工作原理 Docker 镜像采用三阶段构建：

前端 -- 使用 Bun 和 Vite 构建 React SPA 后端 -- 安装 Python 依赖和 TTS 模型包 运行时 -- 将两者合并为一个最小化的镜像，运行 FastAPI 服务器

当检测到已构建的前端时，后端会自动提供 Web 界面。所有 API 路由的表现与桌面应用完全一致。

## 配置 docker-compose.yml 默认的 docker-compose.yml 仅绑定到 localhost，挂载持久卷用于数据存储和模型缓存，并设置了合理的资源限制： services: voicebox: build: . container_name: voicebox restart: unless-stopped ports: - "127.0.0.1:17493:17493" volumes: - ./output:/app/data/generations - voicebox-data:/app/data - huggingface-cache:/home/voicebox/.cache/huggingface environment: - LOG_LEVEL=info deploy: resources: limits: cpus: '4' memory: 8G

### 暴露到网络 默认情况下，容器仅监听 127.0.0.1。若要允许网络中的其他机器连接，请修改端口绑定： ports: - "0.0.0.0:17493:17493" API 没有内置认证功能。仅将其暴露给受信任的网络，或在前面添加带有认证功能的反向代理。

### 环境变量 变量 默认值 描述 LOG_LEVEL info 日志详细程度（debug, info, warning, error） VOICEBOX_MODELS_DIR (HuggingFace 缓存) 自定义模型存储路径 VOICEBOX_CORS_ORIGINS (本地源) 额外的 CORS 源，逗号分隔

### 资源限制 默认 compose 文件将容器限制为 4 个 CPU 和 8GB 内存。请根据硬件进行调整： deploy: resources: limits: cpus: '8' memory: 16G TTS 模型推理非常消耗内存。运行单个引擎的最小需求为 8GB。如果希望同时加载多个引擎，建议至少 16GB。

### 数据卷 数据卷 容器路径 用途 ./output /app/data/generations 生成的音频文件（绑定挂载，便于从主机访问） voicebox-data /app/data 配置文件、数据库、缓存 huggingface-cache /home/voicebox/.cache/huggingface 下载的模型（在重建后持久化） huggingface-cache 数据卷非常重要——如果没有它，每次重建容器时模型都会重新下载。

## GPU 加速 NVIDIA GPU (CUDA) 要在容器内使用 NVIDIA GPU，请安装 NVIDIA Container Toolkit 并在 compose 文件中添加 GPU 访问权限： services: voicebox: build: . # ... 现有配置 ... deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu]

AMD GPU (ROCm) 对于 AMD GPU，使用 ROCm 运行时： services: voicebox: build: . # ... 现有配置 ... devices: - /dev/kfd - /dev/dri group_add: - video

仅 CPU 默认配置在 CPU 上运行。虽然可以正常工作，但生成速度较慢。LuxTTS 是 CPU 上最快的引擎（实时速度的 150 倍）。

## 安全 Docker 镜像遵循安全最佳实践：

非 root 用户 -- 服务器以 voicebox 身份运行，而非 root 本地绑定 -- 默认情况下只能从主机机器访问 健康检查 -- 如果服务器挂起则自动重启（每 30 秒轮询一次 /health 端点） CORS 限制 -- 默认仅允许本地源

## 运行在反向代理后面 对于生产环境部署，建议将 Voicebox 置于带有 TLS 和认证的 nginx 或 Caddy 后面： server { listen 443 ssl; server_name voicebox.example.com;

ssl_certificate /etc/ssl/certs/voicebox.pem; ssl_certificate_key /etc/ssl/private/voicebox.key;

auth_basic "Voicebox"; auth_basic_user_file /etc/nginx/.htpasswd;

location / { proxy_pass http://127.0.0.1:17493; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }

## 故障排除 容器启动但界面显示 JSON 如果你看到的是 {"message": "voicebox API", ...} 而不是 Web 界面，说明前端构建可能在 Docker 构建过程中失败。请检查构建日志： docker compose build --no-cache 在 "Build frontend" 阶段查找错误。

每次重启时重新下载模型 确保已配置 huggingface-cache 数据卷。如果没有，容器停止时模型缓存将丢失： volumes: - huggingface-cache:/home/voicebox/.cache/huggingface

内存不足 TTS 模型很大。如果容器被 OOM killer 终止，请增加内存限制： deploy: resources: limits: memory: 16G

端口已被占用 # 检查谁在使用端口 17493 lsof -i :17493

# 或使用不同的端口 ports: - "127.0.0.1:8080:17493"

## 预构建镜像（即将推出） 我们计划将预构建的 Docker 镜像发布到 GitHub Container Registry，这样你就不需要本地构建了： # 尚未可用 — 将在未来版本中推出 docker run -p 17493:17493 ghcr.io/jamiepine/voicebox:latest CPU 镜像大小约为 3-4 GB（Python + PyTorch + TTS 包）。为 NVIDIA GPU 用户提供的独立 CUDA 标签（约 6-8 GB）也将可用。对于 ML 容器而言，这是正常的。 目前，请使用 docker compose up 从源码构建，如上所述。

## 连接桌面应用 你也可以使用桌面应用作为 Docker 托管后端的界面。在桌面应用中，前往 设置 -> 服务器，启用 远程模式，并输入 http://<服务器IP>:17493。 详情请参阅远程模式指南。

在 GitHub 上编辑 安装 下载并在 macOS、Windows 或 Linux 上安装 Voicebox 快速开始 5 分钟内上手使用 Voicebox