依赖下载点全部配国内源,并修掉「镜像里没有中文字体」这个字幕坑

用户诉求是「镜像已有,其它依赖考虑国内加速」。先把全链路的外部下载点摸了一遍,
结论:**构建镜像不需要 huggingface**——唯一的 HF 地址在 scripts/server.sh,
只在裸机 install 的 fetch_asr_model() 里用到,而且容器里根本没有 whisper-cli,
那条 curl 在 Docker 路径下永远不会执行;requirements.txt 只有 8 个包(没有任何
whisper/hub 依赖),models/ 也被 .dockerignore 排掉。构建期真正的下载点只有
npm / apt / pip 三个,此前 npm 与 pip 已是国内源,只有 apt 还默认 deb.debian.org
(实测这一层要 200+ 秒,清华 0.24 秒拿到 Release)。

改动:
- Dockerfile:APT_MIRROR 默认改清华(境外显式传回 deb.debian.org);apt 清单
  ffmpeg → ffmpeg fontconfig fonts-noto-cjk。后两个是真 bug 修复——slim +
  --no-install-recommends 连 DejaVu 都不带,libass 找不到中文字形**不报错**,
  直接把烧的字幕画成一片豆腐块;services/ffmpeg.py 又要靠 fc-list/fc-scan
  按 charset 反查字体,所以 fontconfig 也一并装上。装完代码零改动:
  _FONT_FILE_CANDIDATES 里已写着 fonts-noto-cjk 的落盘路径。嫌 +120MB 可换
  fonts-wqy-microhei(+10MB)。
- server.sh / dev.sh:新增 PIP_INDEX_URL / NPM_REGISTRY / ASR_DOWNLOAD_URL 三组
  可覆盖变量,优先级 环境变量 > .env > 内置默认,键名与 Dockerfile 的 --build-arg
  完全一致(容器和裸机同一套口径);pip 一律带 -i、npm 一律带 --registry;
  ASR 权重默认走 hf-mirror(huggingface.co 国内实测 0.04s 直接连接重置)。
- server.sh install 新增中文字体探测:复用 app.services.ffmpeg.cjk_font_catalog(),
  查不到就 warn,别等出片了才发现字幕是方块。
- 四处默认值对齐(Dockerfile / docker-compose.yml / server.sh / dev.sh)。
- README §3.2 新增「依赖下载点与国内源」表:五个下载点各自发生在什么时候、
  用哪个键、默认值是什么,并点明浏览器侧 Google Fonts 是最后一处外部依赖
  (只影响访问者,要彻底离线需自托管);工程规范 §5 补一条「依赖源只有一套键、
  默认即国内,判据是新机器零配置能装起来」。

验证:bash -n 两个脚本通过;字体探针正反向都跑过(本机 49 个中文字体 → exit 0);
docker compose config 服务仍只有 app、args 渲染出新默认值;deploy.sh --check 19 项全绿;
pytest -k "ffmpeg or subtitle or font or asr or speech or quality" 35 passed 1 skipped
(未改后端代码,故未跑全量)。docker build 本机验证不了(Docker daemon 没起),
需在服务器上构建确认。
main
mula.liu 2026-11-05 19:36:32 +08:00
parent c048a3bc2c
commit 27f3656d6b
6 changed files with 100 additions and 25 deletions

View File

@ -22,8 +22,13 @@
# 少了 -v $PWD/media 会怎样:出片写进容器可写层,`up --force-recreate` 之后
# 页面上一片 404,而且文件跟着容器一起被删——产物比镜像贵得多,别赌。
#
# 国内网络:BASE_IMAGE / NODE_IMAGE / PIP_INDEX_URL / NPM_REGISTRY 都能 --build-arg 覆盖,
# 默认值走清华 pip 与 npmmirror(境外构建把后两个换成官方源即可)。
# 国内网络:构建期只有三个下载点,默认值全部已指向国内源,零配置即可用——
# npm -> NPM_REGISTRY(默认 npmmirror,且 package-lock.json 的 211 条 resolved 本身就锁在 npmmirror)
# pip -> PIP_INDEX_URL(默认清华)
# apt -> APT_MIRROR(默认清华)
# 基础镜像 BASE_IMAGE / NODE_IMAGE 也在 --build-arg 里;服务器上已有这两个镜像时,
# `docker compose up -d --build` 不加 --pull 就不会联网重拉。境外构建反过来传官方源即可。
# 构建期**没有任何 huggingface 下载**:听写权重(465M)只在裸机 server.sh install 时才拉。
# =============================================================================
ARG BASE_IMAGE=python:3.12-slim
ARG NODE_IMAGE=node:22-alpine
@ -50,16 +55,25 @@ ENV PYTHONUNBUFFERED=1 \
TZ=Asia/Shanghai
WORKDIR /app
# ffmpeg 是硬依赖:时间线合成、抽帧、时长/码率质检全靠调它(app/services/ffmpeg.py),
# slim 基础镜像里没有,缺了它的表现是「导出成片一路 500」而不是起不来。
# 装三个包,缺一不可,而且后两个的缺失是「静默出错」而不是报错:
# ffmpeg 时间线合成、抽帧、时长/码率质检全靠调它(app/services/ffmpeg.py),
# 缺了它的表现是「导出成片一路 500」而不是起不来;
# fontconfig 提供 fc-list / fc-scan —— services/ffmpeg.py 靠它们按 charset
# 反查「哪个字体真的含中文字形」,没有 fc-list 就只能退到写死的路径清单;
# fonts-noto-cjk 烧字幕必须有真的含中文字形的字体。slim + --no-install-recommends
# 连 DejaVu 都不带,libass 找不到字形**不报错**,直接画一排豆腐块,
# 字幕质检和成片一起废(本轮真实踩过,见 ffmpeg.py 注释)。
# 嫌它 +120MB 就换成 fonts-wqy-microhei(+10MB,同样在候选清单里)。
# 源同样是可覆盖的:deb822 与老式 sources.list 里 bookworm 的 /debian 与 /debian-security
# 都在 deb.debian.org 下,一次替换就够;换镜像不动默认值,不传参等于官方源。
ARG APT_MIRROR=deb.debian.org
# 都在 deb.debian.org 下,一次替换就够。默认给清华:实测直连 deb.debian.org 光这一层就要
# 200+ 秒,清华 0.24 秒拿到 Release;境外构建显式传回 --build-arg APT_MIRROR=deb.debian.org。
ARG APT_MIRROR=mirrors.tuna.tsinghua.edu.cn
RUN for f in /etc/apt/sources.list.d/debian.sources /etc/apt/sources.list; do \
[ -f "$f" ] && sed -i "s|deb\.debian\.org|${APT_MIRROR}|g; s|security\.debian\.org|${APT_MIRROR}|g" "$f"; \
done; \
apt-get update \
&& apt-get install -y --no-install-recommends ffmpeg \
&& apt-get install -y --no-install-recommends \
ffmpeg fontconfig fonts-noto-cjk \
&& rm -rf /var/lib/apt/lists/*
# 依赖单独一层:requirements.txt 里带着 psycopg,将来切 Postgres 扩容不必重建镜像骨架

View File

@ -370,13 +370,29 @@ docker compose up -d
| 想改什么 | 改哪里 |
| --- | --- |
| 对外端口 | **`.env` 里的 `HOST_PORT`**(部署形态:Docker 的映射、裸机 `server.sh` 的监听都读它)。容器内固定 8000,改 `HOST_PORT` 改的只是对外映射,且要重跑 `up -d`;开发形态另用 `BACKEND_PORT` / `FRONTEND_PORT`,详见 §3.2 的端口表 |
| 拉不到 docker.io / 装包慢 | `.env` 或 `--build-arg` 覆盖 `BASE_IMAGE`、`NODE_IMAGE`、`PIP_INDEX_URL`、`NPM_REGISTRY`、`APT_MIRROR`(apt 源,装 ffmpeg 那一层) |
| 装包慢 / 源不通 | 见下面「依赖下载点与国内源」:`PIP_INDEX_URL`、`NPM_REGISTRY`、`APT_MIRROR` **默认已是国内源**,只有拉不到 docker.io 时才需要动 `BASE_IMAGE`、`NODE_IMAGE` |
| 换 ComfyUI / 换 GPU 机 | **不在 `.env` 里改**:登录页面「调度中心 → 模型中心」,改那几条模型的 `base_url` 并点 🔌 探测,改完即生效、不用重启。指宿主机写 `http://host.docker.internal:9200`(`extra_hosts` 已备 `host-gateway`),写 `127.0.0.1` 指向的是容器自己 |
| 顺带起一个自建 ComfyUI | `docker compose --profile comfy up -d`(默认**不起**,算力在远端时不用管),再把 `base_url` 指 `http://comfyui:8188` |
#### 依赖下载点与国内源(默认即国内,零配置)
构建 + 安装全链路一共只有五个下载点。**镜像构建里没有 huggingface**:465M 的听写权重不进镜像层
(`.dockerignore` 排掉了 `models/`,`requirements.txt` 里也没有任何 whisper/hub 包)。
| 下载点 | 什么时候发生 | 键(环境变量 / `.env` / `--build-arg`) | 默认值 |
| --- | --- | --- | --- |
| 基础镜像 `python:3.12-slim`、`node:22-alpine` | `docker build` | `BASE_IMAGE` / `NODE_IMAGE` | docker.io 官方 tag。**服务器上已有就不管**:compose 不加 `--pull` 就用本地 tag,不联网 |
| npm 依赖 | `docker build` 第 1 阶段;`server.sh install`、`dev.sh` | `NPM_REGISTRY` | `https://registry.npmmirror.com`(`package-lock.json` 的 211 条 `resolved` 本身就锁在 npmmirror,`npm ci` 天然走国内) |
| apt:`ffmpeg fontconfig fonts-noto-cjk` | `docker build` 第 2 阶段 | `APT_MIRROR` | `mirrors.tuna.tsinghua.edu.cn`(直连 `deb.debian.org` 实测这一层 200+ 秒) |
| pip 依赖(8 个包) | `docker build`;`server.sh install`、`dev.sh` | `PIP_INDEX_URL` | `https://pypi.tuna.tsinghua.edu.cn/simple` |
| whisper 听写权重 `ggml-small.bin`(465M,可选) | **只有裸机** `server.sh install`(`--no-asr` 跳过,且没装 whisper-cli 时自动跳过) | `ASR_DOWNLOAD_URL` | `https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main/ggml-small.bin`(`huggingface.co` 国内实测连接直接被重置) |
境外机器把上面四个源显式传回官方值即可,Dockerfile 不用改。
**最后一处外部依赖在浏览器侧**:`frontend/index.html` 引 `fonts.googleapis.com` 的 DM Sans + Noto Sans SC,
只影响访问者的网络,与服务器/构建无关(本机实测 0.3s 可达);要彻底离线得自托管字体,目前没做。
拉不到 docker.io 时不用改 Dockerfile,把两个基础镜像指到能通的 registry 就行(本机实测可用,
`npm ci`/`apt`/`pip` 三段源都能在 `.env` 里换(`NPM_REGISTRY` / `APT_MIRROR=mirrors.tuna.tsinghua.edu.cn` /
`PIP_INDEX_URL`),构建一次约 5 分钟,其中 apt 装 ffmpeg 约 4 分钟,之后改代码只重跑 COPY 层):
构建一次约 5 分钟,之后改代码只重跑 COPY 层):
```bash
BASE_IMAGE=swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/python:3.12-slim \
@ -385,7 +401,12 @@ docker compose up -d --build
```
**镜像里没有 whisper-cli**:成片台词听写这项质检在容器里会自动跳过(`services/asr.py` 探测不到就
报告原因,不影响出片)。要它在容器里可用,得自己加一个构建阶段编译 whisper.cpp,或者走 §3.4 裸机形态。
报告原因,不影响出片),所以 Docker 形态下没有任何理由去下载那 465M 权重。要它在容器里可用,
得自己加一个构建阶段编译 whisper.cpp(并把 `./models` 挂进来,compose 已备 `:ro` 挂载),
或者走 §3.4 裸机形态。
**镜像里有中文字体**(`fonts-noto-cjk`):这是烧字幕的硬依赖。libass 找不到中文字形**不报错**,
直接把字幕画成一片豆腐块,且质检也会跟着误判。镜像里 `fc-list :charset=4e2d` 查不到字体就是这个问题。
**要扩容再叠一层**(多 GPU、多人同时出片、worker 放别的机器):

View File

@ -22,12 +22,14 @@ services:
build:
context: .
args:
# 源与基础镜像可在 .env 里覆盖,默认值就按国内直连能通的配
# 构建期只有 npm / apt / pip 三个下载点(**没有 huggingface**:听写权重不进镜像),
# 默认值全按国内直连能通的配,运维零配置;境外构建显式传回官方源。
# 基础镜像本机已有就别加 --pull,否则每次都会去 registry 校验一次。
BASE_IMAGE: "${BASE_IMAGE:-python:3.12-slim}"
NODE_IMAGE: "${NODE_IMAGE:-node:22-alpine}"
PIP_INDEX_URL: "${PIP_INDEX_URL:-https://pypi.tuna.tsinghua.edu.cn/simple}"
NPM_REGISTRY: "${NPM_REGISTRY:-https://registry.npmmirror.com}"
APT_MIRROR: "${APT_MIRROR:-deb.debian.org}"
APT_MIRROR: "${APT_MIRROR:-mirrors.tuna.tsinghua.edu.cn}"
image: nex-animation:latest
container_name: nex-animation
restart: unless-stopped

View File

@ -199,7 +199,7 @@ ffmpeg 与本地听写权重)。判据是一句话:**换模型要不要重
| 管理员账号(`users` 里 role=admin) | 同上,导 `password_hash`,不带明文口令 |
| 项目 / 镜头 / 任务 / 事件日志 | **不部署**,服务器从空库开始 |
| `media/` 媒体、平台资源库 | **不部署**;需要时走 `seed.py --with-platform-library` + 手工拷 `media/platform/`。Docker 形态下它是独立挂载点(`./media` ↔ 容器 `/app/media` = `MEDIA_ROOT`),和 SQLite 所在的 `./data` 分开备份 |
| whisper 听写权重 | `server.sh install` 自动下载(`--no-asr` 跳过) |
| whisper 听写权重 | `server.sh install` 自动下载(`--no-asr` 跳过;默认走 `ASR_DOWNLOAD_URL` 指向的 hf-mirror)。**Docker 形态不下载它**:镜像里没有 whisper-cli,`models/` 也被 `.dockerignore` 排掉 |
**开发机打包**(`export --fix` 与 `deploy.sh` 都会体检,区别只是拦在哪一步):
@ -303,6 +303,13 @@ sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service #
**回滚**:部署包不解覆盖式删除远端文件(不加 `--delete`),`.env` 与 `media/` 原地保留,
把 `.env` 指回旧目录即可回退。
**依赖源只有一套键、默认即国内。** 全项目允许出现的外部下载点就五个(基础镜像、npm、apt、pip、
whisper 权重),键名固定为 `BASE_IMAGE` / `NODE_IMAGE` / `NPM_REGISTRY` / `APT_MIRROR` /
`ASR_DOWNLOAD_URL`,`PIP_INDEX_URL` 用 pip 官方同名键;Dockerfile、`server.sh`、`dev.sh`、
`docker-compose.yml` 四处默认值必须一致,新增下载点要同步进 README §3.2 的那张表。
默认值一律给国内源(npmmirror / 清华 / hf-mirror),境外构建显式传官方值——
判据是「新机器上零配置能装起来」,不是「默认值等于上游官方」。
## 6. 删除策略(git 捞不回来的那部分)
`.trash/` 与 `.local/` 都在 `.gitignore` 里,被删的内容**多半是未跟踪的运行时数据**(媒体、日志、验收证据),git 捞不回来,所以:

View File

@ -59,6 +59,13 @@ BACKEND_PORT="${BACKEND_PORT:-$(env_value PORT)}" # 旧键兼容
BACKEND_PORT="${BACKEND_PORT:-8000}"
FRONTEND_PORT="${FRONTEND_PORT:-$(env_value FRONTEND_PORT)}"
FRONTEND_PORT="${FRONTEND_PORT:-5173}"
# 依赖下载源:和 server.sh / Dockerfile 同一套键(PIP_INDEX_URL / NPM_REGISTRY),
# 默认国内源,优先级 环境变量 > .env > 内置默认。
PIP_INDEX="${PIP_INDEX_URL:-$(env_value PIP_INDEX_URL)}"
PIP_INDEX="${PIP_INDEX:-https://pypi.tuna.tsinghua.edu.cn/simple}"
NPM_REGISTRY="${NPM_REGISTRY:-$(env_value NPM_REGISTRY)}"
NPM_REGISTRY="${NPM_REGISTRY:-https://registry.npmmirror.com}"
RELOAD=0
AUTO_INSTALL=1
WANT_BACKEND=1
@ -131,14 +138,16 @@ prepare() {
info "创建虚拟环境并安装后端依赖(首次约 1~2 分钟)…"
command -v python3 >/dev/null || die "缺少 python3"
python3 -m venv "$ROOT/.venv" || die "venv 创建失败"
"$PYBIN" -m pip install -q --upgrade pip
"$PYBIN" -m pip install -q -r "$ROOT/backend/requirements.txt" || die "后端依赖安装失败"
ok "后端依赖已安装"
"$PYBIN" -m pip install -q -i "$PIP_INDEX" --upgrade pip
"$PYBIN" -m pip install -q -i "$PIP_INDEX" -r "$ROOT/backend/requirements.txt" \
|| die "后端依赖安装失败(换源:PIP_INDEX_URL=https://…)"
ok "后端依赖已安装(pip 源 ${PIP_INDEX})"
elif ! "$PYBIN" -c "import uvicorn, fastapi" 2>/dev/null; then
[ "$AUTO_INSTALL" = 1 ] || die "后端依赖不完整(缺 uvicorn/fastapi),且指定了 --no-install"
info "补齐后端依赖…"
"$PYBIN" -m pip install -q -r "$ROOT/backend/requirements.txt" || die "后端依赖安装失败"
ok "后端依赖已补齐"
"$PYBIN" -m pip install -q -i "$PIP_INDEX" -r "$ROOT/backend/requirements.txt" \
|| die "后端依赖安装失败(换源:PIP_INDEX_URL=https://…)"
ok "后端依赖已补齐(pip 源 ${PIP_INDEX})"
else
ok "后端依赖就绪($("$PYBIN" -V 2>&1))"
fi
@ -150,7 +159,7 @@ prepare() {
command -v npm >/dev/null || die "缺少 npm(前端需要)"
[ "$AUTO_INSTALL" = 1 ] || die "缺少 frontend/node_modules,且指定了 --no-install:cd frontend && npm install"
info "安装前端依赖…"
(cd "$ROOT/frontend" && npm install --no-audit --no-fund) > "$LOG_DIR/npm-install.log" 2>&1 \
(cd "$ROOT/frontend" && npm install --registry "$NPM_REGISTRY" --no-audit --no-fund) > "$LOG_DIR/npm-install.log" 2>&1 \
|| die "npm install 失败,详见 .local/logs/npm-install.log"
ok "前端依赖已安装"
else

View File

@ -56,7 +56,17 @@ PORT="${HOST_PORT:-${PORT:-$(env_value HOST_PORT)}}"
PORT="${PORT:-$(env_value PORT)}" # 旧键兼容:上一版模板这里叫 PORT
PORT="${PORT:-8000}"
ASR_MODEL="$ROOT/models/asr/ggml-small.bin"
ASR_URL="https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin"
# ---- 依赖下载源:默认国内源,优先级 环境变量 > .env > 内置默认 ----
# 裸机 install 也要装 pip/npm 依赖,不配国内源时首次 install 能卡十几分钟。
# 键名与 Dockerfile 的 --build-arg 完全一致,容器和裸机同一套口径。
PIP_INDEX="${PIP_INDEX_URL:-$(env_value PIP_INDEX_URL)}"
PIP_INDEX="${PIP_INDEX:-https://pypi.tuna.tsinghua.edu.cn/simple}"
NPM_REGISTRY="${NPM_REGISTRY:-$(env_value NPM_REGISTRY)}"
NPM_REGISTRY="${NPM_REGISTRY:-https://registry.npmmirror.com}"
# 听写权重 465MB:huggingface.co 国内实测连接直接被重置(curl 0.04s 返回 000),
# 默认走 hf-mirror.com;境外机器传 ASR_DOWNLOAD_URL 换回官方地址。
ASR_URL="${ASR_DOWNLOAD_URL:-$(env_value ASR_DOWNLOAD_URL)}"
ASR_URL="${ASR_URL:-https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main/ggml-small.bin}"
WANT_ASR=1
SKIP_DEPS=0
SKIP_BUILD=0
@ -104,25 +114,37 @@ install_backend_deps() {
if [ ! -x "$PYBIN" ]; then
info "创建虚拟环境并安装依赖(首次 1~2 分钟)…"
python3 -m venv "$ROOT/.venv" || die "venv 创建失败(Debian/Ubuntu 需 apt install python3-venv)"
"$PYBIN" -m pip install -q --upgrade pip
"$PYBIN" -m pip install -q -i "$PIP_INDEX" --upgrade pip
fi
# 3.11+ 是硬门槛:Debian 12 自带的 python3 是 3.11(够用),但更老发行版的 3.9
# 会在 import 阶段就炸在 `str | None` 上。与其让服务起不来,不如装依赖时先说清楚。
"$PYBIN" -c 'import sys; sys.exit(0 if sys.version_info >= (3, 11) else 1)' \
|| die "Python 版本过低($("$PYBIN" -V 2>&1)),本项目需要 3.11+,请装更新的 python3"
"$PYBIN" -m pip install -q -r "$ROOT/backend/requirements.txt" || die "后端依赖安装失败"
ok "$("$PYBIN" -V 2>&1) · fastapi/uvicorn/sqlalchemy 就绪"
"$PYBIN" -m pip install -q -i "$PIP_INDEX" -r "$ROOT/backend/requirements.txt" \
|| die "后端依赖安装失败(换源:PIP_INDEX_URL=https://… $0 install)"
ok "$("$PYBIN" -V 2>&1) · fastapi/uvicorn/sqlalchemy 就绪(pip 源 ${PIP_INDEX})"
if command -v ffmpeg >/dev/null && command -v ffprobe >/dev/null; then
ok "ffmpeg 就绪(合成、质检可用)"
else
warn "未找到 ffmpeg/ffprobe:合成与质检会失败(apt install ffmpeg / brew install ffmpeg)"
fi
# 中文字形:libass 找不到字形不报错,只会把字幕画成一片豆腐块,
# 所以宁可现在 warn 一句,也别等出片了才发现(探测复用 app/services/ffmpeg.py 的同一段逻辑)。
if command -v ffmpeg >/dev/null && ! NEX_BACKEND_DIR="$ROOT/backend" "$PYBIN" - <<'PY' 2>/dev/null
import os, sys
sys.path.insert(0, os.environ["NEX_BACKEND_DIR"])
from app.services.ffmpeg import cjk_font_catalog
sys.exit(0 if cjk_font_catalog() else 1)
PY
then
warn "没找到含中文字形的字体:烧字幕会出豆腐块(Debian/Ubuntu: apt install fontconfig fonts-noto-cjk)"
fi
}
build_frontend() {
head2 "前端构建"
command -v npm >/dev/null || die "缺少 npm(Node 18+)"
(cd "$ROOT/frontend" && { [ -d node_modules ] || npm ci --no-audit --no-fund; } && npm run build) \
(cd "$ROOT/frontend" && { [ -d node_modules ] || npm ci --registry "$NPM_REGISTRY" --no-audit --no-fund; } && npm run build) \
> "$LOG_DIR/build.log" 2>&1 || { tail -30 "$LOG_DIR/build.log"; die "前端构建失败,详见 .local/logs/build.log"; }
[ -f "$ROOT/frontend/dist/index.html" ] || die "构建结束但没有 frontend/dist/index.html"
ok "frontend/dist 就绪($(du -sh "$ROOT/frontend/dist" | cut -f1),$(find "$ROOT/frontend/dist" -type f | wc -l | tr -d ' ') 个文件)"