VoiceStudio Docker 部署指南在自有硬件上运行 headless 全本地语音引擎【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio本文以 VoiceStudio 官方 Docker 镜像Docker Hub / GHCR 双镜像源为线索系统讲解其 headless Web 服务器构建的定位、硬件要求、CPU / NVIDIA GPU / AMD ROCm 三种快速启动方式、镜像标签语义、Compose 部署、持久化卷与网络安全配置。读完本文你将能在一台 AMD64 主机上无 GPU 亦可用几条命令拉起一个完全本地、无需任何云 API Key 的语音服务并通过浏览器使用语音克隆、视频配音、听写、转写与有声书创作等能力同时你将理解OMNIVOICE_SERVER_MODE、OMNIVOICE_API_KEY、OMNIVOICE_PUBLIC_API_BASE等关键环境变量背后的源码级原理知道如何安全地在局域网或反向代理后暴露服务。镜像定位headless Web 服务器构建VoiceStudio 官方镜像对应的是仓库中独立的headless web-server 构建由 FastAPI 后端backend/main.py提供 API并直接托管一份预构建的 React 前端SPA静态资源通过 HTTP 对外提供服务。与 Tauri 桌面应用不同容器内没有桌面外壳你需要在浏览器中打开界面。两点值得在拉镜像前明确自动更新机制不适用Tauri 桌面应用的自动更新器与更新频道切换Settings → About → Update channel是桌面端独有能力。镜像部署的更新方式是拉取新 tag 并重建容器docker compose pull docker compose up -d。全部数据留在本地推理完全发生在你自己的硬件上CUDA / ROCm / CPU 自动探测不向云端发送任何内容也不需要注册账号或云 API Key。官方镜像在两个仓库同时发布、tag 语义完全一致ghcr.io/debpalash/omnivoice-studio。架构限制仅 linux/amd64无原生 ARM64发布的所有镜像包括:stable、:latest与全部:rocm变体均为linux/amd64x86-64。在 ARM64 主机上直接docker pull可能报错no matching manifest for linux/arm64/v8 in the manifest list entriesApple SiliconM 系列 Mac请使用原生 macOS 应用它支持 Apple GPU 加速MPS/MLX。Linux 容器无法访问 Mac 的 Apple GPU。ARM64 上的 AMD64 模拟如果你的 Docker 支持模拟可在docker pull与docker run的镜像名之前加--platform linux/amd64。这只是 CPU 模拟方案推理会明显变慢且不是 GPU 的替代方案。Docker Compose 的特殊性Compose 没有逐命令的--platform参数需在运行 Compose 的 shell 中设置export DOCKER_DEFAULT_PLATFORMlinux/amd64否则镜像解析到不存在的 ARM64 manifest 而失败模拟场景下只有 CPU profile 有意义。该变量只存在于当前 shell 及其启动的进程中。硬件与资源要求资源最低推荐/舒适内存8 GB RAM16 GB磁盘约 10 GB模型权重 缓存20 GBGPU 显存4 GBTTS 自动卸载到 CPU8 GB无 GPU可以整条流水线纯 CPU 运行只是更慢—镜像拉取体积约 5 GB 压缩CUDA/CPU 镜像:rocm变体约 15 GB快速开始CPU先在一个保持打开的 shell 中生成管理员 API Keyexport OMNIVOICE_API_KEY$(python3 -c import secrets; print(secrets.token_urlsafe(32)))然后启动容器docker run -d --name omnivoice \ -p 127.0.0.1:3900:3900 \ -e OMNIVOICE_API_KEY$OMNIVOICE_API_KEY \ -v omnivoice-data:/app/omnivoice_data \ -v ~/.cache/huggingface:/root/.cache/huggingface \ palashdeb/omnivoice-studio:latest浏览器打开 http://localhost:3900。首次运行会下载数 GB 的模型权重文档称约 2.4 GB属正常范围用docker logs -f omnivoice观察进度。UI 提示输入 API Key 时粘贴上面生成的值——由于 Docker NAT 会隐藏浏览器真实的回环来源设置项与诊断操作必须依赖这个管理员会话原理见下文服务模式与认证一节。快速开始NVIDIA GPUexport OMNIVOICE_API_KEY$(python3 -c import secrets; print(secrets.token_urlsafe(32))) docker run -d --name omnivoice --gpus all \ -p 127.0.0.1:3900:3900 \ -e OMNIVOICE_API_KEY$OMNIVOICE_API_KEY \ -v omnivoice-data:/app/omnivoice_data \ -v ~/.cache/huggingface:/root/.cache/huggingface \ palashdeb/omnivoice-studio:latestGPU 模式要求宿主机已安装 NVIDIA Container Toolkit。排查时可先验证宿主机 CUDA 容器可访问 GPUdocker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi快速开始AMD GPU / ROCmAMD GPU 必须使用专门的:rocm镜像变体——默认CUDA镜像在 AMD 硬件上只会走 CPU。ROCm 用户态已打包进镜像宿主机只需amdgpu内核驱动无需容器工具包把 GPU 作为设备节点直通即可export OMNIVOICE_API_KEY$(python3 -c import secrets; print(secrets.token_urlsafe(32))) docker run -d --name omnivoice \ --device /dev/kfd --device /dev/dri \ -p 127.0.0.1:3900:3900 \ -e OMNIVOICE_API_KEY$OMNIVOICE_API_KEY \ -v omnivoice-data:/app/omnivoice_data \ -v ~/.cache/huggingface:/root/.cache/huggingface \ palashdeb/omnivoice-studio:rocmPodman 用户同样传两个--device标志Quadlet 单元里写成两行AddDevice/dev/kfd、AddDevice/dev/dri。RDNA3 消费级显卡RX 7900 XTX/XT 等若 GPU 未被识别可加-e HSA_OVERRIDE_GFX_VERSION11.0.0。但请注意 docs/install/docker.md 的告诫后端会在你的显卡 GFX ID 不在镜像 ROCm 构建的架构列表中时自动设置该覆盖变量所以应先不加覆盖运行一次给原生受支持的 GPU如 ROCm 7.x 上的 gfx1151强行覆盖只会把它赶到不匹配的 kernel 上。无 root 宿主机若/dev/kfd为组所有容器用户需要这些组按宿主机getent group render video的结果加--group-add。验证容器是否看到 GPUROCm 构建的 PyTorch 也通过torch.cuda.*上报docker exec container python3 -c \ import torch; ok torch.cuda.is_available(); print(ok, torch.cuda.get_device_name(0) if ok else unavailable)这只能证明 torch 能看到显卡不代表应用一定在用它Settings → Performance Device显示的是 VoiceStudio 实际解析到的设备Model Catalogue 应同时报告omnivoice与omnivoice-subprocess在 ROCm 上加速。若显示cpu查看后端日志中以Falling back to CPU:开头的行它会指出架构不匹配的原因。WSL2 下的 AMD GPUWSL 通过/dev/dxg暴露 AMD 计算能力而非原生 Linux 的/dev/kfd、/dev/dri。需在 WSL 发行版内先安装 ROCm 与librocdxg并确认宿主侧rocminfo能看到 GPU再按librocdxg的 WSL 容器约定加桥接参数--device /dev/dxg、挂载libdxcore.so/librocdxg.so/dids.conf、-e HSA_ENABLE_DXG_DETECTION1、--cap-add SYS_PTRACE、--security-opt seccompunconfined、--ipchost --shm-size 8G等。当前镜像使用 ROCm 7.2.x故必须HSA_ENABLE_DXG_DETECTION1ROCk 7.13 起才取消该要求。这些标志会削弱容器隔离因此请保持端口绑定在127.0.0.1且勿在此容器中运行不受信任的工作负载。WSL 下 RX 6700 XTgfx1031目前被分类为Unverified可映射到gfx1030但尚无公开的端到端验证记录。完整说明与证据要求见 docs/install/docker.md。Docker Compose推荐仓库自带完整的 Compose 文件 deploy/docker-compose.yml内置cpu / gpu / rocm三个 Studio profile以及worker-gpu / worker-rocm两个只借 GPU、不暴露 Web UI的 worker profile# 在为 Compose 服务的 shell 中生成一次 export OMNIVOICE_API_KEY$(python3 -c import secrets; print(secrets.token_urlsafe(32))) # CPU docker compose -f deploy/docker-compose.yml --profile cpu up -d # NVIDIA GPU docker compose -f deploy/docker-compose.yml --profile gpu up -d # AMD GPU (ROCm) docker compose -f deploy/docker-compose.yml --profile rocm up -dCompose 的 host 端口默认也是127.0.0.1:3900:3900容器内部由OMNIVOICE_BIND_HOST0.0.0.0绑定真正把服务限制在回环的是host 侧的127.0.0.1:前缀——这与后端源码默认127.0.0.1的语义见 backend/main.py一致Docker 场景由 Compose 显式放开容器内绑定。Compose 定义了自己的 healthcheckcurl -sf http://localhost:3900/health与restart: unless-stopped。只借 GPU 的 worker 容器若要把一块 headless GPU 借给另一台机器上运行的 VoiceStudio 控制面可在控制面生成 join code 后启动 worker profile# NVIDIA OMNIVOICE_WORKER_TOKENovw_… docker compose \ -f deploy/docker-compose.yml --profile worker-gpu up -d # AMD / ROCm OMNIVOICE_WORKER_TOKENovw_… docker compose \ -f deploy/docker-compose.yml --profile worker-rocm up -d这些 profile不发布任何 HTTP 端口、不需要浏览器 UIuvicorn 只承载持有出站 worker agent 的应用生命周期。join code 必须指向容器可达的 LAN 或私有叠加网络地址不能是控制面的127.0.0.1注册状态持久化在专用卷中因此即使 join code 是一次性的容器重启后也能自动重连。容器健康状态只有在控制面接受注册后才变绿token 缺失或无效时保持 unhealthy而非误报 Web 后端就绪。注册、审批、路由与安全细节见 docs/remote-workers.md。镜像标签语义Tag含义:latest滚动预览——main分支最新提交位于或领先于最近一次发布属预览频道生产环境请固定:stable:stable最近一次版本化发布每次v*git tag 更新:0.5.2精确发布版本:0.50.5小版本内的最新补丁:main与:latest相同的滚动main构建的别名:sha-xxxxxxx特定提交手动 workflow dispatch 产生:rocm滚动预览的AMD GPU (ROCm)构建等价于 ROCm 版的:latest:stable-rocm、:0.5.2-rocm、:0.5-rocm、:sha-xxxxxxx-rocm对应上述 tag 的 ROCm 构建版本规则预览构建始终来自main且版本排序上不会低于:stable因此升级路径自然顺畅。同一批镜像与 tag 在 GHCR 的ghcr.io/debpalash/omnivoice-studio同步镜像。核对运行中版本可用docker exec container python3 -c import importlib.metadata; print(importlib.metadata.version(omnivoice)) # 或直接访问 /health返回 {status: ok, device: ..., version: 0.x.x}值得持久化的数据卷挂载用途omnivoice-data:/app/omnivoice_data项目数据库、用户声音、设置、加密的 HF token——升级后依然存活~/.cache/huggingface:/root/.cache/huggingfaceHF 模型缓存——复用宿主机缓存可省去数 GB 重复下载注意镜像内HF_HOME/app/omnivoice_data/huggingface见 deploy/DockerfileCompose 中亦有对应HF_HOME环境变量模型缓存整体落在数据卷内。配置与网络端口语义容器内 0.0.0.0宿主侧回环镜像内 uvicorn 绑定0.0.0.0:3900DockerfileENTRYPOINT为python3 -m uvicorn backend.main:app --host 0.0.0.0 --port 3900而宿主侧127.0.0.1:3900:3900的映射才是保持仅本机可访问的关键。改成0.0.0.0:3900:3900即对局域网开放。前端默认请求与页面同源的 API因此从http://lan-ip:3900打开 UI 时页面加载与其后的 API/媒体请求都能正常工作。反向代理OMNIVOICE_PUBLIC_API_BASE如果前端页面与 API 落在不同源典型如反向代理拆分域名需要显式钉住 API 基址。使用OMNIVOICE_PUBLIC_API_BASE——这是一个运行时环境变量后端会把它注入页面因此对预构建镜像用docker run -e即可生效无需重新构建docker run -e OMNIVOICE_API_KEY$OMNIVOICE_API_KEY \ -e OMNIVOICE_PUBLIC_API_BASEhttps://api.your-host.example \ -p 0.0.0.0:3900:3900 \ palashdeb/omnivoice-studio:latest其实现位于 backend/core/spa_inject.py后端在 backend/main.py 启动时读取该变量校验为纯http(s)://…URL 后把window.__OMNIVOICE_API_BASE__注入index.html的headSPA 的 API 解析器优先读取它。校验失败的取值会被忽略并回退到同源。早先的VITE_OMNIVOICE_API是在构建期内联的对预构建镜像无效。服务模式与认证OMNIVOICE_SERVER_MODE 与 OMNIVOICE_API_KEYDocker NAT 会把请求的来源 IP 重写为网桥网关地址即使-p 127.0.0.1:3900:3900回环映射后端也无法证明浏览器就在宿主机上。因此镜像内置OMNIVOICE_SERVER_MODE1见 deploy/Dockerfile放宽桌面端专属的回环来源门禁使/system/*与/api/settings/*等管理路由在 Docker NAT 下可用对应历史 issue #261。其鉴权规则在 backend/api/dependencies.py 中有精确实现桌面构建从不设置该变量其回环边界不变服务模式下设置类、诊断类等状态变更请求必须出示长随机OMNIVOICE_API_KEY——UI 首次使用时提示输入浏览器用其换取短期会话主密钥不会持久化六位共享 PIN 只提供消费级访问不能授权管理与听写仅配置 PIN 的部署远程管理仍保持仅回环可用OMNIVOICE_TRUSTED_NETWORKS是消费级豁免绝不可单独解锁管理面/system/set-env属于 RCE 级路由。若你用自有回环认证代理前置容器可设OMNIVOICE_SERVER_MODE0重新启用严格门禁。完整访问模型见 docs/api-auth.md。安全基线回环发布是安全默认。在可信局域网暴露前务必配置OMNIVOICE_API_KEY。在任何不可信网络上明文 HTTP 对 API Key 与会话 Cookie 都不安全。请把后端放在加密的私有叠加网络如 Tailscale / ZeroTier之后不要直接暴露到公网。反代与多源场景下OMNIVOICE_PUBLIC_API_BASE必须是纯http(s)://…URL否则被忽略并回退同源。镜像内部从 Dockerfile 看构建deploy/Dockerfile 采用多阶段构建前端构建阶段oven/bun:1-alpine中bun install --frozen-lockfile后bun run --cwd frontend build产物落在frontend/dist。运行时阶段基于pytorch/pytorch:2.8.0-cuda12.8-cudnn9-runtime默认CUDA 变体CI 通过覆盖BASE_IMAGErocm/pytorch:rocm7.2.4_ubuntu24.04_py3.12_pytorch_release_2.8.0与GPU_FLAVORrocm构建 ROCm 变体issue #1165。两个基础镜像都预装 torch/torchaudio 2.8.0依赖安装会刻意保留它们。版本约束deploy/torch-constraints.txt 钉住torch2.8.0、torchaudio2.8.0、torchvision0.23.0。这是因为uv pip install会忽略项目级的 constraint-dependencies若不显式传--constraint三者会按各自下界独立解析出现 torch 升级而 torchvision 未跟随的 ABI 不匹配RuntimeError: operator torchvision::nms does not existissue #1357。版本号刻意不带本地段PEP 440 让2.8.0同时匹配2.8.0cu128与2.8.0rocm6.4一份文件同时服务 CUDA、ROCm 与 Colab。构建期守护安装后立即校验基础镜像的 GPU torch 未被替换——若未来依赖升级迫使 torch 变更构建会直接失败而不是向 AMD 用户静默交付 CUDA 构建 AMD 上纯 CPU。健康检查与入口镜像级HEALTHCHECK每 30s 请求http://127.0.0.1:3900/health起始宽限 120s因为首次启动要建库、拉模型元数据入口为python3 -m uvicorn backend.main:app。Compose 中另有各自的 healthcheck 覆盖它。功能全景镜像内开箱即用多项能力详见 dockerhub-overview.md 的 Whats inside 与 Settings 中的引擎列表语音克隆3 秒片段即可零样本复刻任意声音支持 646 种语言声音设计调节性别、年龄、口音、音高、语速、情感与方言视频配音YouTube URL 或本地文件 → 转写 → 翻译 → 重配音 → 导出 MP4有声书与长文脚本 → 规划 → 响度归一化的 M4B带章节、元数据与封面人声分离Demucs 分离人声与音乐并保留背景说话人分离Pyannote WhisperX 自动识别谁在何时说话批量队列一次丢入 50 个视频逐任务进度MCP Server可从 Claude、Cursor 或任意 MCP 客户端驱动 VoiceStudioAI 水印不可见的 AudioSealMeta标记抗压缩GPU 自动探测CUDA · ROCm · CPU显存 ≤8 GB 时自动卸载可扩展子类化TTSBackend约 50 行即可接入任意新引擎。多套 TTS 引擎IndexTTS、CosyVoice、Supertonic-3 等随镜像内置在 Settings 中自动探测并可选。启动与故障排查要点端口秒级就绪重初始化在后台容器启动后约 1 秒内端口即有响应但 PyTorch、路由、数据库迁移等重初始化在后台继续。期间/health返回503并带当前步骤GET /startup/progress返回完整的分步台账status、当前step/label、各步状态——启动看起来卡住时先看这里DockerHEALTHCHECK只在/health返回 200 后转绿。Loopback origin required 与版本号空白历史 issue #261 的症状。镜像已内置OMNIVOICE_SERVER_MODE1解决管理变更仍需OMNIVOICE_API_KEY。若用自有回环代理前置设OMNIVOICE_SERVER_MODE0重开严格门禁。GPU 未识别AMD确认拉的是:rocmtag默认镜像仅 CUDA且传了--device /dev/kfd --device /dev/dri用docker exec omnivoice rocminfo | grep -i gfx看容器是否看到显卡。消费级显卡先不加HSA_OVERRIDE_GFX_VERSION运行——后端会在需要时自行设置。版本核对见上文镜像标签语义一节的importlib.metadata//health命令Web UI 的 Settings → About → Version 从后端实时读取。更多条目见 docs/install/troubleshooting.md。小结VoiceStudio 的 Docker 镜像把全本地、无云依赖的语音引擎打包成一条可审计、可复现的部署路径docker run或 Compose profile 即可在 AMD64 主机上获得 CPU / CUDA / ROCm 三档加速回环发布 长随机 API Key 服务模式门禁构成默认安全边界OMNIVOICE_PUBLIC_API_BASE让预构建镜像也能无缝嵌入反向代理拓扑数据卷与 HF 缓存卷则让升级、重建容器都不丢配置与模型。无论是一台 8 GB 内存的 homelab 小主机还是一块 8 GB 显存的 GPU 服务器镜像都提供了对应的启动方式——唯一需要记住的前提是架构为linux/amd64。【免费下载链接】VoiceStudioVoiceStudio is the open-source, fully-local ElevenLabs alternative — voice cloning, voice design, video dubbing, dictation, transcription audiobook creation in 646 languages.项目地址: https://gitcode.com/GitHub_Trending/om/VoiceStudio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考