端口按形态分键: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。
main
mula.liu 2026-11-05 19:01:32 +08:00
parent 24978e9843
commit 1a886beca6
6 changed files with 90 additions and 171 deletions

View File

@ -1,116 +1,50 @@
# ============================================================
# Nex Animation Studio · 运行时配置(复制为 .env 后按需修改)
# · .env 是「每台机器一份」的配置:它不进仓库,服务器上的那份由你从本文件复制,
# 跟开发机那份互不影响。部署包也不带它——先 cp 再改,是唯一需要编辑的文件。
# · 应用配置项 = backend/app/config.py 里 Settings 字段的大写下划线形式(多余键忽略)
# · 端口优先级:命令行参数 > 环境变量 > 本文件的 PORT
# · 模型配置不在这里:地址、模型名、步数、超时、并发与限流、单价、默认位都在数据库,
# 页面「调度中心 → 模型中心」,服务器上的初值随部署包 scripts/seed/ 导入
# 复制为 .env 后按需修改(每台机器一份,不进仓库;模型配置在页面「调度中心 → 模型中心」)
# 这份文件只放配置本身,为什么这么配见 README §3(部署)与 docs/工程规范.md §5
# ============================================================
# ---------- 端口 ----------
# 应用对外端口只有一个,三种形态共用:Docker 对外的映射、裸机 server.sh 监听的、开发态的后端
# 都读它。容器内固定监听 8000(与 EXPOSE / HEALTHCHECK 对齐),改这里只改对外映射。
PORT=8000
# 仅开发形态需要第二个端口:Vite 是独立进程,必须和后端错开
FRONTEND_PORT=5173
HOST_PORT=8000 # 部署形态对外暴露的端口:Docker 的映射、裸机 server.sh 的监听(容器内固定 8000)
BACKEND_PORT=8000 # 开发形态:后端 uvicorn(scripts/dev.sh)
FRONTEND_PORT=5173 # 开发形态:前端 Vite(scripts/dev.sh,独立进程,必须与后端错开)
# ---------- Docker 构建与首启(compose 读,应用不读)----------
# AUTO_SEED:首启导入 scripts/seed 数据包的方式 only-missing(默认)| force | off
# APP_DATABASE_URL / APP_MEDIA_ROOT:容器内的库与产物路径,必须落在挂载点里
# (./data ↔ /app/data,./media ↔ /app/media);想改容器里的落点改这两行,
# 改下面的 DATABASE_URL / MEDIA_ROOT 没用——它们会被 compose 覆盖掉。
# AUTO_SEED=only-missing
# APP_DATABASE_URL=sqlite:////app/data/nex_animation.db
# APP_MEDIA_ROOT=/app/media
# 下面这几项 compose 也替你钉死了,单容器形态不用碰:SERVE_FRONTEND=on、TASK_EXECUTOR=inline、
# 以及容器内的 PORT=8000(本文件的 PORT 只决定对外映射到哪个端口)。
# APT_MIRROR=mirrors.tuna.tsinghua.edu.cn # apt 源(ffmpeg 在这一层装),默认官方 deb.debian.org
# BASE_IMAGE=python:3.12-slim
# NODE_IMAGE=node:22-alpine
# PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# NPM_REGISTRY=https://registry.npmmirror.com
# POSTGRES_* / CELERY_CONCURRENCY 只在叠加 docker-compose.scale.yml 时用到
# ---------- 存储 ----------
# 这两行是「不带 compose 裸跑」时的取值(相对路径锚定仓库根);
# Docker 形态下 compose 把它们覆盖成 APP_DATABASE_URL / APP_MEDIA_ROOT 那两个挂载点。
# 产物落在容器可写层的后果是下次重建镜像就没了,所以容器里必须是挂载点内的绝对路径。
DATABASE_URL=sqlite:///./nex_animation.db
MEDIA_ROOT=./media
# ---------- 基础设施 ----------
DATABASE_URL=sqlite:///./nex_animation.db # Docker 形态下 compose 会指到挂载点 ./data
MEDIA_ROOT=./media # 同上,容器内为 ./media 挂载点
MEDIA_URL_PREFIX=/media
CORS_ORIGINS=*
LOG_LEVEL=INFO
# ---------- 鉴权与账号 ----------
# 开启时 /api/* 与 /media/* 都要会话;关掉只适合可信内网(任何人都能裸奔写入)。
AUTH_ENABLED=true
BOOTSTRAP_USERNAME=admin
BOOTSTRAP_PASSWORD=admin1234
# COOKIE_NAME=nex_session
# ---------- 前端托管 + 任务执行后端(默认 = 单容器那一套)----------
# on = 后端一并托管 frontend/dist 并做 SPA history 回落,对外只有一个端口
# inline = 进程内线程池 + 内置派发守护,不需要 Redis
SERVE_FRONTEND=on
# FRONTEND_DIST_DIR= # 留空 = <仓库根>/frontend/dist
TASK_EXECUTOR=inline
# ---------- 任务执行后端 ----------
TASK_EXECUTOR=inline # inline 进程内线程池(无需 Redis);celery 见 docker-compose.scale.yml
INLINE_WORKERS=2
# ---------- 扩容层专用:只在 -f docker-compose.scale.yml 时生效 ----------
# 叠加之后 scale.yml 会用 Postgres + celery 覆盖上面的 DATABASE_URL / TASK_EXECUTOR,
# 独立 worker 与 beat 各起一个容器;不叠加时这些键没人读,所以默认全部注释掉。
# POSTGRES_DB=nexanimation
# POSTGRES_USER=nex
# POSTGRES_PASSWORD=change_this_password
# REDIS_URL=redis://redis:6379/0
# CELERY_BROKER_URL=redis://redis:6379/0
# CELERY_RESULT_BACKEND=redis://redis:6379/1
# CELERY_CONCURRENCY=2
# ---------- 鉴权与账号 ----------
AUTH_ENABLED=true
BOOTSTRAP_USERNAME=admin
BOOTSTRAP_PASSWORD=admin1234 # 库里首个管理员,登录后请立刻改口令
# ---------- 调度节奏 / 重试 / 断点续跑 ----------
DISPATCH_INTERVAL_SECONDS=5
DISPATCH_BATCH_SIZE=32
MAX_SHOT_RETRIES=3
MAX_SHOT_RETRIES=2
MAX_COMPOSE_RETRIES=2
RETRY_BACKOFF_BASE_SECONDS=5
RETRY_BACKOFF_MAX_SECONDS=300
# 僵死判定要比「最慢的正常任务」更宽,否则会把正在跑的镜头抢回来重跑
STALE_RUNNING_SECONDS=900
# 新建一条模型没填限额时的初始值
STALE_RUNNING_SECONDS=1800 # 要比最慢的正常出图更宽,否则会把在跑的镜头抢回来重跑
DEFAULT_PROVIDER_CONCURRENCY=2
DEFAULT_PROVIDER_RPM=30
# ---------- 合成引擎 ----------
# ---------- 合成与质检 ----------
DEFAULT_FPS=24
DEFAULT_WIDTH=1920
DEFAULT_HEIGHT=1080
TARGET_LUFS=-16.0
XFADE_MAX_DURATION_MS=1200
FFMPEG_THREADS=0
FFMPEG_PRESET=medium
FFMPEG_CRF=20
# 留空 = 自动探测(优先挑带 libass 的完整版构建,能烧字幕);填绝对路径可强制指定
# FFMPEG_BIN=
# FFPROBE_BIN=
# ---------- 自动质检阈值 ----------
QC_DURATION_TOLERANCE=0.35
QC_MIN_BITRATE_KBPS=200
QC_BLACK_THRESHOLD=0.98
QC_VISUAL_ENABLED=true
QC_VISUAL_FRAMES=4
QC_VISUAL_REFERENCES=3
QC_VISUAL_WEIGHT=0.4
QC_ASR_ENABLED=true
# 本地听写权重是文件路径,./scripts/server.sh install 会自动下载(--no-asr 跳过)
ASR_MODEL=models/asr/ggml-small.bin
ASR_MODEL=models/asr/ggml-small.bin # 本地听写权重,server.sh install 自动下载
# ---------- 成本台账 ----------
COST_CURRENCY=CNY
# ---------- 上传白名单(一般无需修改)----------
# UPLOAD_IMAGE_EXTENSIONS=.png,.jpg,.jpeg,.webp,.gif,.bmp,.tif,.tiff
# UPLOAD_VIDEO_EXTENSIONS=.mp4,.mov,.webm,.mkv,.m4v,.avi
# UPLOAD_AUDIO_EXTENSIONS=.mp3,.wav,.m4a,.aac,.flac,.ogg,.opus
# UPLOAD_DOC_EXTENSIONS=.txt,.md,.csv,.tsv,.json,.srt,.ass,.vtt,.zip,.docx

View File

@ -290,7 +290,7 @@ cd frontend && npm install && npm run dev # http://localhost:5173
> 校验 `typeof health.status === 'string'`,一旦代理缺失直接抛出可读错误而不是假装健康。
>
> **后端换地址/换端口**:手工起前端用 `NEX_BACKEND=http://127.0.0.1:8010 npm run dev`,无需改代码;
> 用 `./scripts/dev.sh` 的话改 `.env` 里 `PORT` 就行,脚本会把代理目标一起带着走。
> 用 `./scripts/dev.sh` 的话改 `.env` 里 `BACKEND_PORT` 就行,脚本会把代理目标一起带着走。
> **SQLite 路径**的父目录由 `app/db.py` 自动创建,`DATABASE_URL='sqlite://////tmp/nex_ui/ui.db'`
> 可直接使用(注意 SQLite URL 是 6 个斜杠:3 个协议分隔 + 绝对路径根)。
@ -298,18 +298,31 @@ cd frontend && npm install && npm run dev # http://localhost:5173
```bash
cp .env.example .env # 或直接复用开发机那份:compose 会把 .env 整份注入容器
docker compose up -d --build # 只起一个容器 nex-animation,对外只有 .env 里的 PORT(默认 8000)
docker compose up -d --build # 只起一个容器 nex-animation,对外端口 = .env 的 HOST_PORT(默认 8000)
docker compose logs -f app # 首启会打印「导入部署数据包:seed.py install --only-missing」
docker compose ps # STATUS 到 healthy 才算起来(探的是 /health)
```
**`.env` 是「每台机器一份」的文件**:仓库根那份是你开发机的配置(SQLite、Vite 端口、本机口令),
它 gitignored、不在部署包里;服务器上是 `cp .env.example .env` 生成的另一份,**对外的端口就配在
服务器那份 `.env` 的 `PORT=` 一行**,不在 compose 文件里(compose 只是引用它)。compose 读 `.env`
读两遍:先替 `${PORT}` 插值得到 `ports` 映射,再把整份注入容器当环境变量。有两个例外要记住:
容器内监听的 `PORT` 被 compose 钉成 8000(改 `.env` 只改对外映射),而 `DATABASE_URL`、
`MEDIA_ROOT`、`SERVE_FRONTEND`、`TASK_EXECUTOR` 这四行在 `.env` 里改了没用——compose 的
`environment` 覆盖它们,要挪容器内的落点请改 `APP_DATABASE_URL` / `APP_MEDIA_ROOT`。
**`.env` 是「每台机器一份」的文件**:仓库根那份是你开发机的配置(SQLite、开发端口、本机口令),
它 gitignored、不在部署包里;服务器上是 `cp .env.example .env` 生成的另一份。**对外暴露的端口就配在
服务器那份 `.env` 的 `HOST_PORT=` 一行**,不在 compose 文件里(compose 只引用它:先替 `${HOST_PORT}`
插值得到 `ports` 映射,再把整份 `.env` 注入容器当环境变量)。容器内永远监听 8000,改 `HOST_PORT`
改的只是对外的映射,而且**必须重跑 `docker compose up -d`**——`restart` 沿用旧容器配置,不换端口。
`.env` 里还有四行在 Docker 形态下改了没反应:`DATABASE_URL`、`MEDIA_ROOT`、`SERVE_FRONTEND`、
`TASK_EXECUTOR` 被 compose 的 `environment` 覆盖(所以模板里干脆不写后两条,要挪容器内的落点改
`APP_DATABASE_URL` / `APP_MEDIA_ROOT`)。
**端口一共三个键,按形态分,别混用**:
| 键 | 管谁 | 谁读它 |
| --- | --- | --- |
| `HOST_PORT` | **部署形态**对外的端口:Docker 的端口映射、裸机 `server.sh` 的监听 | compose 插值 / `server.sh` 回读 |
| `BACKEND_PORT` | **开发形态**的后端 uvicorn | `dev.sh` 回读(并同步 Vite 代理目标) |
| `FRONTEND_PORT` | **开发形态**的前端 Vite(独立进程,必须与后端错开) | `dev.sh` 回读 |
取值优先级统一是 **命令行参数 > 同名环境变量 > `.env` > 默认值**(`server.sh` 是 `--port`,
`dev.sh` 是 `--backend-port` / `--frontend-port`)。开发机与容器同机时记得错开 `HOST_PORT`,
本仓开发机用的是 `HOST_PORT=8010`,因为 8000 坐着开发后端。
**compose 里的 `comfyui` 服务默认不参与**:它带 `profiles: ["comfy"]`,
`docker compose up -d` 只起 `app` 一个容器(`docker compose config --services` 可验证)。
@ -356,7 +369,7 @@ docker compose up -d
| 想改什么 | 改哪里 |
| --- | --- |
| 对外端口 | **就一个键:`.env` 里的 `PORT`**,Docker 的对外映射、裸机 `server.sh` 的监听、开发态的后端全都读它。容器内固定 8000(与 `EXPOSE`/健康检查对齐),改 `PORT` 改的只是对外的映射;开发态另有一个 `FRONTEND_PORT`,因为 Vite 是独立进程。优先级 **命令行 `--port` > 环境变量 > `.env` > 默认 8000** |
| 对外端口 | **`.env` 里的 `HOST_PORT`**(部署形态:Docker 的映射、裸机 `server.sh` 的监听都读它)。容器内固定 8000,改 `HOST_PORT` 改的只是对外映射,且要重跑 `up -d`;开发形态另用 `BACKEND_PORT` / `FRONTEND_PORT`,详见 §3.2 的端口表 |
| 拉不到 docker.io / 装包慢 | `.env` 或 `--build-arg` 覆盖 `BASE_IMAGE`、`NODE_IMAGE`、`PIP_INDEX_URL`、`NPM_REGISTRY`、`APT_MIRROR`(apt 源,装 ffmpeg 那一层) |
| 换 ComfyUI / 换 GPU 机 | **不在 `.env` 里改**:登录页面「调度中心 → 模型中心」,改那几条模型的 `base_url` 并点 🔌 探测,改完即生效、不用重启。指宿主机写 `http://host.docker.internal:9200`(`extra_hosts` 已备 `host-gateway`),写 `127.0.0.1` 指向的是容器自己 |
| 顺带起一个自建 ComfyUI | `docker compose --profile comfy up -d`(默认**不起**,算力在远端时不用管),再把 `base_url` 指 `http://comfyui:8188` |
@ -424,7 +437,7 @@ React Router 的 history 回退已经处理好(地址栏直接刷 `/projects/3
# ---- 服务器:落地 ----
tar -xzf nex_animation-*.tar.gz && cd nex_animation
./scripts/server.sh install # venv + 依赖 + npm build + 听写模型 + 体检 + 建表灌种子数据
./scripts/server.sh start # 单进程 uvicorn;端口取 .env 的 PORT(默认 :8000,--port 覆盖)
./scripts/server.sh start # 单进程 uvicorn;端口取 .env 的 HOST_PORT(默认 :8000,--port 覆盖)
./scripts/server.sh verify # 图2 全 12 节点真实 HTTP + ffprobe 自检
./scripts/server.sh status # 端口 / 健康 / 默认模型 / ComfyUI 连通性 / 数据边界
sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service \

View File

@ -1,36 +1,18 @@
# =============================================================================
# Nex Animation Studio · 部署编排(单容器整站:后端 + 前端产物 + SQLite + 进程内调度)
# Nex Animation Studio · 单容器部署(后端 + 前端产物 + ffmpeg 在同一个镜像里)
#
# 日常命令:
# 常用命令:
# docker compose up -d --build 首次部署(构建 + 后台启动)
# docker compose logs -f app 看日志(首启会打印「导入部署数据包」那一行)
# docker compose ps 状态(healthy 才算起来)
# docker compose up -d 改了 .env 之后重跑这条:端口映射是在创建容器时定下的,
# restart 沿用旧容器配置,改了 PORT 也不会换端口
# docker compose logs -f app 看日志(首启会打印导入数据包那一行)
# docker compose ps 状态(healthy 才算起来,探的是 /health)
# docker compose up -d 改了 .env 之后重跑这条:restart 沿用旧容器配置,不换端口映射
# docker compose down 停止并删除容器,数据留在 ./data 与 ./media
# 打开 http://localhost:8000 默认账号见 BOOTSTRAP_USERNAME / BOOTSTRAP_PASSWORD
#
# 为什么只有一个服务:库用 SQLite、任务用 TASK_EXECUTOR=inline(进程内线程池 +
# app/services/daemon.py 的派发守护线程),前端产物由后端一并托管,
# 所以不需要 nginx 容器、不需要 Redis、不需要独立 worker/beat。
# 少三个组件就少三类故障面:没有连不上的 db、没有排队没人消费的 broker、
# 没有「api 起来了 worker 没起来所以任务永远 pending」。
# 需要多机 / 多 GPU 扩容时再叠一层(Postgres + Redis + Celery worker + beat):
# docker compose -f docker-compose.yml -f docker-compose.scale.yml up -d --build
#
# 数据分四处 bind mount(都相对本文件,换镜像不动数据):
# ./data SQLite 库(几 MB~几百 MB) ← 唯一会被写坏的目录,值得单独备份
# ./media 出片产物与上传素材(只涨不跌) ← 单独一个挂载点:能整目录挪大盘、
# 能被 rsync/剪辑软件直接读,
# 和库分开才敢单独做备份与迁移
# ./scripts/seed 模型配置 + 加密主密钥 + 管理员 ← gitignored 的机密,所以不进镜像层
# ./models whisper 权重等(可选)
# 容器首启由 scripts/docker-entrypoint.sh 拿 seed 目录把库灌好(AUTO_SEED 控制)——
# 「用哪个模型、地址是什么」就是这么进库的,不是从 .env 读的。
#
# 配置来源:同目录 .env(compose 会替变量插值读它,并整份注入容器)。
# 下面 environment 里点名的键是例外——容器里的路径和宿主机不是一回事,必须覆盖。
# .env 里不再放模型配置(VIDEO_* / COMFYUI_* / TTS_*),换 ComfyUI 地址去页面改。
# 配置来源:同目录 .env(compose 既用它做变量插值,也整份注入容器)。
# 对外端口 = .env 的 HOST_PORT;容器内固定监听 8000(与 EXPOSE / HEALTHCHECK 对齐)。
# 下面 environment 点名的键是例外,容器内的路径与宿主不是一回事,必须覆盖。
# 数据四个 bind mount:./data 库、./media 产物、./scripts/seed 模型配置与主密钥、./models 权重。
# 为什么只要一个容器、模型配置为什么不在这份文件里、扩容层怎么叠:README §3.2 与 §4.0。
# 需要 Docker Compose ≥ v2.24(env_file 的 required: false 写法)。
# =============================================================================
name: nex-animation
@ -40,59 +22,40 @@ services:
build:
context: .
args:
# 基础镜像与 pip/npm 源都可以在 .env 里覆盖:直连 docker.io / npmjs 很慢时先探好再构建
# 源与基础镜像可在 .env 里覆盖,默认值就按国内直连能通的配
BASE_IMAGE: "${BASE_IMAGE:-python:3.12-slim}"
NODE_IMAGE: "${NODE_IMAGE:-node:22-alpine}"
PIP_INDEX_URL: "${PIP_INDEX_URL:-https://pypi.tuna.tsinghua.edu.cn/simple}"
NPM_REGISTRY: "${NPM_REGISTRY:-https://registry.npmmirror.com}"
# apt 源只有装 ffmpeg 这一层用得到;默认官方源,国内服务器直连不动时再覆盖
APT_MIRROR: "${APT_MIRROR:-deb.debian.org}"
image: nex-animation:latest
container_name: nex-animation
restart: unless-stopped
env_file:
- path: .env
required: false # 空机器上先起来再配模型,别让缺 .env 变成起不来
required: false # 空机器上先起来再配,别让缺 .env 变成起不来
environment:
# ---- 容器内路径:宿主 .env 里写的是 ./media、./nex_animation.db,直接透传会漂 ----
# 库落 ./data,产物落 ./media:两个挂载点各管各的,理由见文件头与 Dockerfile。
DATABASE_URL: "${APP_DATABASE_URL:-sqlite:////app/data/nex_animation.db}"
MEDIA_ROOT: "${APP_MEDIA_ROOT:-/app/media}"
# ---- 容器内永远监听 8000:端口一节写的 PORT 是「对外映射到哪个端口」,
# 不是容器里的监听端口(EXPOSE 与健康检查都按 8000 写死)。显式覆盖宿主 .env
# 注进来的那份,免得将来谁让应用直接读 PORT 时监听端口跟着漂。
PORT: "8000"
# ---- 整站形态的两把开关:后端托管前端 + 进程内执行后端,都必须在容器里成立 ----
SERVE_FRONTEND: "on"
TASK_EXECUTOR: "inline"
SERVE_FRONTEND: "on" # 后端托管 frontend/dist,对外只有一个端口
TASK_EXECUTOR: "inline" # 进程内线程池 + 派发守护线程,不需要 Redis 与独立 worker
INLINE_WORKERS: "${INLINE_WORKERS:-2}"
# ---- 账号:库里没用户时首启播种这个管理员,登录后请立刻改口令 ----
AUTH_ENABLED: "${AUTH_ENABLED:-true}"
BOOTSTRAP_USERNAME: "${BOOTSTRAP_USERNAME:-admin}"
BOOTSTRAP_PASSWORD: "${BOOTSTRAP_PASSWORD:-admin1234}"
AUTO_SEED: "${AUTO_SEED:-only-missing}"
AUTO_SEED: "${AUTO_SEED:-only-missing}" # 首启用 scripts/seed 灌模型配置:only-missing|force|off
TZ: "${TZ:-Asia/Shanghai}"
# 这里刻意没有 COMFYUI_BASE_URL / VIDEO_PROVIDER / TTS_*:模型端点存在数据库里
# (model_specs.base_url / config_json),改完立刻生效,不需要重启容器,
# 也不需要「改 .env + 改页面」两处对齐。页面路径:调度中心 → 模型中心。
ports:
# 对外只有这一个端口:.env 的 PORT(HOST_PORT 是旧键,兼容一版)
- "${PORT:-${HOST_PORT:-8000}}:8000"
- "${HOST_PORT:-8000}:8000"
volumes:
- ./data:/app/data
- ./media:/app/media
- ./scripts/seed:/app/scripts/seed:ro
- ./models:/app/models:ro
extra_hosts:
# Linux 上没有内建的 host.docker.internal,靠 host-gateway 指回宿主机。
# 自建 ComfyUI 装在宿主机时,模型中心里的 base_url 要写 http://host.docker.internal:9200
# (写 127.0.0.1 指向的是容器自己);装在局域网另一台机器就写那台的实际 IP,本条不影响。
- "host.docker.internal:host-gateway"
- "host.docker.internal:host-gateway" # 自建 ComfyUI 装宿主机时用它指回宿主
# 自建 ComfyUI(可选):docker compose --profile comfy up -d 起一份容器实例。
# 已有外部 GPU 机(例如 http://10.100.53.199:9200)时不用开它,
# 去「调度中心 → 模型中心」把三条 comfyui 模型的 base_url 改过去就行(改完即生效,无需重启);
# 装在宿主机上的话用 http://host.docker.internal:9200,指本 profile 起的容器用 http://comfyui:8188。
# 可选:在本机用容器起一份 ComfyUI。默认不参与(--profile comfy 才起),算力在远端时不用管。
comfyui:
profiles: ["comfy"]
image: comfyanonymous/comfyui:latest

View File

@ -181,10 +181,15 @@ ffmpeg 与本地听写权重)。判据是一句话:**换模型要不要重
即视为回归(`app/config.py` 仍保留这些字段,但它们是空库自检的代码级兜底,不是配置入口)。
`.env` 里**只写配置本身**:一个键最多跟一行注释,「为什么不在这里」的长篇理由写在 README 与
本节,不写进 `.env`(那份文件是运维唯一被要求编辑的,注释比配置长就没人读完它)。
写进去的键必须有明确的读取方,且**一件事只有一个键**:端口全项目就 `PORT` 一个——compose 拿它做
对外映射、`server.sh` 拿它做监听端口、`dev.sh` 拿它当开发态后端端口(只有 Vite 因为是独立进程额外
要 `FRONTEND_PORT`)。同义键是回归:曾经 `HOST_PORT` / `PORT` / `BACKEND_PORT` 三个键指同一个端口,
运维改哪个都不确定是不是改对了。优先级统一是 **命令行 > 环境变量 > `.env` > 代码默认值**。
写进去的键必须有明确的读取方,而且**一个键只能有一种含义、同一个 socket 不能有两个键**。
端口按形态分三个键,键名自带它的适用场景:`HOST_PORT` = 部署形态对外的端口(compose 插值做端口映射、
`server.sh` 回读做监听),`BACKEND_PORT` / `FRONTEND_PORT` = 开发形态的两个进程(`dev.sh` 回读)。
反面例子是两个版本里都出现过:先是有过 `HOST_PORT` / `PORT` / `BACKEND_PORT` 三个键指同一件事
(改哪个都不确定对不对),随后收敛成一个 `PORT` 又被三种形态共用(同一个键在 Docker 下指对外映射、
在裸机下指监听、在开发下指后端,不读 README 的人分不出来)。判据从来不是键的个数,是含义的唯一性。
优先级统一是 **命令行 > 环境变量 > `.env` > 代码默认值**,两个脚本都回读 `.env`——写在里面却没人读的键
同样是回归(`.env.example` 因此不再列 `SERVE_FRONTEND` 与 Postgres/Redis/Celery 那一组:前者在 Docker
形态被 compose 覆盖,后者只在叠加 `docker-compose.scale.yml` 时有人读)。
| 内容 | 怎么到新机器上 |
|---|---|

View File

@ -43,17 +43,19 @@ esac
# 本机局域网 IP(macOS:默认路由网卡 → ipconfig getifaddr),取不到就只打印回环地址。
LAN_IP="$( { iface="$(route -n get default 2>/dev/null | awk '/^[[:space:]]*interface:/{print $2; exit}')"
[ -n "$iface" ] && ipconfig getifaddr "$iface" 2>/dev/null; } || true )"
env_value() { # 从仓库根 .env 读一个键(最后一行为准,去引号/去空白)
env_value() { # 从仓库根 .env 读一个键(最后一行为准;去引号、去随行注释、去尾部空白)
[ -f "$ROOT/.env" ] || return 0
sed -n "s/^[[:space:]]*$1=//p" "$ROOT/.env" | tail -1 | tr -d '\r"'"'"'' || true
sed -n "s/^[[:space:]]*$1=//p" "$ROOT/.env" | tail -1 \
| sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//' | tr -d '\r"'"'"'' || true
}
# 全项目只有 PORT 这一个端口键,开发态的后端就是它(Vite 是独立进程,才需要 FRONTEND_PORT
# 这第二个端口)。取值优先级:命令行 --backend-port/--frontend-port > 同名环境变量 > .env > 默认值,
# 和 scripts/server.sh 是同一条约定:.env 是运维唯一被要求编辑的文件,写进去的必须真的生效
# 开发形态两个进程各一个键:BACKEND_PORT(uvicorn)/ FRONTEND_PORT(Vite)。
# 部署形态的对外端口是另一个键 HOST_PORT,跟这里无关(见 .env.example 的端口一节)。
# 取值优先级:命令行 --backend-port/--frontend-port > 同名环境变量 > .env > 默认值,
# 和 scripts/server.sh 是同一条约定:.env 写进去的键必须真的生效
# (后端换端口时下面还会把 NEX_BACKEND 一起带着走,代理不会掉队)。
BACKEND_PORT="${BACKEND_PORT:-${PORT:-$(env_value PORT)}}"
BACKEND_PORT="${BACKEND_PORT:-$(env_value BACKEND_PORT)}" # 旧键兼容
BACKEND_PORT="${BACKEND_PORT:-$(env_value BACKEND_PORT)}"
BACKEND_PORT="${BACKEND_PORT:-$(env_value PORT)}" # 旧键兼容
BACKEND_PORT="${BACKEND_PORT:-8000}"
FRONTEND_PORT="${FRONTEND_PORT:-$(env_value FRONTEND_PORT)}"
FRONTEND_PORT="${FRONTEND_PORT:-5173}"

View File

@ -40,18 +40,20 @@ RUN_DIR="$ROOT/.local/run"
LOG_DIR="$ROOT/.local/logs"
PYBIN="$ROOT/.venv/bin/python"
NAME=server
env_value() { # 从仓库根 .env 读一个键(最后一行为准,去引号/去空白)
env_value() { # 从仓库根 .env 读一个键(最后一行为准;去引号、去随行注释、去尾部空白)
[ -f "$ROOT/.env" ] || return 0
sed -n "s/^[[:space:]]*$1=//p" "$ROOT/.env" | tail -1 | tr -d '\r"'"'"'' || true
sed -n "s/^[[:space:]]*$1=//p" "$ROOT/.env" | tail -1 \
| sed -E 's/[[:space:]]+#.*$//; s/[[:space:]]+$//' | tr -d '\r"'"'"'' || true
}
HOST="${NEX_HOST:-0.0.0.0}"
# 全项目只有 PORT 这一个端口键:Docker 对外的映射、开发态的后端也都读它(见 .env.example)。
# 取值优先级:命令行 --port > 环境变量 PORT > .env 里的 PORT > 8000。
# 回读 .env 是有意的:运维习惯把端口写进 .env(那是他唯一被要求编辑的文件),
# 而以前这里只认命令行与环境变量,表现就是「.env 明明改了 9000,服务还在 8000」。
PORT="${PORT:-$(env_value PORT)}"
PORT="${PORT:-$(env_value HOST_PORT)}" # 旧键:早期 .env.example 让裸机也写 HOST_PORT
# 部署形态的对外端口只有一个键: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
PORT="${PORT:-8000}"
ASR_MODEL="$ROOT/models/asr/ggml-small.bin"
ASR_URL="https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin"
@ -175,8 +177,8 @@ ensure_env() {
# 改完重启生效:./scripts/server.sh restart
# 模型配置不在这里:库里的「调度中心 → 模型中心」改,改完即生效,不用重启服务。
# ---- 端口:本服务对外监听的端口(restart 后生效)----
PORT=8000
# ---- 端口:对外暴露的端口(restart 后生效)----
HOST_PORT=8000
# ---- 存储:单机用 SQLite,媒体落 ./media ----
DATABASE_URL=sqlite:///./nex_animation.db