nex_animation/docs
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
..
MiniMaxH3_Spark_性能诊断与优化方案.md v 0.1.0 2026-11-01 16:18:07 +08:00
UI规范.md v 0.1.1 2026-11-05 16:53:24 +08:00
会话工作流整理.md 文档与脚本同步 React+Tailwind:UI 规范增加词汇→原语对照,工程规范补 frontend/src 分层与扩展点,README 目录/构建口径更新 2026-11-01 19:01:03 +08:00
工程规范.md 端口收成一个键 PORT,.env 里的模型说明清零,apt 源也能换 2026-11-05 18:44:30 +08:00