StemDeck 详细部署教程

1. 部署方式概览

StemDeck 是一款本地运行的分轨（stem separation）工具，可将音频拆分为最多 6 条音轨（人声、鼓、贝斯、吉他、钢琴、其他）。它支持多种部署方式，选择取决于你的使用场景：

部署方式 适用场景 难度 推荐度
桌面安装包 个人日常使用、不想折腾 ⭐ ⭐⭐⭐⭐⭐
Docker 部署 服务器/NAS、多设备访问 ⭐⭐⭐ ⭐⭐⭐⭐
源码运行（Web 服务器） 开发、自定义配置 ⭐⭐⭐ ⭐⭐⭐
Unraid Unraid NAS 用户 ⭐⭐ ⭐⭐⭐⭐

重要定位说明：StemDeck 是分轨工具，不是下载器。它的主要用途是处理你已拥有的音频。YouTube 支持只是便利功能，且不存储、不缓存、不再分发任何下载内容。所有处理都在本地完成。

2. 桌面安装包部署（最简单）

2.1 macOS

从 GitHub Releases 下载对应芯片的 DMG：

DMG 文件 GPU 芯片
StemDeck-macOS-arm64.dmg Apple Silicon (MPS) M1 及更新
StemDeck-macOS-x64.dmg 仅 CPU Intel

安装步骤：

  1. 打开 DMG，将 StemDeck 拖入 Applications 文件夹。
  2. 首次启动时，设置界面会下载 Python 运行时（约 500 MB）、FFmpeg 和 Demucs 模型（约 170 MB）。
  3. 后续启动跳过设置，几秒内即可启动。无需预装 Python 或任何系统依赖。

⚠️ Gatekeeper 提示：macOS 可能首次打开时弹出安全警告。右键点击应用 → 选择「打开」 即可绕过。

2.2 Windows

从 GitHub Releases 下载对应 zip：

Zip 文件 GPU 大小
StemDeck-Windows-x64.zip 仅 CPU ~700 MB
StemDeck-Windows-x64.NVIDIA.zip NVIDIA CUDA ~1.6 GB

安装步骤：

  1. 解压到任意位置，运行 StemDeck.exe。
  2. FFmpeg、Demucs 模型、配置和日志存放在 StemDeck.exe 同级的 data/ 文件夹中，而非 AppData。因此整个文件夹可以任意移动或复制。
  3. 首次启动会验证内置 Python 运行时，并下载 FFmpeg 和 Demucs 模型（~170 MB）到该文件夹。
  4. 作业/库数据默认存放在 ~/Documents/StemDeck，可在「Settings → StemData location」随时重定位。

3. Docker 部署（推荐用于服务器/NAS）

Docker 是服务器或多设备访问场景的首选方式。

3.1 环境要求

  • Docker 和 Docker Compose
  • 约 170 MB 磁盘空间用于 Demucs 模型（首次运行自动下载）
  • 注意：macOS 上的 Docker 不支持 GPU 直通

3.2 使用 Compose 构建

1
docker compose -f build/docker-compose.yml up --build

分轨结果输出到宿主机的 ./jobs/ 目录。Demucs 权重缓存在命名卷中，重建时不会重新下载。

3.3 使用预构建镜像（GHCR）

StemDeck 在 GHCR 上发布了预构建镜像，标签含义：

标签 说明
edge 滚动更新，每次合并到 main 时重建
latest 最新稳定版本
X.Y.Z 固定到具体版本

基础运行命令：

1
2
3
4
5
docker run -d --name stemdeck -p 8000:8000 \
  -v /path/to/jobs:/app/jobs \
  -v /path/to/cache:/cache \
  -e STEMDECK_PERSIST_LIBRARY=1 \
  ghcr.io/stemdeckapp/stemdeck:edge

💡 关键点：STEMDECK_PERSIST_LIBRARY=1 确保曲库持久化，轨道永不自动删除。未设置此项时，作业目录会在 TTL（默认 24 小时）后被清理。

3.4 NVIDIA GPU 加速（Linux 宿主机）

在已安装驱动和 NVIDIA Container Toolkit 的 Linux 宿主机上，添加以下参数：

1
2
3
4
5
6
docker run -d --name stemdeck -p 8000:8000 \
  --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=all \
  -v /path/to/jobs:/app/jobs \
  -v /path/to/cache:/cache \
  -e STEMDECK_PERSIST_LIBRARY=1 \
  ghcr.io/stemdeckapp/stemdeck:edge

镜像已内置 CUDA 版 torch，无需单独安装 CUDA。StemDeck 会自动检测并使用 CUDA。

3.5 访问服务

打开 http://localhost:8000。

⚠️ 重要——远程访问必须使用 HTTPS：

StemDeck 的移调（Transpose）功能基于 AudioWorklet，浏览器只在安全上下文（secure context）下授予该 API。https:// 和 localhost 符合条件，而普通的 http://192.168.1.20:8000 不符合。这意味着通过明文 HTTP 从手机访问时，播放正常但移调控件会灰显无法使用。

从非本地地址访问且未配置 TLS 时，服务会返回 403 并给出说明，而不是提供一个”静默半损坏”的应用。回环地址（localhost）始终可用，因此开启此限制不会把宿主机锁在自己的服务器之外。

三种获取安全上下文的方式（按省力程度排序）：

  1. SSH 隧道到 localhost（最省力）：

    1
    ssh -N -L 8000:localhost:8000 user@host

    然后在客户端打开 http://localhost:8000。此时源是 localhost，包括移调在内的所有功能均可用。

  2. Tailscale Serve：在宿主机执行 tailscale serve 8000，通过真实 HTTPS 在 tailnet 上发布 StemDeck，无需警告、客户端除 Tailscale 外无需安装任何东西。注意：纯 Tailscale IP（100.x.y.z）不是安全上下文，必须通过 serve 走。

  3. 任意 HTTPS 反向代理：Caddy、nginx，或 Cloudflare Tunnel 之类的隧道。StemDeck 会读取 X-Forwarded-Proto 和 RFC 7239 的 Forwarded 头，因此 https 浏览器经明文 http 上游跳转也能被正确识别为安全。

3.6 让 StemDeck 自身提供 HTTPS

若不想额外部署反向代理，可让 StemDeck 直接终止 TLS。设置以下两个变量指向证书和私钥：

1
2
-e STEMDECK_SSL_CERT=/path/to/cert.pem \
-e STEMDECK_SSL_KEY=/path/to/key.pem \

uvicorn 会直接提供服务，无需安装额外包。

4. Unraid 部署

StemDeck 已上架 Unraid Community Applications。

安装步骤：

  1. 打开 Apps，搜索 “StemDeck”，安装。
  2. 映射两个卷到持久化 appdata 路径：
    • /app/jobs → /mnt/user/appdata/stemdeck/jobs（曲库 + 分轨）
    • /cache → /mnt/user/appdata/stemdeck/cache（模型权重）
  3. 曲库默认持久化（STEMDECK_PERSIST_LIBRARY=1），轨道永不自动删除。
  4. GPU 加速：安装 Nvidia Driver 插件，然后将容器的 Extra Parameters 设为 --runtime=nvidia（模板中已包含 NVIDIA_VISIBLE_DEVICES 和 NVIDIA_DRIVER_CAPABILITIES 变量）。仅 CPU 模式无需任何额外配置。

5. 源码运行（Web 服务器）

适用于 macOS / Linux / Windows（需 Python 3.12+）。

5.1 前置要求

  • Python 3.12 或更新
  • ffmpeg 在 PATH 中
  • uv
  • 约 170 MB 空闲磁盘用于 Demucs 模型（首次运行自动下载）

5.2 macOS / Linux（一键脚本）

1
2
3
git clone https://github.com/stemdeckapp/stemdeck stemdeck && cd stemdeck
./run.sh setup     # 安装 ffmpeg + uv，并执行 uv sync
./run.sh start

打开 http://localhost:8000。

setup 在 macOS 上使用 Homebrew，在 Debian/Ubuntu 上使用 apt-get。其他 Linux 发行版需手动安装 ffmpeg 和 uv，然后执行 uv sync 和 ./run.sh start。

5.3 Windows（PowerShell）

安装前置依赖：

1
2
3
4
5
# uv
winget install astral-sh.uv
# ffmpeg
winget install Gyan.FFmpeg
# 或使用 Chocolatey: choco install ffmpeg

启动：

1
2
3
git clone https://github.com/stemdeckapp/stemdeck stemdeck; cd stemdeck
uv sync
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --timeout-graceful-shutdown 5

打开 http://localhost:8000。

run.sh 仅适用于 macOS/Linux。Windows 请使用上述 PowerShell 命令，或在 WSL 中运行。

5.4 NVIDIA GPU (CUDA) 配置

启动前安装 CUDA 版 torch：

1
2
3
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
$env:STEMDECK_DEMUCS_DEVICE = "cuda"
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --timeout-graceful-shutdown 5

5.5 手动运行（任意平台）

1
2
3
git clone https://github.com/stemdeckapp/stemdeck stemdeck && cd stemdeck
uv sync
uv run uvicorn app.main:app --reload --timeout-graceful-shutdown 5

关于 --timeout-graceful-shutdown：此参数限制 uvicorn 停止时等待开放连接的时间。StemDeck 在浏览器标签页打开期间会为导入队列保持一条长生命周期的 SSE 流。若不设置此参数，Ctrl-C 会一直等待该流关闭而无法退出。

5.6 run.sh 控制脚本

1
2
3
4
5
./run.sh setup      # 一次性：安装 ffmpeg + uv，然后 uv sync
./run.sh start      # 后台启动 uvicorn
./run.sh stop       # 优雅关闭
./run.sh restart    # 重启
./run.sh status     # 查看运行状态

run.sh 还读取以下环境变量：HOST（默认 127.0.0.1）、PORT（默认 8765）、RELOAD=1（开发时启用自动重载）、FOREGROUND=1（前台运行而非后台）。

6. 关键配置变量

变量 默认值 用途
STEMDECK_DEMUCS_DEVICE auto 强制 Torch 设备：cuda、mps 或 cpu
STEMDECK_DEMUCS_MODEL htdemucs_6s Demucs 模型名称
STEMDECK_JOBS_DIR ./jobs 作业目录位置
STEMDECK_DATA_DIR (无) 便携模式根目录；设置后以下所有子目录都在其中
STEMDECK_CACHE_DIR <data>/cache Torch 模型缓存目录
STEMDECK_MODELS_DIR <data>/models Demucs 模型权重目录
STEMDECK_PERSIST_LIBRARY (无) 设为 1 使曲库持久化，轨道不自动删除
STEMDECK_MAX_DURATION_SEC 1200 拒绝超过此时长（秒）的音频
STEMDECK_JOB_TTL_SECONDS 86400 作业目录在磁盘上保留的时长
STEMDECK_MAX_PENDING_JOBS 3 队列中最多作业数，超出返回 503
STEMDECK_SSL_CERT (无) PEM 证书；配合下面的密钥可直接提供 https
STEMDECK_SSL_KEY (无) 上述证书的 PEM 私钥
STEMDECK_HTTPS_PORT (无) 在主监听器之外额外提供 https 的端口

7. 常见问题排查

ffmpeg: command not found
安装 ffmpeg 后执行 ./run.sh restart 重启。

WARNING: [youtube] No supported JavaScript runtime
安装 deno（macOS 上 brew install deno）并重启。不装也能下载，但可能选到次优格式。

首次分轨非常慢
Demucs 首次运行会下载 htdemucs_6s 权重（~170 MB），之后会缓存。

Demucs 只在 CPU 上运行
检查启动日志中的 device=mps 或 device=cuda。如果看到 cpu，说明你的 torch 安装可能是 CPU-only 版本。

在另一台机器上移调（Transpose）灰显
这是设计如此，非 bug。移调基于 AudioWorklet，浏览器只在安全上下文暴露该 API。https:// 和 localhost 符合，普通的 http://192.168.x.x 不符合。解决方案见 3.5 节（SSH 隧道、Tailscale Serve 或 HTTPS 反向代理）。

页面在作业中途刷新
作业会在服务端继续运行。等它完成后重新提交即可。注意作业状态存储在内存中，重启服务器会重置作业列表，但文件仍保留在磁盘上。

./run.sh: Permission denied
执行 chmod +x run.sh。

8. 磁盘布局与数据管理

text

1
2
3
4
5
6
7
8
9
10
jobs/<job_id>/
└── stems/
    ├── vocals.wav      # 6 条 Demucs 分轨（始终存在）
    ├── drums.wav
    ├── bass.wav
    ├── guitar.wav
    ├── piano.wav
    ├── other.wav
    ├── original.wav    # 未选中分轨之和（仅子集提取时）
    └── mix.wav         # 选中分轨的 ffmpeg amix 混音（仅子集提取时）

注意：作业状态在内存中。重启服务器后作业列表重置，但文件持久保留在磁盘上。旧目录会按 TTL（默认 24 小时，可配置）自动清理——除非设置了 STEMDECK_PERSIST_LIBRARY=1。

9. 使用流程速览

  1. 在导入栏点击 stem 芯片，选择要提取的分轨（默认全选 6 条）。
  2. 粘贴 YouTube URL 或拖入音频文件（MP3、WAV、FLAC、OGG、MP4、M4A），然后点击 Process。
  3. 等待 Uploading... / Downloading... → Analyzing... → Separating... → Mixing tracks...。
  4. 完成后进入工作室仪表板。若选了子集，第一条泳道是 Original（整首歌减去你的选择），其余是分离出的分轨。
  5. 混音：M 静音、S 独奏（叠加，多个独奏仍可听）、Monitor 只独奏该分轨并清除其他。音量推子 1:1 跟随拖动；双击重置为 0 dB；Shift+滚轮 粗调，普通滚轮细调。
  6. 在标尺上拖动定义循环区域；点击 Loop 启用。用 + / - / Fit 或 Ctrl/Cmd+滚轮 缩放。
  7. 页脚的 Download Mix 导出你选中分轨混音后的 WAV。

键盘快捷键：Space 播放/暂停 · [ 后退 5 秒 · ] 前进 5 秒 · L 循环 · I 循环入点 · O 循环出点

10. 法律与合规提醒

  • YouTube URL 支持通过 yt-dlp 提供，仅为便利功能。自动下载可能违反 YouTube 服务条款。
  • 你（用户）独自负责确保有权处理所提交的任何音频、遵守所下载站点的服务条款，并尊重所处理材料的版权。
  • StemDeck 不存储、缓存或再分发任何音频内容。所有处理均在用户自己的机器上运行，音频不传输到任何地方。
  • 软件按 “as is” 提供，作者不承担任何使用责任。

11. 部署方式选择建议

你的情况 推荐方式
个人电脑日常使用，不想折腾 桌面安装包（macOS DMG / Windows zip）
服务器/NAS，多设备访问 Docker + 反向代理 HTTPS
Unraid 用户 Unraid Community Applications
有 NVIDIA GPU 的 Linux 服务器 Docker + --runtime=nvidia
需要自定义或参与开发 源码运行 + --reload

核心要点：无论哪种方式，若要从非 localhost 地址访问，必须配置 HTTPS，否则移调功能将不可用。这是浏览器的安全上下文限制，不是 StemDeck 的缺陷。