nex_animation/scripts
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
..
ui v 0.1.1 2026-11-05 16:53:24 +08:00
deploy.sh 模型配置全部交给数据库,.env 只管进程参数;media 从库里搬出来单独一个挂载点 2026-11-05 18:18:00 +08:00
dev.sh 端口按形态分键:HOST_PORT 只管部署对外,BACKEND_PORT/FRONTEND_PORT 只管开发;.env.example 与 compose 去噪音 2026-11-05 19:01:32 +08:00
docker-entrypoint.sh 打成 Docker 只留一个容器:前端产物与后端同进程同端口,Postgres/Redis/Celery 收成可选扩容层 2026-11-05 17:39:12 +08:00
e2e_selfcheck.py v 0.1.0 2026-11-01 16:18:07 +08:00
evidence_prune.py v 0.1.0 2026-11-01 16:18:07 +08:00
seed.py 打成 Docker 只留一个容器:前端产物与后端同进程同端口,Postgres/Redis/Celery 收成可选扩容层 2026-11-05 17:39:12 +08:00
server.sh 端口按形态分键:HOST_PORT 只管部署对外,BACKEND_PORT/FRONTEND_PORT 只管开发;.env.example 与 compose 去噪音 2026-11-05 19:01:32 +08:00