From d5c9b004383f2ef6a14c6b51e564a6db54c14896 Mon Sep 17 00:00:00 2001
From: EricWang1358 <122358137+EricWang1358@users.noreply.github.com>
Date: Tue, 25 Aug 2026 18:53:00 +0800
Subject: [PATCH] =?UTF-8?q?fix(docker):=20=E9=BB=98=E8=AE=A4=20HF=5FENDPOI?=
 =?UTF-8?q?NT=20=E6=94=B9=E5=9B=9E=20huggingface.co=20+=20whisper=20?=
 =?UTF-8?q?=E6=A8=A1=E5=9E=8B=E7=BC=93=E5=AD=98=E7=8B=AC=E7=AB=8B=E5=8D=B7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#417 用户反馈 Docker 部署下 Whisper 模型下载失败,根因在 Dockerfile
默认 ENV HF_ENDPOINT=https://hf-mirror.com。hf-mirror 是国内镜像,境外用户
(包括部分 VPN/海外网络)常不可达或不稳定,导致 faster_whisper
huggingface_hub 拉取模型时直接失败。同时 whisper.py 顶部注释与默认值
自相矛盾('已经在 Dockerfile 里指到 huggingface.co')。

本次改动:
- Dockerfile / Dockerfile.gpu / Dockerfile.complete / 两份 docker-compose
  把默认 HF_ENDPOINT 从 https://hf-mirror.com 改为 https://huggingface.co
- whisper.py 顶部注释同步更新,消除与代码的描述偏差
- docker-compose.yml / docker-compose.gpu.yml 顶层新增命名卷
  whisper-models,挂载到 /app/models/whisper,重建容器不再丢失已下载模型
- CHANGELOG 加 [Unreleased] 段,并注明国内用户可在 .env 中显式
  设 HF_ENDPOINT=https://hf-mirror.com 保留旧行为

无新增测试(Docker 构建 / 命名卷不在 pytest 覆盖范围)。
---
 CHANGELOG.md                       | 7 +++++++
 Dockerfile.complete                | 6 +++---
 backend/Dockerfile                 | 2 +-
 backend/Dockerfile.gpu             | 2 +-
 backend/app/transcriber/whisper.py | 2 +-
 docker-compose.gpu.yml             | 6 ++++++
 docker-compose.yml                 | 6 ++++++
 7 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f5a244c3..81e3d383 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,13 @@
 
 本项目所有重要变更记录于此。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [Unreleased]
+
+### Fixed
+
+- **Docker / Dockerfile 默认 `HF_ENDPOINT` 改回 `huggingface.co`**：`2.4.x` 期间 `Dockerfile` / `docker-compose.yml` / `Dockerfile.complete` 三处默认 `ENV HF_ENDPOINT=https://hf-mirror.com`。`hf-mirror.com` 为中国大陆镜像，**境外网络常不可达或不稳定**——`#417`（Docker 部署下 Whisper 模型下载失败）就是命中了这条路径；同时与 `whisper.py` 顶部说明注释「HF_ENDPOINT 已经在 Dockerfile 里指到 huggingface.co」自相矛盾。三处默认改为 `https://huggingface.co`。**国内用户**只需在 `.env` 中设 `HF_ENDPOINT=https://hf-mirror.com` 即可保留旧行为。
+- **Whisper 模型缓存不再随容器重建丢失**：`docker-compose.yml` / `docker-compose.gpu.yml` 顶层新增命名卷 `whisper-models`，挂载到 `/app/models/whisper`，重建容器后 Whisper / Faster Whisper 已下载模型不会重下。
+
 ## [2.4.4] - 2026-06-23
 
 ### Security
diff --git a/Dockerfile.complete b/Dockerfile.complete
index a7b0d67d..cf80391a 100644
--- a/Dockerfile.complete
+++ b/Dockerfile.complete
@@ -19,7 +19,7 @@ RUN set -ex && \
     rm -rf /var/lib/apt/lists/*
 
 ENV PATH="/usr/bin:${PATH}"
-ENV HF_ENDPOINT=https://hf-mirror.com
+ENV HF_ENDPOINT=https://huggingface.co
 
 WORKDIR /tmp/backend
 
@@ -76,7 +76,7 @@ RUN set -ex && \
     rm -rf /var/lib/apt/lists/*
 
 ENV PATH="/usr/bin:${PATH}"
-ENV HF_ENDPOINT=https://hf-mirror.com
+ENV HF_ENDPOINT=https://huggingface.co
 ENV PYTHONUNBUFFERED=1
 
 # 复制 Python 依赖
@@ -110,7 +110,7 @@ nodaemon=true
 user=root
 logfile=/var/log/supervisor/supervisord.log
 pidfile=/var/run/supervisord.pid
-environment=BACKEND_PORT="8483",BACKEND_HOST="0.0.0.0",TRANSCRIBER_TYPE="fast-whisper",WHISPER_MODEL_SIZE="tiny",FFMPEG_BIN_PATH="",HF_ENDPOINT="https://hf-mirror.com",STATIC="/static",OUT_DIR="./static/screenshots",DATA_DIR="data",NOTE_OUTPUT_DIR="data/note_results",DATABASE_URL="sqlite:////app/backend/data/bili_note.db",IMAGE_BASE_URL="/static/screenshots",ENV="production",GROQ_TRANSCRIBER_MODEL="whisper-large-v3-turbo"
+environment=BACKEND_PORT="8483",BACKEND_HOST="0.0.0.0",TRANSCRIBER_TYPE="fast-whisper",WHISPER_MODEL_SIZE="tiny",FFMPEG_BIN_PATH="",HF_ENDPOINT="https://huggingface.co",STATIC="/static",OUT_DIR="./static/screenshots",DATA_DIR="data",NOTE_OUTPUT_DIR="data/note_results",DATABASE_URL="sqlite:////app/backend/data/bili_note.db",IMAGE_BASE_URL="/static/screenshots",ENV="production",GROQ_TRANSCRIBER_MODEL="whisper-large-v3-turbo"
 
 [program:nginx]
 command=nginx -g "daemon off;"
diff --git a/backend/Dockerfile b/backend/Dockerfile
index d08fb376..8edbeed2 100644
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@ -17,7 +17,7 @@ RUN rm -f /etc/apt/sources.list && \
     rm -rf /var/lib/apt/lists/*
 
 ENV PATH="/usr/bin:${PATH}"
-ENV HF_ENDPOINT=https://hf-mirror.com
+ENV HF_ENDPOINT=https://huggingface.co
 
 WORKDIR /app
 
diff --git a/backend/Dockerfile.gpu b/backend/Dockerfile.gpu
index aff0073f..eb2d9f06 100644
--- a/backend/Dockerfile.gpu
+++ b/backend/Dockerfile.gpu
@@ -14,7 +14,7 @@ RUN rm -f /etc/apt/sources.list && \
     apt-get install -y --no-install-recommends ffmpeg python3-pip curl && \
     rm -rf /var/lib/apt/lists/*
 
-ENV HF_ENDPOINT=https://hf-mirror.com
+ENV HF_ENDPOINT=https://huggingface.co
 
 WORKDIR /app
 
diff --git a/backend/app/transcriber/whisper.py b/backend/app/transcriber/whisper.py
index 3d254a26..fb3da701 100644
--- a/backend/app/transcriber/whisper.py
+++ b/backend/app/transcriber/whisper.py
@@ -30,7 +30,7 @@
 # 在线请求失败 → fallback local_files_only=True → HF cache 找不到（因为是
 # modelscope 目录布局不是 HF）→ LocalEntryNotFoundError，误导说"离线模式"。
 # 解法：彻底让 faster-whisper 自己处理下载——传 size name，配 download_root
-# 作为 HF cache 根目录，HF_ENDPOINT 已经在 Dockerfile 里指到 hf-mirror.com，
+# 作为 HF cache 根目录，HF_ENDPOINT 已经在 Dockerfile 里指到 huggingface.co，
 # 国内能用。删掉 modelscope 那一套，避免布局不匹配。
 class WhisperTranscriber(Transcriber):
     def __init__(
diff --git a/docker-compose.gpu.yml b/docker-compose.gpu.yml
index 327bed27..c8334b2d 100644
--- a/docker-compose.gpu.yml
+++ b/docker-compose.gpu.yml
@@ -15,9 +15,12 @@ services:
     environment:
       - BACKEND_PORT=${BACKEND_PORT}
       - BACKEND_HOST=${BACKEND_HOST}
+      - HF_ENDPOINT=https://huggingface.co
     volumes:
       # 同 docker-compose.yml：./backend 绑到 /app，DB / 转写器配置 / 截图 / 上传都持久化
       - ./backend:/app
+      # whisper 模型缓存单独持久化，避免重建容器重新下载
+      - whisper-models:/app/models/whisper
     expose:
       - "${BACKEND_PORT}"  # 不再对外暴露，用于 nginx 内部通信
     # 用 unless-stopped 避免短暂崩溃把容器永久打死后再也读不到 .env 修改
@@ -66,3 +69,6 @@ services:
         condition: service_started
     restart: unless-stopped
     mem_limit: 256m
+
+volumes:
+  whisper-models:
diff --git a/docker-compose.yml b/docker-compose.yml
index bcb022d4..f023b411 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -15,6 +15,7 @@ services:
     environment:
       - BACKEND_PORT=${BACKEND_PORT}
       - BACKEND_HOST=${BACKEND_HOST}
+      - HF_ENDPOINT=https://huggingface.co
     volumes:
       # 把整个 backend/ 目录绑到 /app，意味着这些都持久化到宿主机、删容器不丢：
       #   ./backend/bili_note.db                — SQLite 数据库（含 LLM 供应商配置、笔记历史）
@@ -22,6 +23,8 @@ services:
       #   ./backend/static/screenshots/         — 视频截图
       #   ./backend/uploads/                    — 上传的本地视频
       - ./backend:/app
+      # whisper 模型缓存单独持久化，避免重建容器重新下载
+      - whisper-models:/app/models/whisper
     expose:
       - "${BACKEND_PORT}"  # 不再对外暴露，用于 nginx 内部通信
     # 用 unless-stopped 而非 on-failure:N，避免任何短暂崩溃把容器永久打死后
@@ -65,3 +68,6 @@ services:
         condition: service_started
     restart: unless-stopped
     mem_limit: 256m
+
+volumes:
+  whisper-models: