企业官网建设流程全解析

Voicebox 安装与首次启动指南：4 条路线、4 个环节，排到能出声为止

【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox

Voicebox 是一款本地优先的开源 AI 语音工作室，支持声音克隆、语音生成和全局听写。这篇 Voicebox 安装指南带你走完 macOS 到 Docker 共 4 条安装路线，并按由外到内的 4 个环节排查首次启动红灯、模型下载卡住、GPU 不生效的问题，目标是装完就能生成第一段语音。

动手前：机器要达到的两个数字

桌面端最低要求 macOS 11+ 或 Windows 10+，8GB 内存，5GB 可用磁盘。想跑得舒服：16GB+ 内存，一张 NVIDIA GPU（生成语音至少吃 6GB 显存）。机器不达标不会装不上，只是生成的时候慢或者 OOM。

选路线看场景，对号入座：

• 个人 Mac（Apple Silicon 或 Intel）：装 DMG 安装包，双击运行。
• 个人 Windows 电脑：装 MSI/Setup 安装包，按向导点下一步。
• Linux 日常使用机：没有官方预编译包，走源码构建，just两条命令搞定。
• 无头服务器、多用户共享 GPU：走 Docker，起容器后用浏览器访问，不用装桌面端。

四条路线的最小步骤

macOS：拖进去就完

下载 DMG，把Voicebox.app拖进/Applications。首次启动若弹出"已损坏"，别移废纸篓，跳到下面第 1 环节处理。

Windows：跟着向导走

双击安装程序，一路 Next。首次运行被 SmartScreen 蓝屏拦住属正常现象，处理方式见第 1 环节。

Linux：两条命令构建

先装好 Git、Rust、just（cargo install just）、Bun 和 Tauri 系统依赖，然后：

git clone https://gitcode.com/GitHub_Trending/voicebox1/voicebox cd voicebox just setup # 建 Python venv 并装全部依赖 just build # 构建桌面应用

构建产物在tauri/src-tauri/target/release/bundle/。全部命令定义在 justfile，跑just --list可查完整清单。如果你手上已经有别人给的 AppImage 却提示"权限被拒绝"，先补一句：

chmod +x voicebox-*.AppImage

Docker：给无头服务器

docker compose up --build

首次构建要几分钟（编译前端 + 装 Python 依赖），之后启动秒开。起好后浏览器打开http://127.0.0.1:17600（docker-compose.yml 里默认的宿主机端口映射，容器内部端口是 17493，想改端口直接改ports一行）。

首次启动排障：由外到内 4 个环节

新装出问题的概率集中在系统层，而不是模型层。按下面顺序排查，前一个环节没排除再进下一个。

第 1 环节：系统说"已损坏"、SmartScreen 说"已保护"

现象：macOS 双击弹"应用已损坏，无法打开"；Windows 首次运行弹 SmartScreen 蓝屏"已保护你的电脑"。

判断：Voicebox 没用 Apple 开发者证书签名，系统自动打了隔离属性，Windows 侧同理是无代码签名应用的默认拦截。不是真的坏了，不用重装。

动作：

xattr -cr /Applications/Voicebox.app

macOS 一行解决，再双击即可。Windows 点"更多信息"→"仍要运行"，10 秒完事，不用改任何系统设置。如果你的系统没弹任何拦截提示，这个环节直接跳过。

第 2 环节：状态灯红灯，"Failed to connect to server" 怎么查

现象：应用能打开，左下角服务器状态指示器一直红色，提示 "Failed to connect to server"。

判断：后端是随应用启动的 FastAPI 服务，监听 17493 端口。红灯 9 成是端口被占或后端二进制没执行权限，先查端口：

# macOS / Linux lsof -i :17493

# Windows powershell -Command "Get-NetTCPConnection -LocalPort 17493 -State Listen"

查到占用进程就kill -9 <PID>（Windows 用taskkill /PID <PID> /F）再重启应用。没占用的话，查后端二进制的执行权限（macOS/Linux）：

chmod +x ~/Library/Application\ Support/sh.voicebox.app/backend/voicebox-server

还不行就看日志找真因：macOS 跑tail -f ~/Library/Application\ Support/sh.voicebox.app/logs/server.log，Windows 打开%APPDATA%\sh.voicebox.app\logs\server.log。

💡 日志里出现flash-attn is not installed警告直接忽略：它是可选加速库，缺省时 PyTorch 自动退回 SDPA 注意力，速度几乎无损。

第 3 环节：模型下载卡住，或首次生成要等好几分钟

现象：点生成后进度条停在 "Loading model..." / "Downloading..."，长时间不动。

判断：这不是故障——首次生成会自动下载所选引擎的模型，Kokoro 约 350 MB，TADA 3B 约 8 GB，网络不好的时候体验自然差。

动作：先切到 Settings → Models 看真实进度；带宽有限就先选 Kokoro（~350 MB）或 LuxTTS（~300 MB）起步。卡死在 HuggingFace Hub 的话，走代理或手动把模型下到缓存目录：

pip install huggingface_hub huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base

缓存目录默认是 HuggingFace 标准缓存，可用环境变量VOICEBOX_MODELS_DIR自定义。Docker 用户如果发现"每次重启都重新下载模型"，检查huggingface-cache这个命名卷是否还保留着，docs/content/docs/overview/docker.mdx 里有卷的持久化说明。

第 4 环节：CUDA out of memory，或 GPU 加速不生效

现象：生成时报CUDA out of memory；或者明明有 GPU，生成速度却跟纯 CPU 一样。

判断：一次生成需要 6GB+ 显存，先排除显存不够；排除后再看后端类型是否跟机器匹配。

动作：

1. 关掉游戏、视频编辑这类吃显存的应用，重启 Voicebox；
2. 仍 OOM：Settings → Generation 切到 CPU 模式，速度慢 5-10 倍但改用系统内存，小模型下依然可用；
3. 核对后端：打开 Settings → Server Status，Apple Silicon 应显示Backend: MLX（比 PyTorch 快 4-5 倍）。若显示 PYTORCH，在应用 venv 里执行pip install -r backend/requirements-mlx.txt重装；Windows 用户到 GPU 面板确认 CUDA 后端已安装；
4. 多显卡机器：Settings → Generation → GPU Device 手动选对显卡。

各平台后端对照、RTX 50 系与 Intel Arc 的细节见 docs/content/docs/overview/gpu-acceleration.mdx。

60 秒验证：装完到底成功没有

三步确认，走完这条线安装就算闭环：

1. 启动应用，左下角状态灯变绿 🟢；
2. 进 Voices 页，Create Voice，上传或录制一段 10-30 秒的清晰人声做档案；
3. 在 Generate 页输入一句话并生成，能听到声音即安装成功 🎉

顺带记住数据目录：你的语音档案、生成音频都放在 macOS~/Library/Application Support/sh.voicebox.app/、Windows%APPDATA%\sh.voicebox.app\、Linux~/.config/sh.voicebox.app/，以后备份或迁移就认这个目录。

排障速查表

更多症状（数据库锁、损坏恢复、远程模式连接）收录在 docs/content/docs/overview/troubleshooting.mdx；源码构建时装依赖报版本冲突，对照 backend/requirements.txt 里的依赖清单检查。

【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox