nex_animation/scripts/server.sh

453 lines
24 KiB
Bash
Raw Normal View History

2026-11-01 08:18:07 +00:00
#!/usr/bin/env bash
# ============================================================
# Nex Animation Studio · 服务器部署与运行(单机生产模式)
#
2026-11-05 08:53:24 +00:00
# ./scripts/server.sh install 装依赖 → 构建前端 → 建表 → 体检并导入模型配置与管理员
2026-11-01 08:18:07 +00:00
# ./scripts/server.sh build 只重新构建前端(改了页面时用)
# ./scripts/server.sh start 启动(前端产物由后端一并托管,单进程)
# ./scripts/server.sh stop 停止
# ./scripts/server.sh restart 重启
# ./scripts/server.sh status 端口 / 健康 / 默认模型 / ComfyUI / 数据边界
# ./scripts/server.sh verify 打真实 HTTP 跑一遍 12 节点全流程自检
# ./scripts/server.sh logs 跟踪日志
# ./scripts/server.sh systemd 打印 systemd 单元(交给 root 安装)
#
# 选项:--port N --host ADDR --no-asr --skip-deps --skip-build --db URL
2026-11-05 08:53:24 +00:00
# install 专用:--only-missing(模型配置只补缺)、--allow-drift(体检不过也硬装)
2026-11-01 08:18:07 +00:00
#
# 与 scripts/dev.sh 的分工:dev.sh 面向开发(Vite 热更新 + uvicorn --reload),
# server.sh 面向部署(构建产物 + 不重载 + 首装数据)。两者共用 .local/run 与
# .local/logs,但 pid 名不同(server vs backend/frontend),可以并存,只要端口错开。
#
2026-11-05 08:53:24 +00:00
# 四个必须写在这里的为什么:
2026-11-01 08:18:07 +00:00
# 1) 只起一个 uvicorn 进程,绝不加 --workers。TASK_EXECUTOR=inline 时调度守护线程
# 跑在进程内,多 worker 就是 N 份守护线程同时抢同一批任务、重复派发;
打成 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 09:39:12 +00:00
# 要横向扩展请切 TASK_EXECUTOR=celery 并另起 worker
# (容器形态见 docker-compose.scale.yml,裸机形态见 README §3.2 末尾的 celery 命令)。
2026-11-01 08:18:07 +00:00
# 2) 前端产物由后端托管(SERVE_FRONTEND=on),所以对外只有一个端口,
# 反向代理只需转发一处,/api、/media、/docs 与页面同源,不再有 CORS 与代理漂移。
# 3) 首装顺序是「建表 + 灌数据 → 再启动服务」。先启动也能跑,但应用首启会自己
# 生成一把模型主密钥、把 mock 播成默认,导入时就得再纠正一次默认位。
2026-11-05 08:53:24 +00:00
# 4) 灌数据之前先体检。部署包里的 scripts/seed/*.json 是某天的快照,代码是活水:
# 快照落后时代码新增的能力位(例如 IndexTTS2 的 voice_instruct)不会报错,
# 只会让功能在页面上凭空消失。`seed.py install` 因此先跑 doctor 再写库,
# 不过就停住——install 一旦跑过就改掉了表结构与默认位,回不到原样。
2026-11-01 08:18:07 +00:00
# ============================================================
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
RUN_DIR="$ROOT/.local/run"
LOG_DIR="$ROOT/.local/logs"
PYBIN="$ROOT/.venv/bin/python"
NAME=server
端口按形态分键: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 11:01:32 +00:00
env_value() { # 从仓库根 .env 读一个键(最后一行为准;去引号、去随行注释、去尾部空白)
端口收成一个键 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 10:44:30 +00:00
[ -f "$ROOT/.env" ] || return 0
端口按形态分键: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 11:01:32 +00:00
sed -n "s/^[[:space:]]*$1=//p" "$ROOT/.env" | tail -1 \
| sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//' | tr -d '\r"'"'"'' || true
端口收成一个键 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 10:44:30 +00:00
}
2026-11-01 08:18:07 +00:00
HOST="${NEX_HOST:-0.0.0.0}"
端口按形态分键: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 11:01:32 +00:00
# 部署形态的对外端口只有一个键:HOST_PORT(Docker 的端口映射、裸机监听的都读它)。
# 开发态的 BACKEND_PORT / FRONTEND_PORT 是另一码事,别混用(见 .env.example 的端口一节)。
# 取值优先级:命令行 --port > 环境变量 HOST_PORT/PORT > .env 的 HOST_PORT > 8000。
# 回读 .env 是有意的:.env 是运维唯一被要求编辑的文件,写进去的键必须真的生效,
# 否则表现就是「.env 明明改了 9000,服务还在 8000」。
PORT="${HOST_PORT:-${PORT:-$(env_value HOST_PORT)}}"
PORT="${PORT:-$(env_value PORT)}" # 旧键兼容:上一版模板这里叫 PORT
2026-11-01 08:18:07 +00:00
PORT="${PORT:-8000}"
ASR_MODEL="$ROOT/models/asr/ggml-small.bin"
依赖下载点全部配国内源,并修掉「镜像里没有中文字体」这个字幕坑 用户诉求是「镜像已有,其它依赖考虑国内加速」。先把全链路的外部下载点摸了一遍, 结论:**构建镜像不需要 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 11:36:32 +00:00
# ---- 依赖下载源:默认国内源,优先级 环境变量 > .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}"
2026-11-01 08:18:07 +00:00
WANT_ASR=1
SKIP_DEPS=0
SKIP_BUILD=0
2026-11-05 08:53:24 +00:00
SEED_ONLY_MISSING=0 # install:模型配置只补缺,不动服务器上已调好的同名模型
SEED_ALLOW_DRIFT=0 # install:数据体检报 error 也继续装(逃生门,默认关)
2026-11-01 08:18:07 +00:00
EXPLICIT_DB="${DATABASE_URL:-}"
if [ -t 1 ]; then C_G=$'\033[32m'; C_Y=$'\033[33m'; C_R=$'\033[31m'; C_B=$'\033[36m'; C_D=$'\033[2m'; C_0=$'\033[0m'
else C_G=""; C_Y=""; C_R=""; C_B=""; C_D=""; C_0=""; fi
ok() { printf ' %sok%s %s\n' "$C_G" "$C_0" "$*"; }
info() { printf ' %s\n' "$*"; }
warn() { printf ' %s!%s %s\n' "$C_Y" "$C_0" "$*"; }
die() { printf ' %sXX%s %s\n' "$C_R" "$C_0" "$*" >&2; exit 1; }
head2() { printf '\n%s%s%s\n' "$C_B" "$*" "$C_0"; }
pid_of() { [ -f "$RUN_DIR/$NAME.pid" ] && cat "$RUN_DIR/$NAME.pid" 2>/dev/null || true; }
alive() { local p="${1:-}"; [ -n "$p" ] && kill -0 "$p" 2>/dev/null; }
port_pids() { lsof -nP -iTCP:"$1" -sTCP:LISTEN -t 2>/dev/null | tr '\n' ' ' | sed 's/[[:space:]]*$//' || true; }
# 独立会话里起进程(同 dev.sh:`cmd &` 会被启动它的终端一起带走,SSH 断开即挂)
spawn() {
mkdir -p "$RUN_DIR" "$LOG_DIR"
local pid
pid="$("$PYBIN" - "$LOG_DIR/$NAME.log" "$ROOT" "$@" <<'PY'
import subprocess, sys
log_path, cwd, cmd = sys.argv[1], sys.argv[2], sys.argv[3:]
log = open(log_path, "ab", buffering=0)
print(subprocess.Popen(cmd, stdin=subprocess.DEVNULL, stdout=log, stderr=log,
cwd=cwd, start_new_session=True, close_fds=True).pid)
PY
)"
printf '%s\n' "$pid" > "$RUN_DIR/$NAME.pid"
printf '%s\n' "$pid"
}
wait_http() { local url="$1" limit="${2:-120}" i=0
while [ "$i" -lt "$limit" ]; do
curl -fsS --max-time 2 -o /dev/null "$url" 2>/dev/null && return 0
sleep 1; i=$((i + 1))
done; return 1; }
# ------------------------------------------------------------------ install
install_backend_deps() {
head2 "后端依赖"
command -v python3 >/dev/null || die "缺少 python3(需要 3.11+)"
if [ ! -x "$PYBIN" ]; then
info "创建虚拟环境并安装依赖(首次 1~2 分钟)…"
python3 -m venv "$ROOT/.venv" || die "venv 创建失败(Debian/Ubuntu 需 apt install python3-venv)"
依赖下载点全部配国内源,并修掉「镜像里没有中文字体」这个字幕坑 用户诉求是「镜像已有,其它依赖考虑国内加速」。先把全链路的外部下载点摸了一遍, 结论:**构建镜像不需要 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 11:36:32 +00:00
"$PYBIN" -m pip install -q -i "$PIP_INDEX" --upgrade pip
2026-11-01 08:18:07 +00:00
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"
依赖下载点全部配国内源,并修掉「镜像里没有中文字体」这个字幕坑 用户诉求是「镜像已有,其它依赖考虑国内加速」。先把全链路的外部下载点摸了一遍, 结论:**构建镜像不需要 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 11:36:32 +00:00
"$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})"
2026-11-01 08:18:07 +00:00
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
依赖下载点全部配国内源,并修掉「镜像里没有中文字体」这个字幕坑 用户诉求是「镜像已有,其它依赖考虑国内加速」。先把全链路的外部下载点摸了一遍, 结论:**构建镜像不需要 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 11:36:32 +00:00
# 中文字形: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
2026-11-01 08:18:07 +00:00
}
build_frontend() {
head2 "前端构建"
command -v npm >/dev/null || die "缺少 npm(Node 18+)"
依赖下载点全部配国内源,并修掉「镜像里没有中文字体」这个字幕坑 用户诉求是「镜像已有,其它依赖考虑国内加速」。先把全链路的外部下载点摸了一遍, 结论:**构建镜像不需要 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 11:36:32 +00:00
(cd "$ROOT/frontend" && { [ -d node_modules ] || npm ci --registry "$NPM_REGISTRY" --no-audit --no-fund; } && npm run build) \
2026-11-01 08:18:07 +00:00
> "$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 ' ') 个文件)"
}
fetch_asr_model() {
head2 "台词听写模型(whisper.cpp)"
if [ ! -x "$(command -v whisper-cli || true)" ] && [ ! -x "$(command -v whisper || true)" ]; then
warn "未安装 whisper-cli:台词听写质检(prompt_leak)不生效,其余功能不受影响"
info " macOS: brew install whisper-cpp Debian/Ubuntu: 从源码构建 https://github.com/ggml-org/whisper.cpp"
return 0
fi
if [ -f "$ASR_MODEL" ]; then ok "已存在 $(basename "$ASR_MODEL")($(du -sh "$ASR_MODEL" | cut -f1))"; return 0; fi
[ "$WANT_ASR" = 1 ] || { info "按 --no-asr 跳过(台词听写质检需要它)"; return 0; }
info "下载 ggml-small.bin(约 465MB,只下一次)…"
mkdir -p "$(dirname "$ASR_MODEL")"
curl -fL --retry 3 -o "$ASR_MODEL.tmp" "$ASR_URL" || die "下载失败:$ASR_URL"
mv "$ASR_MODEL.tmp" "$ASR_MODEL"
ok "$ASR_MODEL"
}
seed_data() {
head2 "表结构与初始数据"
if [ ! -d "$ROOT/scripts/seed" ]; then
# 从 git 克隆(而不是从部署包解压)时没有这个目录:不是错误,
前端四项调整:输入框去掉光晕、账号菜单收口、逐页删开发期说明书、登录页重做成左右分栏 用户这一轮提了四条,其中三条是同一件事的三个面——**界面上残留着写给开发者自己的话**。 逐条落地的口径与取舍: **1)所有输入框聚焦时的蓝色外框** 量出来其实是三层叠在一起:antd 组件 token 的 `activeShadow`(2px 主色光晕)、 `genFocusStyle` 画的 `outline`、站内 `app.css` 给自绘表面准备的全站 `:focus-visible` 兜底。 第二层没有独立 token,而它依赖的 `lineWidthFocus` 还被 Upload 拖拽区复用,动 token 会连带改上传框, 所以分两刀收:`theme/antd.ts` 关 token(`Input`/`InputNumber` 的 `activeShadow` = `none`、 `Select.activeOutlineColor` = `transparent`),`styles/app.css` 用 `:where(...):focus-visible { outline: none }` 关那圈 outline——用 `:where()` 是为了把特异度归零, 它只是一份选择器清单而不是新加一层优先级,将来谁要恢复焦点环不必先赢过一条 `!important` (app.css 本身不在 `@layer` 里,压得住被 Tailwind 放进 `@layer antd` 的那份,本来就不需要 `!important`)。 **焦点指示没有被删**:antd 的 `activeBorderColor` + 加粗边框仍在,键盘用户看得见焦点; 自绘表面继续吃全站那条兜底。实测聚焦 `#login-user`:`box-shadow: none`、`outline: none 3px`、 `border-color` 浅 rgb(22,119,255) / 深 rgb(22,104,220)。 **2)账号胶囊:菜单去重、项上不留副标题** 「设置新密码」和「我的账号」是同一件事,且首启时登录页已经直接把人的带到 `/account?must=1`, 重复排队只让菜单变长——删掉,待办语义留着头像上的 Badge 红点。 菜单项不再写「账号信息 · 密码 · 登录设备」这类预演式说明;顺手把胶囊第二行的 `第 N 次登录` 也去了:那是「用户管理」表格里逐人登记的数据,挂在人人都要看的顶栏里等于把统计搬进导航。 现在菜单就是三项:我的账号 / 用户管理 / 退出登录。 **3)逐页去开发时冗余说明**(`Dashboard` / `AssetLibrary` / `ModelCenter` / `AgentConsole` / `project/{Library,Overview,Storyboard,Timeline,Review,Delivery}` / `ProjectBriefDrawer`) 三类处置,已写进 UI规范 §14 G2: - 常驻说明书删掉可见文字,信息进 `title`/`desc`:IndexTTS2 那四行论文式介绍(两处重复, 含「下面这条预告会说清楚:」)、总控台「期间页面不会推进,属正常现象」; - 开发者口径翻成「会怎样」:ffmpeg libass 提示只留降级后果,`FFMPEG_BIN` / `brew install ffmpeg-full` / 当前探测路径收进 `title`;`Delivery` 卡头「媒体由后端 `/media` 直出,下载走 `/api/exports/:id/download`」整条删; 「每一站的汇总状态由它覆盖的那几个节点折算而来」→「点一行直接跳到对应环节」; - 内部词不许漏到版面:`mock/Mock` → 站内既有的**演练通道**(四处)、「未匹配的列在 `unmatched_images`」 → 翻成人话;**一个物件只有一个名字**,`/models` 曾同时叫「模型中心 / 模型控制台 / 调度中心 → 模型中心」, 全站统一成侧栏那一项的写法 **模型管理中心**(含 `.env` 注释、`dev.sh`/`server.sh`/`seed.py` 的引导语、 后端四条给用户的报错文案、README、docs、探针页面名),并修掉不存在的入口路径「调度中心 → 模型中心」。 有意保留:单位与取值口径的括号(`(秒)(毫秒)(可选)(0=自动)(dB)`——读数不该依赖悬停)、 条件出现的 `Notice`/`LineHint`/`ErrorText`、`confirmAction` 的 `desc`、`Stat hint`、`nav.hint`、 `PageHead sub`(kit 既定槽位的一句话职责说明)、`Help.tsx` 整页(登记在册的产品手册)。 配套给 `OptionGrid` 单开 `labelTitle`,让组标签的括号补充有地方去而不额外占一行。 **4)登录页重做**(UI规范新增 §13.4) 左右分栏:左栏 `w-[46%] max-w-[620px]` 写平台自述(品牌行 →「把一条长视频,做成一条流水线」+ 三条能力点 → 角色可见范围),底色用 `color-mix` 把主色掺进 `color-bg-layout`,**零新 hex**; 右栏卡片保留原生 `<form>` 包在 `<Panel>` 外(Enter 提交与密码自动填充都挂在 form 上)。 窄于 `lg` 左栏整列收起,品牌行回到卡片顶部,任何宽度都认得出登的是哪个系统。 去掉后端下发的种子账号预填(`login_hint` 字段本身保留,`test_auth.py` 与 `e2e_selfcheck.py` 还在用它判首启), placeholder 回到「用户名」「密码」;新增**记住我**:键 `nex-login`,账号+口令一起记一起清 (只清口令留账号的话勾选框就不算数了),只在登录成功后落盘,取消勾选当场 `writeLocal(key, null)`, 默认不勾(本机明文口令)。 文档同步:UI规范 §8.4(`labelTitle`)、§9.3(焦点轮廓三层口径)、§13.4(登录页)、 §14 G2(三类处置 + 一个物件一个名字)与 §14 例外登记(登录页左栏、`Help.tsx` 整页豁免); README 鉴权一节补登录页与记住我;命名统一顺带扫了 `.env.example` / 三个脚本 / 后端文案。 验证:`npx tsc --noEmit`、`npm run build` 全绿;`node scripts/ui/classaudit.mjs` 七道闸门 0/0/0/0/0/0/0; 后端 + 前端起在 :8010/:5199 后跑完 §15 全部探针,退出码全 0——visualcheck 1440×明暗 15 路由 (console 0 / HTTP 失败 0 / 断言 0)、tableaudit 0、gridcheck 0、rhythmcheck 0、tagcheck 0/0、 btnrowcheck 0(413 组)、aligncheck 0、symmetrycheck 0、feedbackcheck 通过、footercheck 0(30 处吸底条)、 btnclustercheck 0(159 簇);gateprobe 11/11 反向验证;`pytest -q` 全量 502 passed 1 skipped (后端改了四条用户可见文案,对应 3 处断言同步更新)。记住我三条路径(勾上存 / 不勾清空 / 取消即清)实测过。
2026-11-05 14:09:16 +00:00
# 应用首启会自己建表、播 mock、建 admin/admin1234,只是要在模型管理中心重配一遍。
2026-11-01 08:18:07 +00:00
warn "没有 scripts/seed/:跳过数据导入,服务器将用 mock 模型 + admin/admin1234 起步"
return 0
fi
2026-11-05 08:53:24 +00:00
# 体检不在这层重复实现:seed.py install 自己会先量包(列 / 适配器 / 能力位 /
# 默认位 / 主密钥能否解开包里的密文),量不过就不写库,这里只透传两个开关。
# --only-missing:只补库里没有的模型,不覆盖这台机器上已经调好的端点与参数
# (场景:同一台服务器换新包,想带上开发机新增的模型);
# --allow-drift :体检报 error 也照装,给「服务器代码比数据集新、但确认无碍」留门。
local -a seed_args=()
[ "$SEED_ONLY_MISSING" = 1 ] && seed_args+=(--only-missing)
[ "$SEED_ALLOW_DRIFT" = 1 ] && seed_args+=(--allow-drift)
"$PYBIN" "$ROOT/scripts/seed.py" install ${seed_args[@]+"${seed_args[@]}"} \
|| die "导入模型配置与管理员失败(多半是体检没过:上面每条 error 都写了怎么修)"
2026-11-01 08:18:07 +00:00
info "${C_D}数据边界:表结构 + 模型配置 + 管理员。项目/镜头/媒体不在部署包里,服务器从空库开始。${C_0}"
2026-11-05 08:53:24 +00:00
"$PYBIN" "$ROOT/scripts/seed.py" boundary || true
2026-11-01 08:18:07 +00:00
}
打成 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 09:39:12 +00:00
# 单机 .env:不能直接 cp .env.example —— 那份模板默认给的是 Postgres + Redis +
# TASK_EXECUTOR=celery(只有 docker-compose.scale.yml 那套才有 db/redis),照抄到一台
# 裸机上会因为连不上 db 而起不来;server.sh 承诺的是「一台机器一条命令跑起来」,
# 所以写 SQLite + inline —— 和 docker-compose.yml 的默认单容器形态是同一份配置。
2026-11-01 08:18:07 +00:00
ensure_env() {
[ -f "$ROOT/.env" ] && { ok ".env 就绪"; return 0; }
cat > "$ROOT/.env" <<'ENV'
# Nex Animation Studio · 单机部署配置(由 scripts/server.sh install 生成)
# 改完重启生效:./scripts/server.sh restart
前端四项调整:输入框去掉光晕、账号菜单收口、逐页删开发期说明书、登录页重做成左右分栏 用户这一轮提了四条,其中三条是同一件事的三个面——**界面上残留着写给开发者自己的话**。 逐条落地的口径与取舍: **1)所有输入框聚焦时的蓝色外框** 量出来其实是三层叠在一起:antd 组件 token 的 `activeShadow`(2px 主色光晕)、 `genFocusStyle` 画的 `outline`、站内 `app.css` 给自绘表面准备的全站 `:focus-visible` 兜底。 第二层没有独立 token,而它依赖的 `lineWidthFocus` 还被 Upload 拖拽区复用,动 token 会连带改上传框, 所以分两刀收:`theme/antd.ts` 关 token(`Input`/`InputNumber` 的 `activeShadow` = `none`、 `Select.activeOutlineColor` = `transparent`),`styles/app.css` 用 `:where(...):focus-visible { outline: none }` 关那圈 outline——用 `:where()` 是为了把特异度归零, 它只是一份选择器清单而不是新加一层优先级,将来谁要恢复焦点环不必先赢过一条 `!important` (app.css 本身不在 `@layer` 里,压得住被 Tailwind 放进 `@layer antd` 的那份,本来就不需要 `!important`)。 **焦点指示没有被删**:antd 的 `activeBorderColor` + 加粗边框仍在,键盘用户看得见焦点; 自绘表面继续吃全站那条兜底。实测聚焦 `#login-user`:`box-shadow: none`、`outline: none 3px`、 `border-color` 浅 rgb(22,119,255) / 深 rgb(22,104,220)。 **2)账号胶囊:菜单去重、项上不留副标题** 「设置新密码」和「我的账号」是同一件事,且首启时登录页已经直接把人的带到 `/account?must=1`, 重复排队只让菜单变长——删掉,待办语义留着头像上的 Badge 红点。 菜单项不再写「账号信息 · 密码 · 登录设备」这类预演式说明;顺手把胶囊第二行的 `第 N 次登录` 也去了:那是「用户管理」表格里逐人登记的数据,挂在人人都要看的顶栏里等于把统计搬进导航。 现在菜单就是三项:我的账号 / 用户管理 / 退出登录。 **3)逐页去开发时冗余说明**(`Dashboard` / `AssetLibrary` / `ModelCenter` / `AgentConsole` / `project/{Library,Overview,Storyboard,Timeline,Review,Delivery}` / `ProjectBriefDrawer`) 三类处置,已写进 UI规范 §14 G2: - 常驻说明书删掉可见文字,信息进 `title`/`desc`:IndexTTS2 那四行论文式介绍(两处重复, 含「下面这条预告会说清楚:」)、总控台「期间页面不会推进,属正常现象」; - 开发者口径翻成「会怎样」:ffmpeg libass 提示只留降级后果,`FFMPEG_BIN` / `brew install ffmpeg-full` / 当前探测路径收进 `title`;`Delivery` 卡头「媒体由后端 `/media` 直出,下载走 `/api/exports/:id/download`」整条删; 「每一站的汇总状态由它覆盖的那几个节点折算而来」→「点一行直接跳到对应环节」; - 内部词不许漏到版面:`mock/Mock` → 站内既有的**演练通道**(四处)、「未匹配的列在 `unmatched_images`」 → 翻成人话;**一个物件只有一个名字**,`/models` 曾同时叫「模型中心 / 模型控制台 / 调度中心 → 模型中心」, 全站统一成侧栏那一项的写法 **模型管理中心**(含 `.env` 注释、`dev.sh`/`server.sh`/`seed.py` 的引导语、 后端四条给用户的报错文案、README、docs、探针页面名),并修掉不存在的入口路径「调度中心 → 模型中心」。 有意保留:单位与取值口径的括号(`(秒)(毫秒)(可选)(0=自动)(dB)`——读数不该依赖悬停)、 条件出现的 `Notice`/`LineHint`/`ErrorText`、`confirmAction` 的 `desc`、`Stat hint`、`nav.hint`、 `PageHead sub`(kit 既定槽位的一句话职责说明)、`Help.tsx` 整页(登记在册的产品手册)。 配套给 `OptionGrid` 单开 `labelTitle`,让组标签的括号补充有地方去而不额外占一行。 **4)登录页重做**(UI规范新增 §13.4) 左右分栏:左栏 `w-[46%] max-w-[620px]` 写平台自述(品牌行 →「把一条长视频,做成一条流水线」+ 三条能力点 → 角色可见范围),底色用 `color-mix` 把主色掺进 `color-bg-layout`,**零新 hex**; 右栏卡片保留原生 `<form>` 包在 `<Panel>` 外(Enter 提交与密码自动填充都挂在 form 上)。 窄于 `lg` 左栏整列收起,品牌行回到卡片顶部,任何宽度都认得出登的是哪个系统。 去掉后端下发的种子账号预填(`login_hint` 字段本身保留,`test_auth.py` 与 `e2e_selfcheck.py` 还在用它判首启), placeholder 回到「用户名」「密码」;新增**记住我**:键 `nex-login`,账号+口令一起记一起清 (只清口令留账号的话勾选框就不算数了),只在登录成功后落盘,取消勾选当场 `writeLocal(key, null)`, 默认不勾(本机明文口令)。 文档同步:UI规范 §8.4(`labelTitle`)、§9.3(焦点轮廓三层口径)、§13.4(登录页)、 §14 G2(三类处置 + 一个物件一个名字)与 §14 例外登记(登录页左栏、`Help.tsx` 整页豁免); README 鉴权一节补登录页与记住我;命名统一顺带扫了 `.env.example` / 三个脚本 / 后端文案。 验证:`npx tsc --noEmit`、`npm run build` 全绿;`node scripts/ui/classaudit.mjs` 七道闸门 0/0/0/0/0/0/0; 后端 + 前端起在 :8010/:5199 后跑完 §15 全部探针,退出码全 0——visualcheck 1440×明暗 15 路由 (console 0 / HTTP 失败 0 / 断言 0)、tableaudit 0、gridcheck 0、rhythmcheck 0、tagcheck 0/0、 btnrowcheck 0(413 组)、aligncheck 0、symmetrycheck 0、feedbackcheck 通过、footercheck 0(30 处吸底条)、 btnclustercheck 0(159 簇);gateprobe 11/11 反向验证;`pytest -q` 全量 502 passed 1 skipped (后端改了四条用户可见文案,对应 3 处断言同步更新)。记住我三条路径(勾上存 / 不勾清空 / 取消即清)实测过。
2026-11-05 14:09:16 +00:00
# 模型配置不在这里:库里的配置,页面上在左侧栏「模型管理中心」改,改完即生效,不用重启服务。
端口收成一个键 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 10:44:30 +00:00
端口按形态分键: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 11:01:32 +00:00
# ---- 端口:对外暴露的端口(restart 后生效)----
HOST_PORT=8000
2026-11-01 08:18:07 +00:00
# ---- 存储:单机用 SQLite,媒体落 ./media ----
DATABASE_URL=sqlite:///./nex_animation.db
MEDIA_ROOT=./media
# ---- 执行后端:inline = 进程内线程池,不需要 Redis ----
打成 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 09:39:12 +00:00
# 想横向扩展(多 GPU、多机)再切 celery,并另起 worker/beat,见 docker-compose.scale.yml。
2026-11-01 08:18:07 +00:00
TASK_EXECUTOR=inline
# ---- 对外 ----
# 由后端一并托管前端产物:浏览器只访问一个端口。
SERVE_FRONTEND=on
AUTH_ENABLED=true
LOG_LEVEL=INFO
端口收成一个键 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 10:44:30 +00:00
# ---- 本地听写权重(whisper.cpp 的文件路径,install 时下载)----
2026-11-01 08:18:07 +00:00
ASR_MODEL=models/asr/ggml-small.bin
ENV
前端四项调整:输入框去掉光晕、账号菜单收口、逐页删开发期说明书、登录页重做成左右分栏 用户这一轮提了四条,其中三条是同一件事的三个面——**界面上残留着写给开发者自己的话**。 逐条落地的口径与取舍: **1)所有输入框聚焦时的蓝色外框** 量出来其实是三层叠在一起:antd 组件 token 的 `activeShadow`(2px 主色光晕)、 `genFocusStyle` 画的 `outline`、站内 `app.css` 给自绘表面准备的全站 `:focus-visible` 兜底。 第二层没有独立 token,而它依赖的 `lineWidthFocus` 还被 Upload 拖拽区复用,动 token 会连带改上传框, 所以分两刀收:`theme/antd.ts` 关 token(`Input`/`InputNumber` 的 `activeShadow` = `none`、 `Select.activeOutlineColor` = `transparent`),`styles/app.css` 用 `:where(...):focus-visible { outline: none }` 关那圈 outline——用 `:where()` 是为了把特异度归零, 它只是一份选择器清单而不是新加一层优先级,将来谁要恢复焦点环不必先赢过一条 `!important` (app.css 本身不在 `@layer` 里,压得住被 Tailwind 放进 `@layer antd` 的那份,本来就不需要 `!important`)。 **焦点指示没有被删**:antd 的 `activeBorderColor` + 加粗边框仍在,键盘用户看得见焦点; 自绘表面继续吃全站那条兜底。实测聚焦 `#login-user`:`box-shadow: none`、`outline: none 3px`、 `border-color` 浅 rgb(22,119,255) / 深 rgb(22,104,220)。 **2)账号胶囊:菜单去重、项上不留副标题** 「设置新密码」和「我的账号」是同一件事,且首启时登录页已经直接把人的带到 `/account?must=1`, 重复排队只让菜单变长——删掉,待办语义留着头像上的 Badge 红点。 菜单项不再写「账号信息 · 密码 · 登录设备」这类预演式说明;顺手把胶囊第二行的 `第 N 次登录` 也去了:那是「用户管理」表格里逐人登记的数据,挂在人人都要看的顶栏里等于把统计搬进导航。 现在菜单就是三项:我的账号 / 用户管理 / 退出登录。 **3)逐页去开发时冗余说明**(`Dashboard` / `AssetLibrary` / `ModelCenter` / `AgentConsole` / `project/{Library,Overview,Storyboard,Timeline,Review,Delivery}` / `ProjectBriefDrawer`) 三类处置,已写进 UI规范 §14 G2: - 常驻说明书删掉可见文字,信息进 `title`/`desc`:IndexTTS2 那四行论文式介绍(两处重复, 含「下面这条预告会说清楚:」)、总控台「期间页面不会推进,属正常现象」; - 开发者口径翻成「会怎样」:ffmpeg libass 提示只留降级后果,`FFMPEG_BIN` / `brew install ffmpeg-full` / 当前探测路径收进 `title`;`Delivery` 卡头「媒体由后端 `/media` 直出,下载走 `/api/exports/:id/download`」整条删; 「每一站的汇总状态由它覆盖的那几个节点折算而来」→「点一行直接跳到对应环节」; - 内部词不许漏到版面:`mock/Mock` → 站内既有的**演练通道**(四处)、「未匹配的列在 `unmatched_images`」 → 翻成人话;**一个物件只有一个名字**,`/models` 曾同时叫「模型中心 / 模型控制台 / 调度中心 → 模型中心」, 全站统一成侧栏那一项的写法 **模型管理中心**(含 `.env` 注释、`dev.sh`/`server.sh`/`seed.py` 的引导语、 后端四条给用户的报错文案、README、docs、探针页面名),并修掉不存在的入口路径「调度中心 → 模型中心」。 有意保留:单位与取值口径的括号(`(秒)(毫秒)(可选)(0=自动)(dB)`——读数不该依赖悬停)、 条件出现的 `Notice`/`LineHint`/`ErrorText`、`confirmAction` 的 `desc`、`Stat hint`、`nav.hint`、 `PageHead sub`(kit 既定槽位的一句话职责说明)、`Help.tsx` 整页(登记在册的产品手册)。 配套给 `OptionGrid` 单开 `labelTitle`,让组标签的括号补充有地方去而不额外占一行。 **4)登录页重做**(UI规范新增 §13.4) 左右分栏:左栏 `w-[46%] max-w-[620px]` 写平台自述(品牌行 →「把一条长视频,做成一条流水线」+ 三条能力点 → 角色可见范围),底色用 `color-mix` 把主色掺进 `color-bg-layout`,**零新 hex**; 右栏卡片保留原生 `<form>` 包在 `<Panel>` 外(Enter 提交与密码自动填充都挂在 form 上)。 窄于 `lg` 左栏整列收起,品牌行回到卡片顶部,任何宽度都认得出登的是哪个系统。 去掉后端下发的种子账号预填(`login_hint` 字段本身保留,`test_auth.py` 与 `e2e_selfcheck.py` 还在用它判首启), placeholder 回到「用户名」「密码」;新增**记住我**:键 `nex-login`,账号+口令一起记一起清 (只清口令留账号的话勾选框就不算数了),只在登录成功后落盘,取消勾选当场 `writeLocal(key, null)`, 默认不勾(本机明文口令)。 文档同步:UI规范 §8.4(`labelTitle`)、§9.3(焦点轮廓三层口径)、§13.4(登录页)、 §14 G2(三类处置 + 一个物件一个名字)与 §14 例外登记(登录页左栏、`Help.tsx` 整页豁免); README 鉴权一节补登录页与记住我;命名统一顺带扫了 `.env.example` / 三个脚本 / 后端文案。 验证:`npx tsc --noEmit`、`npm run build` 全绿;`node scripts/ui/classaudit.mjs` 七道闸门 0/0/0/0/0/0/0; 后端 + 前端起在 :8010/:5199 后跑完 §15 全部探针,退出码全 0——visualcheck 1440×明暗 15 路由 (console 0 / HTTP 失败 0 / 断言 0)、tableaudit 0、gridcheck 0、rhythmcheck 0、tagcheck 0/0、 btnrowcheck 0(413 组)、aligncheck 0、symmetrycheck 0、feedbackcheck 通过、footercheck 0(30 处吸底条)、 btnclustercheck 0(159 簇);gateprobe 11/11 反向验证;`pytest -q` 全量 502 passed 1 skipped (后端改了四条用户可见文案,对应 3 处断言同步更新)。记住我三条路径(勾上存 / 不勾清空 / 取消即清)实测过。
2026-11-05 14:09:16 +00:00
warn "已生成单机版 .env(SQLite + inline + 托管前端);模型配置在数据库里,页面「模型管理中心」可改"
2026-11-01 08:18:07 +00:00
}
do_install() {
printf 'Nex Animation Studio · 服务器部署安装(cwd=%s)\n' "$ROOT"
head2 "配置"
ensure_env
[ "$SKIP_DEPS" = 1 ] || install_backend_deps
[ "$SKIP_BUILD" = 1 ] || build_frontend
fetch_asr_model
seed_data
head2 "下一步"
模型配置全部交给数据库,.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 10:17:47 +00:00
info "1) 编辑 .env:只有 DATABASE_URL / MEDIA_ROOT / AUTH_ENABLED 这类进程参数——模型地址不在这里"
2026-11-01 08:18:07 +00:00
info " (模型配置已在导入时随包带过来:$(ls "$ROOT/scripts/seed" 2>/dev/null | tr '\n' ' '))"
前端四项调整:输入框去掉光晕、账号菜单收口、逐页删开发期说明书、登录页重做成左右分栏 用户这一轮提了四条,其中三条是同一件事的三个面——**界面上残留着写给开发者自己的话**。 逐条落地的口径与取舍: **1)所有输入框聚焦时的蓝色外框** 量出来其实是三层叠在一起:antd 组件 token 的 `activeShadow`(2px 主色光晕)、 `genFocusStyle` 画的 `outline`、站内 `app.css` 给自绘表面准备的全站 `:focus-visible` 兜底。 第二层没有独立 token,而它依赖的 `lineWidthFocus` 还被 Upload 拖拽区复用,动 token 会连带改上传框, 所以分两刀收:`theme/antd.ts` 关 token(`Input`/`InputNumber` 的 `activeShadow` = `none`、 `Select.activeOutlineColor` = `transparent`),`styles/app.css` 用 `:where(...):focus-visible { outline: none }` 关那圈 outline——用 `:where()` 是为了把特异度归零, 它只是一份选择器清单而不是新加一层优先级,将来谁要恢复焦点环不必先赢过一条 `!important` (app.css 本身不在 `@layer` 里,压得住被 Tailwind 放进 `@layer antd` 的那份,本来就不需要 `!important`)。 **焦点指示没有被删**:antd 的 `activeBorderColor` + 加粗边框仍在,键盘用户看得见焦点; 自绘表面继续吃全站那条兜底。实测聚焦 `#login-user`:`box-shadow: none`、`outline: none 3px`、 `border-color` 浅 rgb(22,119,255) / 深 rgb(22,104,220)。 **2)账号胶囊:菜单去重、项上不留副标题** 「设置新密码」和「我的账号」是同一件事,且首启时登录页已经直接把人的带到 `/account?must=1`, 重复排队只让菜单变长——删掉,待办语义留着头像上的 Badge 红点。 菜单项不再写「账号信息 · 密码 · 登录设备」这类预演式说明;顺手把胶囊第二行的 `第 N 次登录` 也去了:那是「用户管理」表格里逐人登记的数据,挂在人人都要看的顶栏里等于把统计搬进导航。 现在菜单就是三项:我的账号 / 用户管理 / 退出登录。 **3)逐页去开发时冗余说明**(`Dashboard` / `AssetLibrary` / `ModelCenter` / `AgentConsole` / `project/{Library,Overview,Storyboard,Timeline,Review,Delivery}` / `ProjectBriefDrawer`) 三类处置,已写进 UI规范 §14 G2: - 常驻说明书删掉可见文字,信息进 `title`/`desc`:IndexTTS2 那四行论文式介绍(两处重复, 含「下面这条预告会说清楚:」)、总控台「期间页面不会推进,属正常现象」; - 开发者口径翻成「会怎样」:ffmpeg libass 提示只留降级后果,`FFMPEG_BIN` / `brew install ffmpeg-full` / 当前探测路径收进 `title`;`Delivery` 卡头「媒体由后端 `/media` 直出,下载走 `/api/exports/:id/download`」整条删; 「每一站的汇总状态由它覆盖的那几个节点折算而来」→「点一行直接跳到对应环节」; - 内部词不许漏到版面:`mock/Mock` → 站内既有的**演练通道**(四处)、「未匹配的列在 `unmatched_images`」 → 翻成人话;**一个物件只有一个名字**,`/models` 曾同时叫「模型中心 / 模型控制台 / 调度中心 → 模型中心」, 全站统一成侧栏那一项的写法 **模型管理中心**(含 `.env` 注释、`dev.sh`/`server.sh`/`seed.py` 的引导语、 后端四条给用户的报错文案、README、docs、探针页面名),并修掉不存在的入口路径「调度中心 → 模型中心」。 有意保留:单位与取值口径的括号(`(秒)(毫秒)(可选)(0=自动)(dB)`——读数不该依赖悬停)、 条件出现的 `Notice`/`LineHint`/`ErrorText`、`confirmAction` 的 `desc`、`Stat hint`、`nav.hint`、 `PageHead sub`(kit 既定槽位的一句话职责说明)、`Help.tsx` 整页(登记在册的产品手册)。 配套给 `OptionGrid` 单开 `labelTitle`,让组标签的括号补充有地方去而不额外占一行。 **4)登录页重做**(UI规范新增 §13.4) 左右分栏:左栏 `w-[46%] max-w-[620px]` 写平台自述(品牌行 →「把一条长视频,做成一条流水线」+ 三条能力点 → 角色可见范围),底色用 `color-mix` 把主色掺进 `color-bg-layout`,**零新 hex**; 右栏卡片保留原生 `<form>` 包在 `<Panel>` 外(Enter 提交与密码自动填充都挂在 form 上)。 窄于 `lg` 左栏整列收起,品牌行回到卡片顶部,任何宽度都认得出登的是哪个系统。 去掉后端下发的种子账号预填(`login_hint` 字段本身保留,`test_auth.py` 与 `e2e_selfcheck.py` 还在用它判首启), placeholder 回到「用户名」「密码」;新增**记住我**:键 `nex-login`,账号+口令一起记一起清 (只清口令留账号的话勾选框就不算数了),只在登录成功后落盘,取消勾选当场 `writeLocal(key, null)`, 默认不勾(本机明文口令)。 文档同步:UI规范 §8.4(`labelTitle`)、§9.3(焦点轮廓三层口径)、§13.4(登录页)、 §14 G2(三类处置 + 一个物件一个名字)与 §14 例外登记(登录页左栏、`Help.tsx` 整页豁免); README 鉴权一节补登录页与记住我;命名统一顺带扫了 `.env.example` / 三个脚本 / 后端文案。 验证:`npx tsc --noEmit`、`npm run build` 全绿;`node scripts/ui/classaudit.mjs` 七道闸门 0/0/0/0/0/0/0; 后端 + 前端起在 :8010/:5199 后跑完 §15 全部探针,退出码全 0——visualcheck 1440×明暗 15 路由 (console 0 / HTTP 失败 0 / 断言 0)、tableaudit 0、gridcheck 0、rhythmcheck 0、tagcheck 0/0、 btnrowcheck 0(413 组)、aligncheck 0、symmetrycheck 0、feedbackcheck 通过、footercheck 0(30 处吸底条)、 btnclustercheck 0(159 簇);gateprobe 11/11 反向验证;`pytest -q` 全量 502 passed 1 skipped (后端改了四条用户可见文案,对应 3 处断言同步更新)。记住我三条路径(勾上存 / 不勾清空 / 取消即清)实测过。
2026-11-05 14:09:16 +00:00
info " 换 GPU 机 / 改模型参数:登录后进左侧栏「模型管理中心」改 base_url 并点 🔌 探测"
2026-11-01 08:18:07 +00:00
info "2) ./scripts/server.sh start"
info "3) 浏览器打开 $BASE,用部署包里的管理员登录,随后立刻改密码"
info "4) ./scripts/server.sh verify # 用 mock/真实模型跑一遍全流程自检"
}
# ------------------------------------------------------------------ 运行
start_server() {
head2 "启动 :$PORT"
local pid busy
pid="$(pid_of)"
if alive "$pid"; then ok "已在运行 pid=$pid(跳过启动)"; return 0; fi
busy="$(port_pids "$PORT")"
[ -z "$busy" ] || die "端口 $PORT 被进程 $busy 占用;先 ./scripts/server.sh stop 或 --port 换端口"
[ -x "$PYBIN" ] || die "缺少 .venv:先 ./scripts/server.sh install"
[ -f "$ROOT/frontend/dist/index.html" ] || warn "没有 frontend/dist:本次只提供 API,页面请跑 ./scripts/server.sh build"
# SERVE_FRONTEND=on:由后端托管构建产物(见 backend/app/main.py 的 SPA 挂载)。
# --app-dir 从仓库根启动,.env / media / SQLite 相对路径全部锚定仓库根。
local cmd=(env SERVE_FRONTEND=on "$PYBIN" -m uvicorn app.main:app --app-dir "$ROOT/backend"
--host "$HOST" --port "$PORT")
pid="$(spawn "${cmd[@]}")"
if wait_http "$BASE/health" 120; then
ok "健康检查通过 pid=$pid"
else
tail -30 "$LOG_DIR/$NAME.log" 2>/dev/null || true
die "启动失败(120s 内 /health 未就绪)"
fi
if curl -fsS --max-time 3 -o /dev/null "$BASE/" 2>/dev/null; then
ok "页面 $BASE/"
else
warn "$BASE/ 未返回页面:确认已构建前端且 .env 没把 SERVE_FRONTEND 关掉"
fi
# 深链回落:React Router 用 browser history,/projects/1 在磁盘上没有对应文件,
# 必须回 index.html。这条挂了 = 用户刷新一次页面就 404(见 backend/app/main.py:spa_target)。
if curl -fsS --max-time 3 -o /dev/null "$BASE/projects/1" 2>/dev/null; then
ok "深链回落 $BASE/projects/1(history 模式正常)"
else
warn "$BASE/projects/1 没有回落页面:刷新深链会 404,检查 SERVE_FRONTEND 与 frontend/dist"
fi
# 不存在的接口必须是 JSON 404,不能被 SPA 壳伪装成 200 + HTML(前端会把 HTML 当 JSON 解析)
code="$(curl -s -o /dev/null -w '%{http_code}' --max-time 3 "$BASE/api/__spa_probe__" 2>/dev/null || echo 000)"
[ "$code" = "404" ] && ok "未知接口返回 404(未被 SPA 壳吞掉)" \
|| warn "$BASE/api/__spa_probe__ 返回 $code,期望 404:SPA catch-all 可能吞掉了 API 路径"
2026-11-01 08:18:07 +00:00
head2 "已启动"
info "${C_B}平台${C_0} $BASE/"
info "${C_B}接口${C_0} $BASE/docs"
local lan
lan="$( { iface="$(route -n get default 2>/dev/null | awk '/^[[:space:]]*interface:/{print $2; exit}')"
[ -n "$iface" ] && ipconfig getifaddr "$iface" 2>/dev/null; } || true )"
[ -n "$lan" ] && info "${C_B}局域网${C_0} http://$lan:$PORT/"
info "${C_B}日志${C_0} .local/logs/$NAME.log ${C_D}跟踪:./scripts/server.sh logs${C_0}"
info "${C_B}停止${C_0} ./scripts/server.sh stop"
}
stop_server() {
local pid; pid="$(pid_of)"
alive "$pid" || { rm -f "$RUN_DIR/$NAME.pid"; info "未在运行"; return 0; }
# pid 就是会话组长:按进程组回收,uvicorn 派生的 ffmpeg / whisper 子进程才不会被留下
kill -TERM -- "-$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
local i=0
while alive "$pid" && [ "$i" -lt 30 ]; do sleep 0.5; i=$((i + 1)); done
alive "$pid" && { kill -KILL -- "-$pid" 2>/dev/null || true; warn "已强制结束 pid=$pid"; }
rm -f "$RUN_DIR/$NAME.pid"
ok "已停止(pid=${pid})"
}
status_server() {
head2 "运行状态"
local pid; pid="$(pid_of)"
if alive "$pid"; then
printf ' %srunning%s server :%-6s pid=%s\n' "$C_G" "$C_0" "$PORT" "$pid"
elif [ -n "$(port_pids "$PORT")" ]; then
printf ' %sbusy%s server :%-6s 被本脚本之外的进程占用 (pid=%s)\n' \
"$C_Y" "$C_0" "$PORT" "$(port_pids "$PORT")"
else
printf ' %sstopped%s server :%s\n' "$C_D" "$C_0" "$PORT"
fi
[ -f "$ROOT/frontend/dist/index.html" ] && ok "前端产物 frontend/dist" || warn "前端产物缺失:./scripts/server.sh build"
[ -f "$ASR_MODEL" ] && ok "听写模型 $(basename "$ASR_MODEL")" || warn "听写模型缺失:台词听写质检不生效"
if curl -fsS --max-time 3 -o /dev/null "$BASE/health" 2>/dev/null; then
NEX_BASE="$BASE" "$PYBIN" <<'PY' || true
import os, sys, httpx
模型配置全部交给数据库,.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 10:17:47 +00:00
GREEN, YELLOW, DIM, RESET = (("\033[32m", "\033[33m", "\033[2m", "\033[0m")
if sys.stdout.isatty() else ("", "", "", ""))
2026-11-01 08:18:07 +00:00
base = os.environ["NEX_BASE"].rstrip("/")
# 部署形态默认 AUTH_ENABLED=true,/api/* 要会话;未登录时这里会退化成
# 「HTTP 401 读不到模型」,看不出来是配置没导入还是没登录,所以先登录再读。
模型配置全部交给数据库,.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 10:17:47 +00:00
# 模型端点也在这里探:地址存在 model_specs 表里(不在 .env),页面/数据库说是什么就是什么,
# 以前那种「curl .env 里的 COMFYUI_BASE_URL」现在会探到一个已经不用的旧地址。
2026-11-01 08:18:07 +00:00
c = httpx.Client(base_url=base, timeout=10, trust_env=False)
h = c.get("/health").json()
print(f" executor={h.get('executor')} database={h.get('database')} ffmpeg={h.get('ffmpeg')} "
f"model_specs={h.get('model_specs')} frontend={h.get('frontend')} auth={h.get('auth_enabled')}")
try:
st = c.get("/api/auth/state").json()
if st.get("auth_enabled") and not st.get("authenticated"):
r = c.post("/api/auth/login", json={
"username": os.environ.get("NEX_USER") or (st.get("login_hint") or {}).get("username") or "admin",
"password": os.environ.get("NEX_PASS") or "admin1234"})
if r.status_code != 200:
# 登录不进去多半是首登强制改密没走界面,这里只提示,不阻塞 status
print(f" 模型注册表跳过:登录失败 {r.status_code}(改 NEX_USER/NEX_PASS 后重试)")
sys.exit(0)
模型配置全部交给数据库,.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 10:17:47 +00:00
listing = c.get("/api/providers").json()
for p in listing["providers"]:
2026-11-01 08:18:07 +00:00
if p.get("is_default"):
print(f" [默认] {p['media_type']:6s} {p['provider']}/{p['model']} 可用={p.get('available')}")
模型配置全部交给数据库,.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 10:17:47 +00:00
# 端点连通性:把库里真实用到的地址逐个探一遍(自建 ComfyUI 探 /system_stats)。
# 同一台机器常常同时挂视频/图像/配音三条模型,去重后只探一次。
endpoints = {}
for p in listing["providers"]:
if not p.get("enabled"):
continue
url = str((p.get("config") or {}).get("base_url") or "").rstrip("/")
if url and not p.get("uses_mock"):
endpoints.setdefault(url, []).append(f"{p['provider']}/{p['model']}")
for url, users in sorted(endpoints.items()):
probe = f"{url}/system_stats" if "comfy" in url.lower() else url
try:
c.get(probe, timeout=4)
print(f" {GREEN}reachable{RESET} {url} ← {', '.join(sorted(users))}")
except Exception:
print(f" {YELLOW}unreachable{RESET} {url} ← {', '.join(sorted(users))}"
f" {DIM}(这几条模型真实出片会失败,页面点 🔌 探测看细节){RESET}")
2026-11-01 08:18:07 +00:00
except Exception as exc:
print(f" 模型注册表读取失败:{type(exc).__name__}: {exc}")
PY
else
模型配置全部交给数据库,.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 10:17:47 +00:00
info "${C_D}服务未启动:健康检查、默认模型与模型端点连通性都要等进程起来才能读(地址在库里)${C_0}"
2026-11-01 08:18:07 +00:00
fi
2026-11-05 08:53:24 +00:00
# 数据边界:这台机器上「部署包带来的」与「本机业务跑出来的」各多少行。
# 直接读库而不是打 HTTP——装完还没 start 时也需要知道导入了什么,
# 而且这一眼能回答部署后最常见的问题:「业务数据是不是被我覆盖掉了」。
head2 "数据边界"
"$PYBIN" "$ROOT/scripts/seed.py" boundary || warn "读不到库:先 ./scripts/server.sh install,或 --db 指对连接串"
2026-11-01 08:18:07 +00:00
}
verify_server() {
head2 "全流程自检(真实 HTTP + ffprobe 实测)"
wait_http "$BASE/health" 5 || die "$BASE 没有可用的后端"
NEX_BASE="$BASE" "$PYBIN" "$ROOT/scripts/e2e_selfcheck.py"
}
do_systemd() {
local unit user
user="${SUDO_USER:-$(id -un)}"
cat <<UNIT
# /etc/systemd/system/nex-animation.service
# 安装:sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service
# sudo systemctl daemon-reload && sudo systemctl enable --now nex-animation
[Unit]
Description=Nex Animation Studio
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=$user
WorkingDirectory=$ROOT
EnvironmentFile=$ROOT/.env
# SERVE_FRONTEND 之类已在 .env 里;这里显式再写一次,防止有人把 .env 换成 compose 版
# 前端产物由后端托管,对外一个端口;inline 执行器把调度守护线程跑在进程内,
# 所以只能一个进程——加 --workers 会变成 N 份守护线程重复派发。
ExecStart=$ROOT/.venv/bin/python -m uvicorn app.main:app --app-dir $ROOT/backend --host 0.0.0.0 --port $PORT
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.target
UNIT
}
2026-11-05 08:53:24 +00:00
# 帮助 = 文件头那段注释。取范围靠「第一条 # === 到第二条 # ===」而不是写死行号:
# 上一版是 sed -n '3,30p',头注释每加一行就得回来挪一次数字,很容易忘(deploy.sh 同修)。
usage() { awk '/^# ={10,}/{n++; next} n==1{sub(/^# ?/, ""); print} n>1{exit}' "${BASH_SOURCE[0]}"; }
2026-11-01 08:18:07 +00:00
ACTION=start
while [ $# -gt 0 ]; do
case "$1" in
install|build|start|stop|restart|status|verify|logs|systemd) ACTION="$1" ;;
--port) PORT="${2:?--port 需要端口}"; shift ;;
--host) HOST="${2:?--host 需要地址}"; shift ;;
--db) DATABASE_URL="${2:?--db 需要连接串}"; export DATABASE_URL; shift ;;
--no-asr) WANT_ASR=0 ;;
--skip-deps) SKIP_DEPS=1 ;;
--skip-build) SKIP_BUILD=1 ;;
2026-11-05 08:53:24 +00:00
--only-missing) SEED_ONLY_MISSING=1 ;;
--allow-drift) SEED_ALLOW_DRIFT=1 ;;
2026-11-01 08:18:07 +00:00
-h|--help) usage; exit 0 ;;
*) die "未知参数:$1(./scripts/server.sh --help)" ;;
esac
shift
done
# BASE 必须在解析完参数之后再算:早先算在文件头,`server.sh start --port 8020`
# 会把服务起在 8020、却去健康检查 8000,而那台机器 8000 上另有一个后端,
# 于是「健康检查通过」是个假绿灯。
case "$HOST" in 0.0.0.0|""|::|\[::\]) PROBE_HOST=127.0.0.1 ;; *) PROBE_HOST="$HOST" ;; esac
BASE="http://$PROBE_HOST:$PORT"
# 相对路径(models/asr、media、SQLite 文件名)一律锚到仓库根:
# 从 /etc/systemd 或 ~ 里启动服务时,cwd 不是项目目录,相对路径会指到别处。
cd "$ROOT"
if [ -n "$EXPLICIT_DB" ]; then export DATABASE_URL="$EXPLICIT_DB"; fi
case "$ACTION" in
install) do_install ;;
build) install_backend_deps; build_frontend ;;
start) start_server ;;
stop) stop_server ;;
restart) stop_server; start_server ;;
status) status_server ;;
verify) verify_server ;;
systemd) do_systemd ;;
logs) f="$LOG_DIR/$NAME.log"; [ -f "$f" ] || : > "$f"; exec tail -n 80 -F "$f" ;;
esac