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

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

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;"

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
 

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
 

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__(

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:

docker-compose.yml

@@ -15,13 +15,16 @@ services:
     environment:
       - BACKEND_PORT=${BACKEND_PORT}
       - BACKEND_HOST=${BACKEND_HOST}
+      - HF_ENDPOINT=https://huggingface.co
     volumes:
       # 把整个 backend/ 目录绑到 /app，意味着这些都持久化到宿主机、删容器不丢：
       #   ./backend/bili_note.db                — SQLite 数据库（含 LLM 供应商配置、笔记历史）
       #   ./backend/config/transcriber.json     — 转写器运行时配置
       #   ./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: