Docker、启动脚本与部署参数

本页说明 Applio 仓库中用于容器化构建、GPU 部署和本地启动的 Docker 配置与启动脚本。内容聚焦 Dockerfile、Dockerfile_cuda、docker-compose.yaml 以及 run-applio.sh 所表达的部署边界；应用内部的业务模块、模型推理流程和完整安装流程不在本页展开。

Purpose and Scope

本页覆盖以下端到端部署信息：

Dockerfile 的基础镜像、系统依赖、Python 虚拟环境、PyTorch 安装、持久化卷和默认入口。
Dockerfile_cuda 的 NVIDIA CUDA 基础镜像、系统库、源码获取、虚拟环境与启动方式。
docker-compose.yaml 如何选择 Dockerfile、发布端口并请求一块 NVIDIA GPU。
run-applio.sh 如何设置 Apple Metal 相关环境变量并把参数传给 app.py。

本页不推断 app.py 未在已读取源码中展示的参数默认值，也不把 Compose 配置扩展为完整生产编排方案。若需要了解应用 UI、推理服务或业务参数，请参阅对应的应用功能页面；若需要了解通用依赖安装逻辑，请参阅安装相关文档。

Overview

仓库提供两条容器构建路径：

Dockerfile 以 python:3.12-trixie 为基础，在镜像内复制当前构建上下文，并创建 /app/.venv。它显式安装 ffmpeg、libportaudio2、python-ffmpeg 以及 PyTorch CUDA 12.8 wheel，最后用 python3 app.py --server-name 0.0.0.0 --port 6969 启动。
Dockerfile_cuda 直接基于 nvidia/cuda:12.8.1-cudnn-devel-ubuntu24.04，安装 Python、Git、OpenGL/GLib、FFmpeg 和 PortAudio，然后在构建阶段从 GitHub 克隆 Applio，再安装依赖。它的默认命令使用虚拟环境 Python，并只显式传入 --server-name 0.0.0.0。

Compose 文件选择第一条路径，而不是 Dockerfile_cuda：其 build.dockerfile 明确为 Dockerfile。同时，Compose 通过 deploy.resources.reservations.devices 声明 NVIDIA 设备需求，因此“使用哪一个 Dockerfile”和“运行时请求 GPU”是两个分别配置的决策。

Architecture

Loading diagram...

Source: Dockerfile Source: Dockerfile_cuda Source: docker-compose.yaml

图中的两条镜像路径来自两个独立 Dockerfile：普通文件复制本地上下文，CUDA 文件在构建阶段克隆远程仓库。Compose 只连接到 Dockerfile，因此 Dockerfile_cuda 需要被单独选择或直接构建，不能假定 Compose 会自动使用它。

Dockerfile 构建路径

基础镜像与系统依赖

Dockerfile 使用 Python 3.12 trixie 镜像，并将工作目录固定为 /app。构建阶段通过 APT 安装 ffmpeg 和 libportaudio2，之后清理 APT 列表。这种顺序的直接效果是运行时具备音视频处理和 PortAudio 动态库，同时删除 /var/lib/apt/lists 以减少镜像残留。

Python 环境与依赖安装

镜像在 /app/.venv 创建虚拟环境，并在激活该环境的同一条 RUN 指令中升级 pip、安装 python-ffmpeg、安装指定版本 PyTorch/torchvision/torchaudio，最后仅在 requirements.txt 存在时安装该文件。因为后续设置了 PATH=/app/.venv/bin:$PATH，入口中的 python3 会优先解析到该虚拟环境中的解释器。

下面是仓库中的实际安装片段：

dockerfile

RUN python3 -m venv /app/.venv && \\
    . /app/.venv/bin/activate && \\
    pip install --no-cache-dir --upgrade pip && \\
    pip install --no-cache-dir python-ffmpeg && \\
    pip install --no-cache-dir torch==2.7.1 torchvision torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu128 && \\
    if [ -f "requirements.txt" ]; then pip install --no-cache-dir -r requirements.txt; fi

Source: Dockerfile

这里的 if [ -f "requirements.txt" ] 使 Dockerfile 在缺少该文件时仍可继续构建；但这并不表示应用依赖已经完整安装，依赖是否充分仍取决于镜像上下文中的文件和预装包。

入口、端口与日志卷

Dockerfile 声明 /app/logs/ 为卷，并通过 ENTRYPOINT ["python3"] 固定执行解释器，再由 CMD 提供应用脚本及网络参数。CMD 可在容器启动时被覆盖，而 ENTRYPOINT 仍会保留 Python 解释器这一执行边界。

dockerfile

VOLUME ["/app/logs/"]

ENV PATH="/app/.venv/bin:$PATH"

ENTRYPOINT ["python3"]
CMD ["app.py", "--server-name", "0.0.0.0", "--port", "6969"]

Source: Dockerfile

需要注意的是，Dockerfile 只声明了容器端口 6969；实际主机端口映射由运行命令或 Compose 决定。不要把 EXPOSE 当作主机端口发布规则。

CUDA 专用构建路径

Dockerfile_cuda 与普通 Dockerfile 的关键差异不只是镜像名称：它还改变了源码进入镜像的方式和最终启动解释器。

基础镜像为 nvidia/cuda:12.8.1-cudnn-devel-ubuntu24.04。
系统包包含 python3、python3-venv、python3-pip、git、libgl1、libglib2.0-0、ffmpeg 和 libportaudio2。
构建阶段执行 git clone https://github.com/IAHispano/Applio.git .，因此该路径不是复制调用方本地上下文，而是从远程仓库获取源代码。
依赖安装使用 .venv/bin/pip，并重复使用 CUDA 12.8 对应的 PyTorch 索引。
运行命令使用 .venv/bin/python app.py --server-name 0.0.0.0，没有在该文件中显式写出 --port 6969。

dockerfile

FROM docker.io/nvidia/cuda:12.8.1-cudnn-devel-ubuntu24.04

ENV DEBIAN_FRONTEND=noninteractive

WORKDIR /app

RUN apt update && apt install -y \\
    python3 \\
    python3-venv \\
    python3-pip \\
    git \\
    libgl1 \\
    libglib2.0-0 \\
    ffmpeg \\
    libportaudio2

Source: Dockerfile_cuda

dockerfile

RUN git clone https://github.com/IAHispano/Applio.git .

RUN python3 -m venv .venv

RUN .venv/bin/pip install --no-cache-dir --upgrade pip
RUN .venv/bin/pip install --no-cache-dir python-ffmpeg

RUN .venv/bin/pip install --no-cache-dir torch==2.7.1 torchvision torchaudio==2.7.1 --index-url https://download.pytorch.org/whl/cu128

RUN .venv/bin/pip install --no-cache-dir -r requirements.txt

Source: Dockerfile_cuda

这条路径的设计意图是把 CUDA runtime/development 用户态库和应用环境放在同一个 NVIDIA 基础镜像中，并使用 CUDA 对应的 PyTorch wheel。由于源码来源是构建时的远程 clone，构建可复现性还依赖远程仓库在构建时的内容；已读取源码中没有 commit 固定或版本参数，因此本页不宣称它具备 commit 级别的可重复构建保证。

Compose 部署参数

Compose 服务名为 applio，构建上下文是当前目录，Dockerfile 明确选择 Dockerfile。设备预留部分声明 NVIDIA driver、数量为 1，并要求 gpu capability。

yaml

version: '1'

services:
  applio:
    build:
      context: ./
      dockerfile: Dockerfile
    ports:
      - "6969"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

Source: docker-compose.yaml

参数	类型	当前值	作用
`services.applio.build.context`	路径	`./`	将当前目录作为构建上下文。
`services.applio.build.dockerfile`	文件名	`Dockerfile`	选择普通 Dockerfile，而不是 `Dockerfile_cuda`。
`services.applio.ports`	字符串列表	`"6969"`	为 Compose 服务声明 6969 端口；源码没有写出固定的主机端口映射。
`deploy.resources.reservations.devices[].driver`	字符串	`nvidia`	指定 GPU 设备驱动。
`deploy.resources.reservations.devices[].count`	数字	`1`	请求一块 GPU。
`deploy.resources.reservations.devices[].capabilities`	列表	`[gpu]`	将设备能力标记为 GPU。

Compose 启动关系

Loading diagram...

Source: docker-compose.yaml Source: Dockerfile Source: Dockerfile

该图只表示源码明确表达的依赖关系：Compose 选择普通 Dockerfile，服务请求 GPU，容器通过 Dockerfile 的默认命令启动应用。它不推断宿主机 NVIDIA 驱动安装方式，也不推断 deploy 在所有 Compose 运行模式下的具体实现差异。

本地启动脚本

run-applio.sh 是宿主机启动辅助脚本，不是 Docker entrypoint。已读取到的关键行为有两项：它设置 PyTorch 在 Apple Metal 后端不可用时的 fallback，并把 --open 及脚本收到的所有参数传递给 app.py。

bash

export PYTORCH_ENABLE_MPS_FALLBACK=1
export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0
python app.py --open "$@"

Source: run-applio.sh

这条路径与容器路径的边界很清楚：Dockerfile 通过 --server-name 0.0.0.0 让容器内服务对外监听，而脚本通过 --open 启动本地应用并保留调用方参数。已读取源码没有显示脚本中的依赖安装、端口转发或容器调用，因此不能把它描述为 Docker 启动器。

Core Flow

Loading diagram...

Source: run-applio.sh Source: Dockerfile Source: Dockerfile_cuda Source: docker-compose.yaml

API 与启动参数参考

这里的“API”是部署入口参数，而不是应用内部 Python API。源码明确给出的参数如下：

入口	参数	来源	说明
`Dockerfile` 的 `CMD`	`--server-name 0.0.0.0`	Dockerfile	传给 `app.py`，使服务绑定到容器可访问地址。
`Dockerfile` 的 `CMD`	`--port 6969`	Dockerfile	传给 `app.py`，与 Dockerfile 的 `EXPOSE 6969` 对齐。
`Dockerfile_cuda` 的 `CMD`	`--server-name 0.0.0.0`	Dockerfile_cuda	CUDA 路径显式设置服务地址，但未在该文件中显式设置端口。
`run-applio.sh`	`--open`	run-applio.sh	本地脚本固定传给 `app.py`。
`run-applio.sh`	`"$@"`	run-applio.sh	将调用脚本时的额外参数原样转发。

除上述字符串外，应用参数的合法值、默认值、异常类型和返回行为需要查看 app.py 的 argparse 定义；本页不对未读取的实现作推断。

Failure Modes、边界与并发

构建失败边界

Dockerfile 的系统依赖安装依赖 Debian APT 可用性；ffmpeg 或 libportaudio2 安装失败会使镜像构建失败。
两个 Dockerfile 都依赖 PyTorch CUDA 12.8 wheel 索引；索引不可用或版本不兼容时，依赖安装阶段会失败。
Dockerfile_cuda 无条件执行 git clone 和 pip install -r requirements.txt。相较普通 Dockerfile 的条件安装，CUDA 路径对远程仓库和 requirements 文件的存在有更强前置要求。
Dockerfile_cuda 在源码中未固定 clone 的 commit；因此远程仓库变化可能导致后续构建结果变化。

运行时边界

普通镜像把日志路径声明为 /app/logs/ 卷；已读取 Compose 文件没有把该卷显式绑定到宿主机目录，因此持久化行为取决于实际运行命令或额外 Compose 配置。
Dockerfile 的应用端口固定写入 6969，而 Compose 使用 "6969" 而非显式的 HOST:CONTAINER 形式。部署时应检查实际端口发布结果，而不是仅依据 EXPOSE 判断宿主机端口。
GPU 资源只在 Compose 的设备预留中明确声明；普通 Dockerfile 本身没有 --gpus 参数。GPU 是否可用还取决于宿主机 NVIDIA 运行时环境，这部分在已读取源码中没有实现。
两个 Dockerfile 的启动参数并不完全一致：CUDA 路径没有显式 --port 6969。应用自身是否提供相同默认端口，当前证据不足。

并发与扩展

已读取的部署文件没有实现 worker 数量、队列、锁、重试或多进程配置；因此不能从这些文件推导并发模型。扩展部署时，优先通过独立 Dockerfile、Compose override 或命令覆盖来改变镜像/入口，而不要假设 run-applio.sh 会参与容器生命周期。

Performance / Operational Notes

两个 Dockerfile 都使用 --no-cache-dir 安装 Python 包，减少 pip 缓存进入镜像层。
普通 Dockerfile 在 APT 安装后清理 /var/lib/apt/lists；CUDA Dockerfile 也在系统包安装后删除该目录。
PyTorch 安装被放在 requirements 安装之前，并使用 CUDA 12.8 wheel index；这使核心深度学习依赖的来源显式化，但也使构建依赖外部 wheel 服务。
Dockerfile_cuda 使用 cudnn-devel 基础镜像，而不是运行时镜像；这意味着其镜像职责包含开发工具链，镜像体积和构建能力应在部署时单独评估。源码没有提供体积或启动耗时数据，因此不作量化结论。

Dockerfile：本地上下文构建路径、容器端口和默认入口。
Dockerfile_cuda：NVIDIA CUDA 专用构建路径。
docker-compose.yaml：服务构建选择、端口声明和 GPU 设备预留。
run-applio.sh：本地 MPS fallback 与应用启动参数转发。

Docker、启动脚本与部署参数

Purpose and Scope

Overview

Architecture

Dockerfile 构建路径

基础镜像与系统依赖

Python 环境与依赖安装

入口、端口与日志卷

CUDA 专用构建路径

Compose 部署参数

Compose 启动关系

本地启动脚本

Core Flow

API 与启动参数参考

Failure Modes、边界与并发

构建失败边界

运行时边界

并发与扩展

Performance / Operational Notes

Related Links

Sources