保留现有的 Docker 安装¶

在替换由较旧的 docker run 示例创建的容器之前，请先使用此方法。这些示例为 Hugging Face 缓存挂载了 /app/omnivoice_data，但应用程序数据可能仍保留在容器内的 /root/.omnivoice 中。删除该容器可能会删除数据库、语音、生成的音频、项目、设置和受管理的引擎。

新的安装命令现在显式使用 /app/omnivoice_data。现有安装应保留其原始的容器内路径：数据库记录、引擎环境和符号链接可能包含绝对路径。下面的步骤会将数据复制到持久化的宿主机目录，而不会移动这些路径或覆盖现有卷。

检查现有路径¶

在旧容器仍在运行时，检查其有效数据目录：

docker exec omnivoice python3 -c 'from backend.core.config import DATA_DIR; print(DATA_DIR)'
docker inspect omnivoice --format '{{json .Mounts}}'

将命令中的 omnivoice 替换为你的容器名称。以下示例针对以前的默认目录 /root/.omnivoice，其中镜像的默认 Hugging Face 缓存位于 /app/omnivoice_data/huggingface。如果有效数据目录已经是 /app/omnivoice_data，则保留其现有卷和环境设置；无需执行旧路径迁移。升级前请备份该卷。对于自定义数据、缓存或引擎目录，请备份配置中显示的每个位置，并保留其挂载目标。

在替换任何内容之前进行备份¶

首先完成正在进行的任务。选择一个宿主文件系统，使其有足够空间同时容纳备份以及数据和模型缓存的工作副本。在同一个 Bash 会话中运行以下命令，如果任何命令失败则停止：

backup_dir="$(pwd)/voicestudio-backup-$(date +%Y%m%d-%H%M%S)"
mkdir -m 700 "$backup_dir" &&
docker inspect omnivoice > "$backup_dir/container.json" &&
docker stop omnivoice &&
docker cp omnivoice:/root/.omnivoice "$backup_dir/data" &&
docker cp omnivoice:/app/omnivoice_data "$backup_dir/volume"

在容器停止后复制，可确保 SQLite 及其 WAL 文件保持一致，并防止备份期间发生写入。复制整个目录，包括隐藏文件和引擎安装。在继续之前检查两份副本。请将 container.json 保密：其中包含环境变量和凭据。不要删除旧容器、不要删除其卷，也不要运行 docker compose down -v。

使用原始路径恢复¶

保持备份原封不动，并创建工作副本。在开始替换之前，导出旧安装使用的相同 OMNIVOICE_API_KEY。

cp -a "$backup_dir/data" "$backup_dir/restored-data" &&
cp -a "$backup_dir/volume" "$backup_dir/restored-volume" &&
docker run -d --name omnivoice-migrated \
  -p 127.0.0.1:3900:3900 \
  -e OMNIVOICE_API_KEY="$OMNIVOICE_API_KEY" \
  -e OMNIVOICE_DATA_DIR=/root/.omnivoice \
  --mount "type=bind,src=$backup_dir/restored-data,dst=/root/.omnivoice" \
  --mount "type=bind,src=$backup_dir/restored-volume,dst=/app/omnivoice_data" \
  ghcr.io/debpalash/voicestudio:stable

使用与原始容器相同的 GPU 标志、镜像架构/变体和自定义环境设置；上面的命令是 CPU 示例。两个绑定挂载可保留应用程序路径和现有的 Hugging Face 缓存。对于后续升级，请保持这些相同的挂载目标和数据设置，而不要切换到全新安装的卷示例。

打开应用，验证现有的语音、项目、生成的音频、设置和已安装的模型。检查 docker logs omnivoice-migrated 是否有启动错误。在验证成功之前，请保留已停止的原始容器和未动过的备份。如果验证失败，请停止 omnivoice-migrated 并重新启动 omnivoice；旧容器及其卷尚未被删除或覆盖。