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
|
517720cf62
|
打成 Docker 只留一个容器:前端产物与后端同进程同端口,Postgres/Redis/Celery 收成可选扩容层
compose 原本是六个容器(db/redis/api/worker/beat/web),那是「前后端分离 + 独立 broker」
时代的遗产。这个项目实际跑的是 SQLite + TASK_EXECUTOR=inline(进程内线程池,周期派发交给
app/services/daemon.py 的守护线程),前端产物由 SERVE_FRONTEND=on 让后端一并托管——
就是 scripts/server.sh 在裸机上跑的那套形态。多出来的三个组件在这里只增加故障面:
连不上的 db、没人消费的 broker、「api 起来了 worker 没起所以任务永远 pending」。
新增
· Dockerfile:两段式。node 阶段 npm ci && npm run build(tsc --noEmit 不过就地失败,
比在服务器上炸便宜);运行阶段 python:3.12-slim + apt ffmpeg(时间线合成/抽帧/质检的
硬依赖,缺它的表现是「导出成片一路 500」而不是起不来)。镜像内保持仓库布局
backend/ + scripts/ + frontend/dist:app/config.py 与 scripts/seed.py 都靠 parents[N]
反推根目录,布局一改就是「.env 找不到」「数据集看不见」两类静默失灵。
BASE_IMAGE/NODE_IMAGE/PIP_INDEX_URL/NPM_REGISTRY 全部可 --build-arg 覆盖。
· .dockerignore:刻意排除 scripts/seed —— 加密主密钥不能烘进镜像层,谁拉镜像谁拿到它。
· scripts/docker-entrypoint.sh:首启把挂载进来的部署数据包灌进库(AUTO_SEED=
only-missing|force|off),灌失败只告警不拦启动(缺的只是几条模型配置,页面和 API 是好的);
末尾 exec 让 uvicorn 当 PID 1,docker stop 的 SIGTERM 才传得进去。根目录从脚本自身位置
反推而不是写死 /app:写死会让「数据集存在与否」的判断在换目录时静默变成 False。
· docker-compose.scale.yml:真要多机/多 GPU 才叠这层切回 Postgres + Redis + worker + beat,
页面仍由 app 这一个容器提供(SERVE_FRONTEND 没被动过)。
改动
· docker-compose.yml 重写成单 service:对外只有 HOST_PORT 一个端口(容器内固定 8000,
与 EXPOSE/HEALTHCHECK 对齐),数据三处 bind mount——./data(库+media)、
./scripts/seed:ro(机密)、./models:ro;comfyui 降级成 profile。
· seed.py install 的「目标库已有业务数据」两档模式分开报:覆盖式保持黄色告警,
--only-missing 一行都不动已有数据,而容器每次重启都会走到这里——跑了几天的服务器上
必然有 event_logs,每次都黄一条等于训练运维无视黄条,降级成一行普通提示。
· deploy.sh 必带清单加四个 Docker 文件(现 19 项)、包内排除新增的 /data/;
server.sh 注释里的 docker-compose 指向改成 scale 层;.env.example 新增「Docker 部署」一节;
README §3.2 整段重写(含挂载表、AUTO_SEED 三档、扩容叠加、国内 registry 实测命令)、
§3.4 补「同一份部署包也能直接跑 docker」;工程规范 §1 根目录白名单与 §2 脚本表同步。
验证(真跑,不是纸面推演)
· docker compose config --services = app(默认一个);叠 scale 层 = db redis beat worker app。
· docker build 成功(685MB,本机直连不到 docker.io,改用 swr 镜像源的
python:3.12-slim + node:22-alpine 走通,npm ci 34.8s / vite build 12.7s / ffmpeg 221s)。
· HOST_PORT=8010 docker compose up -d 12 秒到 healthy;首启日志「模型配置:新增 8」
「前端产物已托管:/app/frontend/dist」「执行后端=inline ffmpeg=True」。
· / 与 /projects/3/storyboard 回落同一 index.html;/assets/index-*.js 200/216KB;
/api/nope 是 401 JSON 而不是被 SPA 兜底成 HTML;登录后 /api/providers 返回 8 条配置 +
四个默认位;/app/scripts/seed 确认 Read-only file system。
· 把 tts 默认位手工改成 mock 后 restart:日志「保留本机默认位不改」,重启后仍是 mock;
AUTO_SEED=force 时按包覆盖回 comfyui/indextts2。celery 入口与 AUTO_SEED=off 都不灌数据。
· 优雅停止:SIGTERM 后 0s 走完「Shutting down → 内联调度守护线程已停止 → shutdown complete」。
· 开发库 nex_animation.db mtime 纹丝没动;down 之后 ./data 完好;deploy.sh --check 全绿(19 项)。
|
2026-11-05 17:39:12 +08:00 |
mula.liu
|
9614b2d225
|
v 0.1.1
|
2026-11-05 16:53:24 +08:00 |
mula.liu
|
20e8f19eca
|
前端统一收尾:图文手册从 public/help.html 搬成站内 React+Tailwind 页面 /help,SPA 深链回落与未知接口 404 拆成纯函数补自检,新增 ErrorBoundary 兜住分包加载失败
|
2026-11-01 19:25:47 +08:00 |
mula.liu
|
9467e1bb97
|
v 0.1.0
|
2026-11-01 16:18:07 +08:00 |