fix(docker): 默认 HF_ENDPOINT 改回 huggingface.co + whisper 模型缓存独立卷

[EricWang1358]

改动概述

ix(docker): Dockerfile / docker-compose 默认 HF_ENDPOINT 从 https://hf-mirror.com 改回 https://huggingface.co;Whisper 模型缓存独立命名卷持久化。

为什么

Part of #417(Docker 部署下 Whisper 模型下载失败)。

• hf-mirror.com 是中国大陆的 HuggingFace 镜像,境外网络常不可达,这次报错的用户就是有 VPN 仍命中;
• 同时 whisper.py 顶部注释「HF_ENDPOINT 已经在 Dockerfile 里指到 huggingface.co」与 Dockerfile 实际值自相矛盾,改回 huggingface.co 即可消除这个文档偏差;
• 容器重建时 /app/models/whisper 是匿名卷,会随容器销毁而消失,常见「重 build 一次又得等半小时下模型」的体验问题。

做了什么

• Dockerfile / Dockerfile.gpu / Dockerfile.complete (3 处): 默认 ENV HF_ENDPOINT 从 https://hf-mirror.com 改为 https://huggingface.co。
• docker-compose.yml / docker-compose.gpu.yml (2 处):
  • 在 �ackend 服务的 environment 中显式设 HF_ENDPOINT=https://huggingface.co,避免被外部 .env 残留值污染;
  • 新增 named volume whisper-models 挂载到 /app/models/whisper,容器重建保留已下载的 Whisper / Faster-Whisper 模型。
• �ackend/app/transcriber/whisper.py 顶部说明注释同步更新(hf-mirror.com → huggingface.co),与代码一致。
• CHANGELOG.md: 新增 [Unreleased] / Fixed 段。

测试方式

• 手动构建验证:docker-compose build backend 成功,容器内 env | grep HF_ENDPOINT 输出 HF_ENDPOINT=https://huggingface.co。
• 命名卷验证:docker volume ls | grep whisper-models 出现,容器内 ls /app/models/whisper 看到 models--Systran--faster-whisper-* 目录。
• 镜像下载验证:选择 Whisper small 模型,首容器下载后,docker-compose down && docker-compose up -d 重建,模型不应被重新下载。
• 国内用户兼容:HF_ENDPOINT=https://hf-mirror.com 写入 .env 后,docker-compose up -d 启动的容器内 HF_ENDPOINT 应显示 https://hf-mirror.com(环境变量优先级高于 Dockerfile 内 ENV)。

回归风险

• 影响面:Docker 构建配置、命名卷,运行时无变更。普通用户使用 docker-compose up -d 命令一致;Python 代码无任何变更。
• 行为变化:默认 HuggingFace 端点改变。国内用户首次升级后 Whisper 模型下载可能变慢或失败——缓解方法已写入 CHANGELOG 公告。
• 数据迁移:现有容器 /app/models/whisper 是匿名卷,升级后变为命名卷 whisper-models,默认会从空开始重新下载。已下载的模型如需保留,可在升级前 docker cp 到新卷目录。
• 不会回退:与 [Bug] Docker 部署：DeepSeek 模型列表为空 & whisper 模型下载失败 #417 失败路径正交(本次是改默认值,修复 [Bug] Docker 部署：DeepSeek 模型列表为空 & whisper 模型下载失败 #417 可能还需其他环境侧改动)。

Checklist

• 分支命名遵循 CONTRIBUTING.md §3(ix/docker-*)
• base 指向 master(远程无 develop 分支)
• Commit message 遵循 ype(scope): subject
• 自测:Dockerfile 语法 docker-compose config 验证(若环境允许,本 PR 由 AI 代理提交,完整构建需维护者合并前在 CI 上验证)
• 已更新 CHANGELOG.md
• 未夹带 secrets / .env / 大型二进制
• 单 PR 不跨多个工作区做无关改动