Commit Graph

5 Commits (27f3656d6b722a6966f2d9338cd6bda8292d280d)

Author SHA1 Message Date
mula.liu 27f3656d6b 依赖下载点全部配国内源,并修掉「镜像里没有中文字体」这个字幕坑
用户诉求是「镜像已有,其它依赖考虑国内加速」。先把全链路的外部下载点摸了一遍,
结论:**构建镜像不需要 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 没起),
需在服务器上构建确认。
2026-11-05 19:36:32 +08:00
mula.liu 1a886beca6 端口按形态分键:HOST_PORT 只管部署对外,BACKEND_PORT/FRONTEND_PORT 只管开发;.env.example 与 compose 去噪音
一、端口三个键,各管一种形态,键名自带场景
上一轮我把它收敛成单一的 PORT,方向收得太狠:一个键被三种形态共用,等于把「这是给谁看的」
又塞回 README 里——同一个 HOST_PORT 在 Docker 下指对外映射、在裸机下指监听、在开发下指后端,
不翻文档的人分不出来。按形态分回去,判据从来不是键的个数,而是含义的唯一性:
一个键只能有一种含义、同一个 socket 不能有两个键。

  HOST_PORT      部署形态对外暴露的端口:compose 拿它插值做端口映射,server.sh 回读它做监听端口
  BACKEND_PORT   开发形态的后端 uvicorn(dev.sh 回读,并同步 Vite 代理目标)
  FRONTEND_PORT  开发形态的前端 Vite(独立进程,必须与后端错开)

compose 的 ports 回到 "${HOST_PORT:-8000}:8000",并删掉上一轮为兼容 PORT 加的 environment.PORT="8000"
钉子(键名分开之后没有歧义要钉了)。server.sh 的取值链改成
命令行 --port > 环境变量 HOST_PORT/PORT > .env 的 HOST_PORT > 8000,
旧键 PORT 留一版兼容;dev.sh 只认 BACKEND_PORT/FRONTEND_PORT(PORT 作旧键回退)。
实测:.env 写 HOST_PORT=8010 → compose published=8010、server.sh status 打 :8010;
HOST_PORT=9301 环境变量覆盖 → :9301;BACKEND_PORT=8000/FRONTEND_PORT=5173 → dev.sh 两个进程端口正确。

二、.env.example 按 .env 的样式重写,噪音清掉
它是运维唯一被要求编辑的文件,之前 100 行里 65 行是注释与说明,还有一批在 Docker 形态下
根本没人读的键。现在 32 个生效键 / 11 行注释,键位与本机 .env 一一对应,只放配置本身:
- 删掉 compose 覆盖掉的那几行的误导(SERVE_FRONTEND 不再列;DATABASE_URL/MEDIA_ROOT 只留一行说明
  「Docker 形态 compose 会指到挂载点」),长篇「为什么不在这里」全部搬到 README §3 与工程规范 §5,
  .env 头部三行指路。
- 删掉只在叠加 scale.yml 时才有人读的 POSTGRES_*/REDIS_URL/CELERY_*(默认值写在 scale.yml 里)。
- 删掉与代码默认值同值的长尾键(上传白名单、COOKIE_NAME、FRONTEND_DIST_DIR、QC 细项等),
  需要的人按 Settings 字段名加一行即可(文件头写明键名 = 字段大写下划线)。
- 默认值改成单容器真相:SQLite + inline,不再是 postgresql+…@db:5432 + celery。
本机 .env 同步精简成 11 键 / 8 行注释,并把容器对外端口定成 HOST_PORT=8010(8000 坐着开发后端)。

三、docker-compose.yml 114 行 → 77 行
头部 34 行的架构论证压成 16 行只留「常用命令 + 配置来源 + 四个挂载点 + 指路 README」,
正文注释每条最多一行;为什么单容器、模型配置为什么不在这份文件里、扩容层怎么叠,
都指向 README §3.2 / §4.0。顺手把上一轮的教训留住:改 .env 之后必须重跑 up -d,
restart 沿用旧容器配置、不换端口映射,这条写进了命令清单。
env_value() 补上「去随行注释与尾部空白」:三种解析器(python-dotenv、compose env_file、
本仓的 sed 回读)里只有前者会剥行内注释,漏了它 server.sh 会把
「HOST_PORT=8010  # 本机跑容器…」整串当端口用。

四、文档同步:README §3.2 加端口三键表与「改了没反应的四个键」,§3.1 前端代理、§3.2 命令、
常用改动表、§3.4 server.sh 注释全部改口径;docs/工程规范.md §5 把规则从「端口只有一个键」
改写成「按形态分键 + 含义唯一」,并把两次反复的教训写进正文。

验证:bash -n 两个脚本通过;docker compose config --services 仍只有 app,published 随 HOST_PORT 变化,
容器内四个覆盖值仍是挂载点那套;deploy.sh --check 全绿(19 项入口齐全);
两份 env 0 未知键 0 模型键;backend 全量 502 passed / 1 skipped。
2026-11-05 19:01:32 +08:00
mula.liu 1934fb8bcc 端口收成一个键 PORT,.env 里的模型说明清零,apt 源也能换
一、端口:HOST_PORT / PORT / BACKEND_PORT 三个键砍成一个

上一轮把端口小节加回 .env.example 时,我按「三种部署形态」列了三个键:
Docker 用 HOST_PORT、裸机 server.sh 用 PORT、开发 dev.sh 用 BACKEND_PORT+FRONTEND_PORT。
听起来各管一摊,实际上它们指的是同一件事——「这个应用对外听在哪个端口」。
一份要交给运维编辑的文件里出现三个同义键,他的第一反应必然是「我该改哪个」,
而改错那个的表现还是「服务起来了但端口没变」,跟没改一样。所以这次收到一个:

  PORT = 应用对外端口。Docker 对外的映射读它、裸机 server.sh 的监听端口读它、
         开发态的后端也读它。

- docker-compose.yml:ports 改成 "${PORT:-${HOST_PORT:-8000}}:8000",旧键留一版回退;
  另外在 environment 里显式写死 PORT: "8000",因为容器内永远监听 8000
  (EXPOSE 与健康检查都按 8000 写死),宿主 .env 注进来的那份不能让它漂——
  今天应用不读 PORT 没事,将来谁加一行 os.environ["PORT"] 就会变成
  「映射 9000:8000 但进程监听 9000」,容器直接不通。
- server.sh / dev.sh:加 env_value() 回读仓库根 .env(上一轮删掉过,是倒退)。
  取值优先级统一 命令行 > 环境变量 > .env > 默认值;旧键 HOST_PORT / BACKEND_PORT
  只作兼容回退。回读 .env 是有意的:.env 是运维唯一被要求编辑的文件,
  写进去的键必须真的生效,否则就是本仓最忌讳的「写了不生效」。
- 开发态仍保留 FRONTEND_PORT,这不是同义键:Vite 是独立进程,必须和后端错开端口。
- 实测:.env 写 PORT=8211 → server.sh status 打印 server :8211、dev.sh status 打印
  backend :8211;PORT=9000 docker compose config 的 published 变 9000 而容器内
  PORT 仍是 8000;HOST_PORT=9100(.env 无 PORT 时)仍能回退到 9100。

二、.env / .env.example:只留配置本身

模型相关的配置和说明全部删净——现在两份文件里 VIDEO_* / COMFYUI_* / TTS_* / IMAGE_* / LLM_*
一个键都没有,原先三段「模型配置为什么不在这里」的长说明压成头部两行指引
(去页面「调度中心 → 模型中心」改,服务器初值随 scripts/seed/ 导入)。
.env.example 55 行注释对 45 个生效键,每条最多两行;本机 .env 10 键 10 行注释。
顺带确认:本机 .env 没被删过,它是 gitignored 的,所以从来不出现在提交里。
APP_DATABASE_URL / APP_MEDIA_ROOT 归到 Docker 小节(它们只在容器里成立)。
键名逐个对过 Settings 字段:两份文件 0 个未知键(多余键本身会被 extra="ignore" 吞掉,
但写错字得能立刻看出来)。

三、ffmpeg:镜像里装了,而且源现在可换

回答提问:装了。Dockerfile 运行阶段(python:3.12-slim 没有 ffmpeg)apt 装它,
时间线合成、抽帧、时长/码率质检全调它(app/services/ffmpeg.py);
缺它的表现是「导出成片一路 500」而不是起不来,所以没做成可选层。
实测容器 /health 报 ffmpeg=true(/usr/bin/ffmpeg 5.1.9-0+deb12u1,
libass/xfade/subtitles/loudnorm 全 true)。
但这一段以前是唯一没做国内镜像的装包层,README 却写着「三段都走公网镜像源」——
名不副实,且上次该层在构建机上跑了约 221 s。补上 ARG APT_MIRROR(默认 deb.debian.org,
不传参等于原行为),bookworm 的 /debian 与 /debian-security 同在 deb.debian.org 下,
一次 sed 覆盖 deb822 与老式 sources.list 两种文件;compose 侧透出同名 build-arg。

四、文档同步:README §3.2 端口行与构建源行、§3.4、前端代理那条;
docs/工程规范.md §5 补「一件事只有一个键」,并把三键同义列为回归。

backend/tests 全量 502 passed / 1 skipped;bash -n 两个脚本通过;
docker compose config 只有一个服务 app,端口映射与 APT_MIRROR 注入均已核对。
2026-11-05 18:44:30 +08:00
mula.liu 890f1ee589 模型配置全部交给数据库,.env 只管进程参数;media 从库里搬出来单独一个挂载点
上一版把容器收成一个之后,剩下的口径不一致是「模型配在哪」有两处说法:
.env 里能写 COMFYUI_BASE_URL / VIDEO_PROVIDER / TTS_*,模型中心页面也能改,
而运行时 config_json 优先——于是"改了没生效"和"到底哪条说了算"变成日常问题。
搬家的判据写成一句话放进工程规范:**换模型要不要重启进程**。要,就说明它站错了队。
另外三条理由:① 换 GPU 机是日常操作,不该要求改 .env 再 up --force-recreate;
② API / worker / beat 三个进程必须读同一份模型事实,写 .env 就是三份;
③ 地址与 Key 进库才有审计(谁改的、什么时候)与探测记录。
media 分家是同一批的诉求:产物只涨不跌,会长到几十上百 GB,迟早要单独挪大盘、
做增量备份、被 rsync 与剪辑软件直接读,和"一个不能写坏的 SQLite"绑在同一个挂载点
就得整目录停服拷走。代价说清楚:备份清单从一条变两条。

改动
   · 划界:.env / .env.example 里 VIDEO_* / COMFYUI_* / TTS_* 一律清零(脚本核对过,
     43 个键全部对应 Settings 字段或 compose 插值键,无未知键、无模型键),模板头部
     写明"为什么这里没有模型配置"与新的排障口径(先去页面点 🔌 探测)。补回四个
     原本漏在模板外的进程参数 FFMPEG_BIN/FFPROBE_BIN/QC_VISUAL_*/QC_ASR_ENABLED。
   · Dockerfile / docker-compose.yml / docker-compose.scale.yml:MEDIA_ROOT 从
     /app/data/media 改成 /app/media 并新增 ./media 挂载;worker 同步挂两个目录
     (否则「worker 写完了页面看不到」),beat 不读写产物所以不挂;compose 里删掉
     COMFYUI_BASE_URL 透传,注释说明"去模型中心改 base_url,改完即生效"。
   · 后端三处悄悄降级要一起清掉,否则 env 一空就把真实默认位打回 Mock:
     api/system.py 不再用 settings.video_provider/tts_provider 覆盖页面默认位;
     services/audio.py 的 resolve_tts_spec 候选去掉 settings.tts_provider(未设供应商的
     声线会静默 Mock 配音,只有听成片才发现);providers/registry.py 的 _dedupe_defaults
     改按「真实模型 > 启用 > 登记顺序」裁决,两条 mock 行的 is_default 交给
     _has_real_spec 闸门而不是 env。config.py 的模型字段保留为代码级兜底并写明两个用处。
   · 两个启停脚本原来都是 curl .env 里的 COMFYUI_BASE_URL 探活——现在探的是废弃地址,
     绿字反而误导:dev.sh / server.sh 的 status 改成登录取 /api/providers,
     把库里在册且启用的 base_url 去重后逐个探(comfy 探 /system_stats)。
     dev.sh 顺带修两处历史问题:/api/providers 在 AUTH_ENABLED=true 下 401 被打印成
     "模型注册表读取失败"(现在先登录);非 2xx 被 urllib 当异常抛,LLM 根路径 404
     会误判 unreachable(有 HTTP 应答即算机器活着,真可用性以页面探测为准)。env_value
     随之无人引用,两个脚本各删一份。
   · 文档:README §3.2 挂载表 3 行→4 行(含"少挂 media 会怎样")+ 备份清单两条、
     「常用改动」表把 ComfyUI 一行改成页面操作、§4.0 重写(事实源 + 三条理由 +
     三种接入路径 + COMFYUI_BASE_URL 逃生门 + 排障顺序);工程规范 §5 加"配置分两层"、
     硬约束 #3 与数据边界表同步;deploy.sh / dev.sh 提示语同步。

验证(真跑)
   · 全量后端用例 502 passed / 1 skipped;conftest 新增钉住 COMFYUI_BASE_URL,
     否则 comfyui 三条不登记,断言会跟着开发机 .env 漂(这正是删完 .env 才暴露的隐性污染)。
   · HOST_PORT=8010 docker compose up -d --build → 12 秒 healthy;容器里没有任何模型 env,
     /api/providers 仍是 8 条、默认位四条全真(comfyui/minimax-h3 · qwen-image-2.1-turbo ·
     indextts2 · qwen/qwen3.7-plus),默认位是 entrypoint 从 ./scripts/seed 灌进去的。
   · media 挂载双向实测:容器内写 /app/media/_mount_probe.txt → 宿主 media/ 立即可见;
     宿主已有 1.8G 产物经容器读回 200(/media/1/generated/shot-02-task2.mp4 2.8MB video/mp4);
     走真实接口 POST /api/projects/1/assets 上传,落盘 media/1/reference/*.png 并能在页面直出。
   · ./scripts/deploy.sh --check 19 项全绿;seed.py doctor/boundary 通过;
     dev.sh status 与 server.sh status 均正确报出 http://10.100.53.199:9200 reachable、
     dashscope 报 HTTP 404(有应答)。冒烟产生的 media 两个探针文件与 ./data 移入
     .trash/2026-11-05/smoke-media-mount/,宿主库与产物未留垃圾。
2026-11-05 18:18:00 +08:00
mula.liu 9467e1bb97 v 0.1.0 2026-11-01 16:18:07 +08:00